danvics/ytdl-sub
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[DOCS] logs: persistent logs config (#1304)

Browse source 
* 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).
This commit is contained in:
Ross Patterson 2025-08-27 09:04:36 -07:00 committed by GitHub
parent 26922e1787
commit abd75f8005
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 45 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
docs/source/config_reference/config_yaml.rst
View file

@ -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

30
docs/source/usage.rst
View file

@ -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.

6
examples/advanced/tv_show_config.yaml
View file

@ -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
only_recent_max_files: 30

25
src/ytdl_sub/config/config_validator.py
View file

@ -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