From abd75f800518da3283b798c38a45022c68527d65 Mon Sep 17 00:00:00 2001 From: Ross Patterson Date: Wed, 27 Aug 2025 09:04:36 -0700 Subject: [PATCH] [DOCS] logs: persistent logs config (#1304) * docs(logs): Mimick argparse option default format I find it more readable to use punctuation to separate technical information, such as required vs optional or default values, from narrative description. Follow argparse's lead, and put such information in parens following the narrative description. * docs(usage): Consistent structure, clarifications * docs(config): Clarify persist_logs behavior/opts Clarify the `persist_logs:` options per [Discord discussion](https://discord.com/channels/994270357957648404/1409161361853780060/1409602529460879431). --- docs/source/config_reference/config_yaml.rst | 16 +++++++---- docs/source/usage.rst | 30 +++++++++++--------- examples/advanced/tv_show_config.yaml | 6 ++-- src/ytdl_sub/config/config_validator.py | 25 +++++++++------- 4 files changed, 45 insertions(+), 32 deletions(-) diff --git a/docs/source/config_reference/config_yaml.rst b/docs/source/config_reference/config_yaml.rst index 6c065bc9..6955c386 100644 --- a/docs/source/config_reference/config_yaml.rst +++ b/docs/source/config_reference/config_yaml.rst @@ -33,8 +33,17 @@ subscriptions. persist_logs ~~~~~~~~~~~~ -Within ``configuration``, define whether logs from subscription downloads should be -persisted. +Without this key, ``ytdl-sub`` only prints output to it's ``stdout`` and ``stderr``. If +your configuration includes the ``persist_logs:`` key, then ``ytdl-sub`` also writes log +files to disk. + +.. warning:: + + The log files grow rapidly if ``keep_successful_logs:`` is ``true``, the default, and + may fill up disk space. Set ``keep_successful_logs: false`` or prune the log files + regularly. + +For example: .. code-block:: yaml @@ -42,9 +51,6 @@ persisted. persist_logs: logs_directory: "/path/to/log/directory" -Log files are stored as -``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``. - .. autoclass:: ytdl_sub.config.config_validator.PersistLogsValidator() :members: :member-order: bysource diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 68f45651..8f828858 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -11,14 +11,15 @@ For Windows users, it would be ``ytdl-sub.exe`` General Options --------------- -General options must be specified before the command (i.e. ``sub``). +CLI options common to all sub-commands. Must be specified before the sub-command, for +example ``$ ytdl-sub --dry-run sub ...``: .. code-block:: text -h, --help show this help message and exit -v, --version show program's version number and exit -c CONFIGPATH, --config CONFIGPATH - path to the config yaml, uses config.yaml if not provided + path to the config yaml, uses ./config.yaml if not provided -d, --dry-run preview what a download would output, does not perform any video downloads or writes to output directories -l quiet|info|verbose|debug, --log-level quiet|info|verbose|debug level of logs to print to console, defaults to info @@ -30,18 +31,19 @@ General options must be specified before the command (i.e. ``sub``). match subscription names to one or more substrings, and only run those subscriptions -Sub Options ------------ +Subscriptions Options +--------------------- -Download all subscriptions specified in each ``SUBPATH``. +Download all subscriptions specified in each :doc:`subscriptions file +<./guides/getting_started/first_sub>`. .. code-block:: ytdl-sub [GENERAL OPTIONS] sub [SUBPATH ...] -``SUBPATH`` is one or more paths to subscription files, uses ``subscriptions.yaml`` if -not provided. It will use the config specified by ``--config``, or ``config.yaml`` if -not provided. +``SUBPATH`` is one or more paths to subscription files and defaults to +``./subscriptions.yaml`` if none are given. It will use the config specified by +``--config``, or ``./config.yaml``, if not provided. .. code-block:: text :caption: Additional Options @@ -55,15 +57,15 @@ not provided. Download Options ---------------- -Download a single subscription in the form of CLI arguments. +Download a single subscription in the form of CLI arguments instead of from :doc:`a +subscriptions file <./guides/getting_started/first_sub>`: .. code-block:: ytdl-sub [GENERAL OPTIONS] dl [SUBSCRIPTION ARGUMENTS] -``SUBSCRIPTION ARGUMENTS`` are exactly the same as YAML arguments, but use periods -(``.``) instead of indents for specifying YAML from the CLI. For example, you can -represent this subscription: +``SUBSCRIPTION ARGUMENTS`` are the same as YAML arguments, but use periods (``.``) +instead of indents. For example, you can represent this subscription: .. code-block:: yaml @@ -90,6 +92,8 @@ See how to shorten commands using `download aliases View Options ------------ +Preview the source variables for a given URL. Helpful to create new subscriptions: + .. code-block:: ytdl-sub view [-sc] [URL] @@ -99,5 +103,3 @@ View Options -sc, --split-chapters View source variables after splitting by chapters - -Preview the source variables for a given URL. Helps when creating new configs. diff --git a/examples/advanced/tv_show_config.yaml b/examples/advanced/tv_show_config.yaml index 9cfa4ca7..d2019b9a 100644 --- a/examples/advanced/tv_show_config.yaml +++ b/examples/advanced/tv_show_config.yaml @@ -1,9 +1,9 @@ ############################################################################### -# Top-level configurations to apply umask and persist error logs +# Top-level configurations to apply umask and write log files configuration: umask: "002" persist_logs: - logs_directory: './logs' + logs_directory: '/config/logs' keep_successful_logs: False presets: @@ -98,4 +98,4 @@ presets: overrides: only_recent_date_range: "2months" - only_recent_max_files: 30 \ No newline at end of file + only_recent_max_files: 30 diff --git a/src/ytdl_sub/config/config_validator.py b/src/ytdl_sub/config/config_validator.py index 55a91f55..b5d234a9 100644 --- a/src/ytdl_sub/config/config_validator.py +++ b/src/ytdl_sub/config/config_validator.py @@ -67,7 +67,8 @@ class PersistLogsValidator(StrictDictValidator): @property def logs_directory(self) -> str: """ - Required. The directory to store the logs in. + Write log files to this directory with names like + ``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``. (required) """ return self._logs_directory.value @@ -92,7 +93,10 @@ class PersistLogsValidator(StrictDictValidator): @property def keep_successful_logs(self) -> bool: """ - Optional. Whether to store logs when downloading is successful. Defaults to True. + If the ``persist_logs:`` key is in the configuration, then ``ytdl-sub`` *always* + writes log files for the subscription both for successful downloads and when it + encounters an error while downloading. When this key is ``False``, only write + log files for errors. (default ``True``) """ return self._keep_successful_logs.value @@ -147,7 +151,7 @@ class ConfigOptions(StrictDictValidator): def working_directory(self) -> str: """ The directory to temporarily store downloaded files before moving them into their final - directory. Defaults to .ytdl-sub-working-directory + directory. (default ``./.ytdl-sub-working-directory``) """ # Expands tildas to actual paths, use native os sep return os.path.expanduser(self._working_directory.value.replace(posixpath.sep, os.sep)) @@ -155,7 +159,7 @@ class ConfigOptions(StrictDictValidator): @property def umask(self) -> Optional[str]: """ - Umask (octal format) to apply to every created file. Defaults to "022". + Umask in octal format to apply to every created file. (default ``022``) """ return self._umask.value @@ -214,24 +218,25 @@ class ConfigOptions(StrictDictValidator): def lock_directory(self) -> str: """ The directory to temporarily store file locks, which prevents multiple instances - of ``ytdl-sub`` from running. Note that file locks do not work on network-mounted - directories. Ensure that this directory resides on the host machine. Defaults to ``/tmp``. + of ``ytdl-sub`` from running. Note that file locks do not work on + network-mounted directories. Ensure that this directory resides on the host + machine. (default ``/tmp``) """ return self._lock_directory.value @property def ffmpeg_path(self) -> str: """ - Path to ffmpeg executable. Defaults to ``/usr/bin/ffmpeg`` for Linux, and - ``ffmpeg.exe`` for Windows (in the same directory as ytdl-sub). + Path to ffmpeg executable. (default ``/usr/bin/ffmpeg`` for Linux, + ``./ffmpeg.exe`` in the same directory as ytdl-sub for Windows) """ return self._ffmpeg_path.value @property def ffprobe_path(self) -> str: """ - Path to ffprobe executable. Defaults to ``/usr/bin/ffprobe`` for Linux, and - ``ffprobe.exe`` for Windows (in the same directory as ytdl-sub). + Path to ffprobe executable. (default ``/usr/bin/ffprobe`` for Linux, + ``./ffprobe.exe`` in the same directory as ytdl-sub for Windows) """ return self._ffprobe_path.value