update yamls with preset reuse

docs/config.rst

@@ -131,6 +131,18 @@ nfo_output_directory
   :members:
   :member-order: bysource
 
+-------------------------------------------------------------------------------
+
+subscription.yaml
+-----------------
+The ``subscription.yaml`` file is where we use our `presets`_ in the `config.yaml`_
+to define a `subscription`: something we want to recurrently download such as a specific
+channel or playlist.
+
+The subscription file looks nearly identical to the `presets`_ section with a few
+exceptions. TODO: work in progress!
+
+
 -------------------------------------------------------------------------------
 
 .. _source-variables:

examples/kodi_music_videos_config.yaml

@@ -16,7 +16,7 @@ configuration:
   working_directory: '.ytdl-sub-downloads'
 
 presets:
-  yt_music_video:
+  yt_music_video_playlist:
     # Youtube playlists are our source/download strategy. However, this
     # can be overwritten to download music videos from a 'channel' or a
     # single 'video'
@@ -66,3 +66,11 @@ presets:
     overrides:
       music_video_directory: "path/to/Music Videos"
       music_video_name: "{sanitized_artist} - {sanitized_title}"
+
+  # It is not always ideal to download all of an artist's music videos.
+  # Maybe you only like one song of theirs. We can reuse our preset above
+  # to download a single video instead.
+  yt_music_video:
+    preset: "yt_music_video_playlist"
+    youtube:
+      download_strategy: "video"

examples/kodi_music_videos_subscriptions.yaml

@@ -12,7 +12,7 @@
 john_smith:
   # We must define a preset to use from our config. We named the one in the
   # config example "yt_music_video", so set that here.
-  preset: "yt_music_video"
+  preset: "yt_music_video_playlist"
 
   # Since our preset download strategy is set to 'playlist', set the playlist id.
   youtube:
@@ -37,9 +37,8 @@ john_smith:
 # to download a single video instead.
 #
 # The only difference between this example and the one above is
-# - youtube.download_strategy
+# - preset
-#     We defined this as 'playlist' in the config. We must override it
+#     Use the music video preset, not the playlist preset
-#     with 'video' to perform a single video download
 # - youtube.video_id
 #     The id of the video to download
 #
@@ -48,18 +47,13 @@ john_smith:
 # command:
 #
 #     ytdl-sub dl                                                     \
-#         --preset "yt_channel_as_tv"                                 \
+#         --preset "yt_music_video"                                   \
-#         --youtube.download_strategy "video"                         \
 #         --youtube.video_id "QhY6r6oAErg"                            \
 #         --overrides.artist "John Smith and the Instrument Players"
 #
-# The --preset and --youtube.download_strategy args will always be the
-# same. We will try to simplify the dl command to make it shorter.
-
 john_smith_one_hit_wonder:
-  preset: "yt_channel_as_tv"
+  preset: "yt_music_video"
   youtube:
-    download_strategy: "video"
     video_id: "QhY6r6oAErg"
   overrides:
     artist: "John Smith and the Instrument Players"

examples/kodi_tv_shows_config.yaml

@@ -20,8 +20,14 @@ configuration:
   working_directory: '.ytdl-sub-downloads'
 
 presets:
+
+  ###############################################################################
+  # LEVEL 1 - FULL ARCHIVE
+  #
+  # We will call this preset `yt_channel_as_tv`, and it will download every single video in
+  # a YouTube channel.
   yt_channel_as_tv:
-    # Youtube channels are our source/download strategy
+    # YouTube channels are our source/download strategy
     # Use the channel avatar and banner images for Kodi
     youtube:
       download_strategy: "channel"
@@ -82,3 +88,53 @@ presets:
     overrides:
       youtube_tv_shows_directory: "/path/to/youtube_tv_shows"
       episode_name: "Season {upload_year}/s{upload_year}.e{upload_month_padded}{upload_day_padded} - {sanitized_title}"
+
+  ###############################################################################
+  # LEVEL 2 - RECENT ARCHIVE
+  #
+  # It is not always ideal to go full data-hoarder on a channel's videos.
+  # This example shows how you can only download the last 14 days-worth
+  # of videos on each download invocation.
+  yt_channel_as_tv__recent:
+    # `preset` can be set to any other preset in the config, and will inherit all its defined fields.
+    # This helps reduce copy-paste in the config.yaml
+    preset: "yt_channel_as_tv"
+
+    # We will add the `after` field onto `yt_channel_as_tv`'s YouTube channel download strategy.
+    # This is saying 'only download videos uploaded in the last 2 weeks'
+    youtube:
+      after: "today-2weeks"
+
+    # This is getting into YTDL voodoo. By default, YTDL will try to
+    # download all channel videos beginning with the most recent one.
+    # By setting break_on_reject, we will break this full-download on
+    # the first video that gets rejected. Since we have youtube.after
+    # defined, all videos after today-14days will be rejected. Therefore,
+    # the first video that is out of range that it tries to download, it
+    # will stop there, and save a significant amount of time.
+    #
+    # Similar to break_on_reject, but instead, breaks if a video has
+    # already been downloaded. If you were to perform a download on this
+    # subscription one-after-the-other, the second invocation would stop
+    # after looking at the first (most recent) video since it would exist
+    # in the download archive.
+    ytdl_options:
+      break_on_reject: True
+      break_on_existing: True
+
+  ###############################################################################
+  # LEVEL 3 - ROLLING ARCHIVE
+
+  # If you put the recent archive example in a cron job, then in a year or so
+  # you will basically be datahoarding that channel unless you manually delete
+  # old videos. This example shows how to only keep the last 14-days worth of videos,
+  # and delete the rest.
+  yt_channel_as_tv__only_recent:
+    # Reuse `yt_channel_as_tv__recent` to only download the last 2 weeks' of videos
+    preset: "yt_channel_as_tv__recent"
+
+    # This is saying "only keep files if they were uploaded in the last 2 weeks".
+    # All other files that this subscription had previously downloaded will be
+    # deleted.
+    output_options:
+      keep_files_after: "today-2weeks"

examples/kodi_tv_shows_subscriptions.yaml

@@ -4,13 +4,13 @@
 
 ###############################################################################
 # LEVEL 1 - FULL ARCHIVE
-
+#
 # Subscription names are defined by you. We will call this one
 # john_smith_archive because it will download every single video in
 # john_smith's channel.
 john_smith_archive:
-  # We must define a preset to use from our config. We named the one in the
+  # We must define a preset to use from our config. The one that downloads the
-  # config example "yt_channel_as_tv", so set that here.
+  # entire YouTube channel is called "yt_channel_as_tv", so set that here.
   preset: "yt_channel_as_tv"
 
   # Our download strategy was Youtube channels. Define the channel id here
@@ -28,61 +28,24 @@ john_smith_archive:
 
 ###############################################################################
 # LEVEL 2 - RECENT ARCHIVE
-
-# It is not always ideal to go full datahoarder on a channel's videos.
-# This example shows how you can only download the last 14 days-worth
-# of videos on each download invocation.
 #
-# The only difference between this example and the one above is
+# Use the "yt_channel_as_tv__recent" preset to only download the last two
-# - youtube.after
+# weeks' worth of YouTube videos.
-#     This is saying 'only download videos in the last 14 days'
-# - ytdl_options.break_on_reject
-#     This is getting into YTDL voodoo. By default, YTDL will try to
-#     download all channel videos beginning with the most recent one.
-#     By setting break_on_reject, we will break this full-download on
-#     the first video that gets rejected. Since we have youtube.after
-#     defined, all videos after today-14days will be rejected. Therefore,
-#     the first video that is out of range that it tries to download, it
-#     will stop there, and save a significant amount of time.
-# - ytdl_options.break_on_existing
-#     Similar to break_on_reject, but instead, breaks if a video has
-#     already been downloaded. If you were to perform a download on this
-#     subscription one-after-the-other, the second invocation would stop
-#     after looking at the first (most recent) video since it would exist
-#     in the download archive.
 john_smith_recent_archive:
-  preset: "yt_channel_as_tv"
+  preset: "yt_channel_as_tv__recent"
   youtube:
     channel_id: "UCsvn_Po0SmunchJYtttWpOxMg"
-    after: today-14days
   overrides:
     tv_show_name: "John /\ Smith"
-  ytdl_options:
-    break_on_reject: True
-    break_on_existing: True
 
 ###############################################################################
 # LEVEL 3 - ROLLING ARCHIVE
-
-# If you put the recent archive example in a cron job, then in a year or so
-# you will basically be datahoarding that channel unless you manually delete
-# old videos. We automate because we are lazy. This example shows how to
-# only keep the last 14-days worth of videos, and delete the rest.
 #
-# The only difference between this example and the one above is
+# Use the "yt_channel_as_tv__recent_only" preset to only download the last two
-# - output_options.keep_files_after
+# weeks' worth of YouTube videos, and delete any existing older videos.
-#     This is saying "only keep files if they were uploaded in the last 14 days".
-#     All other files that this subscription had previously downloaded will be
-#     deleted.
 john_smith_rolling_archive:
-  preset: "yt_channel_as_tv"
+  preset: "yt_channel_as_tv__only_recent"
   youtube:
     channel_id: "UCsvn_Po0SmunchJYtttWpOxMg"
-    after: today-2weeks
   overrides:
-    tv_show_name: "John /\ Smith"
+    tv_show_name: "John /\ Smith"
-  ytdl_options:
-    break_on_reject: True
-    break_on_existing: True
-  output_options:
-    keep_files_after: today-2weeks

tests/e2e/youtube/test_channel_as_kodi_tv_show.py

@@ -139,11 +139,8 @@ def recent_channel_subscription_dict(subscription_dict):
     return mergedeep.merge(
         subscription_dict,
         {
+            "preset": "yt_channel_as_tv__recent",
             "youtube": {"after": "20150101"},
-            "ytdl_options": {
-                "break_on_reject": True,
-                "break_on_existing": True,
-            },
         },
     )
 
@@ -194,7 +191,11 @@ def expected_recent_channel_download():
 @pytest.fixture
 def rolling_recent_channel_subscription_dict(recent_channel_subscription_dict):
     return mergedeep.merge(
-        recent_channel_subscription_dict, {"output_options": {"keep_files_after": "20181101"}}
+        recent_channel_subscription_dict,
+        {
+            "preset": "yt_channel_as_tv__only_recent",
+            "output_options": {"keep_files_after": "20181101"},
+        },
     )