From 42f2b650c93abc2be2a2bd816d4b64b6205e6075 Mon Sep 17 00:00:00 2001 From: jbannon Date: Sat, 7 May 2022 05:19:33 +0000 Subject: [PATCH] done for now --- docs/config.rst | 67 +++++++++++++++++---------- src/ytdl_sub/config/preset_options.py | 62 +++++++++++++++++++++---- 2 files changed, 95 insertions(+), 34 deletions(-) diff --git a/docs/config.rst b/docs/config.rst index 0ba8be35..056b8abe 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -1,28 +1,32 @@ Config ====== -ytdl-sub is configured in the ``config.yaml`` and consists of two sections: +ytdl-sub is configured using a ``config.yaml`` file. You can view our +:doc:`examples ` and read detailed documentation for every configurable +field below. + +The ``config.yaml`` is made up of two sections: .. code-block:: yaml configuration: presets: +You can jump to any section and subsection of the config using the navigation +section to the left. configuration ------------- - -The ``configuration`` section contains app-wide configs. +The ``configuration`` section contains app-wide configs applied to all presets +and subscriptions. presets ------- - ``presets`` define a `formula` for how to format downloaded media and metadata. -download strategy +download_strategy ^^^^^^^^^^^^^^^^^ -Download strategies dictate what exactly is getting downloaded from which -source. By having separate strategies, we can define strategy-dependent -parameters to better fine-tune how we download things. +Download strategies dictate what is getting downloaded from a source. Each +download strategy has its own set of parameters. youtube """"""" @@ -56,7 +60,7 @@ after _____ .. autoproperty:: ytdl_sub.downloaders.youtube_downloader.YoutubeChannelDownloaderOptions.after --------- +------------------------------------------------------------------------------- playlist '''''''' @@ -71,7 +75,7 @@ playlist_id ___________ .. autoproperty:: ytdl_sub.downloaders.youtube_downloader.YoutubePlaylistDownloaderOptions.playlist_id --------- +------------------------------------------------------------------------------- video ''''' @@ -86,7 +90,7 @@ video_id ________ .. autoproperty:: ytdl_sub.downloaders.youtube_downloader.YoutubeVideoDownloaderOptions.video_id --------- +------------------------------------------------------------------------------- soundcloud """""""""" @@ -108,7 +112,7 @@ skip_premiere_tracks ____________________ .. autoproperty:: ytdl_sub.downloaders.soundcloud_downloader.SoundcloudAlbumsAndSinglesDownloadOptions.skip_premiere_tracks --------- +------------------------------------------------------------------------------- output_options ^^^^^^^^^^^^^^ @@ -133,40 +137,40 @@ keep_files """""""""" .. autoproperty:: ytdl_sub.config.preset_options.OutputOptions.keep_files +------------------------------------------------------------------------------- + ytdl_options ^^^^^^^^^^^^ -.. autoclass:: ytdl_sub.config.preset_options.YTDLOptions +.. autoclass:: ytdl_sub.config.preset_options.YTDLOptions() + +------------------------------------------------------------------------------- overrides ^^^^^^^^^ -.. autoclass:: ytdl_sub.config.preset_options.Overrides +.. autoclass:: ytdl_sub.config.preset_options.Overrides() Plugins ^^^^^^^ music_tags """""""""" -TODO +.. autoclass:: ytdl_sub.plugins.music_tags.MusicTagsOptions() nfo """ -TODO +.. autoclass:: ytdl_sub.plugins.nfo_tags.NfoTagsOptions() nfo_output_directory """""""""""""""""""" -TODO +.. autoclass:: ytdl_sub.plugins.output_directory_nfo_tags.OutputDirectoryNfoTagsOptions() -Format Variables +Source Variables ---------------- -Format variables are ``{variables}`` that contain metadata from downloaded -media. - -.. contents:: Source Format Variables - :local: +Source variables are ``{variables}`` that contain metadata from downloaded media. +These variables can be used in StringFormatters, but not OverrideFormatters. Youtube Variables ^^^^^^^^^^^^^^^^^ - .. automodule:: ytdl_sub.entries.variables.youtube_variables :members: :inherited-members: @@ -174,8 +178,21 @@ Youtube Variables Soundcloud Variables ^^^^^^^^^^^^^^^^^^^^ - .. automodule:: ytdl_sub.entries.variables.soundcloud_variables :members: :inherited-members: :undoc-members: + +Formatters +---------- +Formatters are strings that can contain ``{variables}`` that are overwritten at +run-time with values assigned to that variable. There are two different types of +formatters. + +String Formatter +^^^^^^^^^^^^^^^^ +.. autoclass:: ytdl_sub.validators.string_formatter_validators.StringFormatterValidator() + +Overrides Formatter +^^^^^^^^^^^^^^^^^^^ +.. autoclass:: ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator() diff --git a/src/ytdl_sub/config/preset_options.py b/src/ytdl_sub/config/preset_options.py index d2af9466..ca827c97 100644 --- a/src/ytdl_sub/config/preset_options.py +++ b/src/ytdl_sub/config/preset_options.py @@ -13,12 +13,52 @@ from ytdl_sub.validators.validators import LiteralDictValidator class YTDLOptions(LiteralDictValidator): - """Ensures `ytdl_options` is a dict""" + """ + Optional. This section allows you to add any ytdl argument to ytdl-sub's downloader. + The argument names can differ slightly from the command-line argument names. See + `this docstring `_ + for more details. + + ytdl_options should be formatted like: + + .. code-block:: yaml + + presets: + my_example_preset: + ytdl_options: + ignoreerrors: True + + where each key is a ytdl argument. + """ +# Disable for proper docstring formatting +# pylint: disable=line-too-long class Overrides(DictFormatterValidator): - """Ensures `overrides` is a dict""" + """ + Optional. This section allows you to define variables that can be used in any string formatter. + For example, if you want your file and thumbnail files to match without copy-pasting a large + format string, you can define something like: + .. code-block:: yaml + + presets: + my_example_preset: + overrides: + output_directory: "/path/to/media" + custom_file_name: "{upload_year}.{upload_month_padded}.{upload_day_padded}.{sanitized_title}" + + # Then use the override variables in the output options + output_options: + output_directory: "{output_directory}" + file_name: "{custom_file_name}.{ext}" + thumbnail_name: "{custom_file_name}.{thumbnail_ext}" + + Override variables can contain explicit values and other variables, including both override + and source variables. + """ + + # pylint: enable=line-too-long def __init__(self, name, value): super().__init__(name, value) for key in self._keys: @@ -132,19 +172,23 @@ class OutputOptions(StrictDictValidator): .. code-block:: yaml - output_options: - keep_files: - before: - after: + presets: + my_example_preset: + output_options: + keep_files: + before: + after: where ``before`` and ``after`` are date-times. A common usage of this option is to only fill in the after, such as: .. code-block:: yaml - output_options: - keep_files: - after: today-2weeks + presets: + my_example_preset: + output_options: + keep_files: + after: today-2weeks Which translates to 'keep files uploaded in the last two weeks'.