docs docs more docs
This commit is contained in:
jbannon
parent
f9979521ac
commit
20d376b5a1
5 changed files with 98 additions and 35 deletions
|
|
@ -61,3 +61,7 @@ add_module_names = False
|
|||
python_use_unqualified_type_names = False
|
||||
napoleon_numpy_docstrings = True
|
||||
napoleon_use_rtype = False
|
||||
|
||||
# -- Options for autodocs -------------------------------------------------
|
||||
|
||||
autodoc_default_options = {"autodoc_typehints_format": "short"}
|
||||
|
|
|
|||
|
|
@ -4,6 +4,9 @@ ytdl-sub is configured using a ``config.yaml`` file. You can view our
|
|||
:doc:`examples <examples>` and read detailed documentation for every configurable
|
||||
field below.
|
||||
|
||||
config.yaml
|
||||
-----------
|
||||
|
||||
The ``config.yaml`` is made up of two sections:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -15,28 +18,28 @@ 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 applied to all presets
|
||||
and subscriptions.
|
||||
|
||||
presets
|
||||
-------
|
||||
^^^^^^^
|
||||
``presets`` define a `formula` for how to format downloaded media and metadata.
|
||||
|
||||
download_strategy
|
||||
^^^^^^^^^^^^^^^^^
|
||||
"""""""""""""""""
|
||||
Download strategies dictate what is getting downloaded from a source. Each
|
||||
download strategy has its own set of parameters.
|
||||
|
||||
youtube
|
||||
"""""""
|
||||
'''''''
|
||||
Download strategies for downloading videos (or audio if you configure `ytdl_options`_ correctly) from Youtube. See
|
||||
Download strategies for downloading music from Soundcloud. See
|
||||
:class:`Youtube Variables <ytdl_sub.entries.variables.youtube_variables>`
|
||||
for available source variables to use.
|
||||
|
||||
channel
|
||||
'''''''
|
||||
_______
|
||||
.. autoclass:: ytdl_sub.downloaders.youtube_downloader.YoutubeChannelDownloaderOptions()
|
||||
:members:
|
||||
:member-order: bysource
|
||||
|
|
@ -46,7 +49,7 @@ channel
|
|||
-------------------------------------------------------------------------------
|
||||
|
||||
playlist
|
||||
''''''''
|
||||
________
|
||||
.. autoclass:: ytdl_sub.downloaders.youtube_downloader.YoutubePlaylistDownloaderOptions()
|
||||
:members:
|
||||
:member-order: bysource
|
||||
|
|
@ -55,7 +58,7 @@ playlist
|
|||
-------------------------------------------------------------------------------
|
||||
|
||||
video
|
||||
'''''
|
||||
_____
|
||||
.. autoclass:: ytdl_sub.downloaders.youtube_downloader.YoutubeVideoDownloaderOptions()
|
||||
:members:
|
||||
:member-order: bysource
|
||||
|
|
@ -64,13 +67,13 @@ video
|
|||
-------------------------------------------------------------------------------
|
||||
|
||||
soundcloud
|
||||
""""""""""
|
||||
''''''''''
|
||||
Download strategies for downloading music from Soundcloud. See
|
||||
:class:`Soundcloud Variables <ytdl_sub.entries.variables.soundcloud_variables>`
|
||||
for available source variables to use.
|
||||
|
||||
albums_and_singles
|
||||
''''''''''''''''''
|
||||
__________________
|
||||
.. autoclass:: ytdl_sub.downloaders.soundcloud_downloader.SoundcloudAlbumsAndSinglesDownloadOptions()
|
||||
:members:
|
||||
:member-order: bysource
|
||||
|
|
@ -79,7 +82,7 @@ albums_and_singles
|
|||
-------------------------------------------------------------------------------
|
||||
|
||||
output_options
|
||||
^^^^^^^^^^^^^^
|
||||
""""""""""""""
|
||||
|
||||
.. autoclass:: ytdl_sub.config.preset_options.OutputOptions()
|
||||
:members:
|
||||
|
|
@ -88,38 +91,55 @@ output_options
|
|||
-------------------------------------------------------------------------------
|
||||
|
||||
ytdl_options
|
||||
^^^^^^^^^^^^
|
||||
""""""""""""
|
||||
.. autoclass:: ytdl_sub.config.preset_options.YTDLOptions()
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
.. _overrides:
|
||||
|
||||
overrides
|
||||
^^^^^^^^^
|
||||
"""""""""
|
||||
.. autoclass:: ytdl_sub.config.preset_options.Overrides()
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
|
||||
Plugins
|
||||
^^^^^^^
|
||||
"""""""
|
||||
Plugins are used to perform any type of post-processing to the already downloaded files.
|
||||
|
||||
music_tags
|
||||
""""""""""
|
||||
''''''''''
|
||||
.. autoclass:: ytdl_sub.plugins.music_tags.MusicTagsOptions()
|
||||
:members:
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
nfo
|
||||
"""
|
||||
'''
|
||||
.. autoclass:: ytdl_sub.plugins.nfo_tags.NfoTagsOptions()
|
||||
:members:
|
||||
:member-order: bysource
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
nfo_output_directory
|
||||
""""""""""""""""""""
|
||||
''''''''''''''''''''
|
||||
.. autoclass:: ytdl_sub.plugins.output_directory_nfo_tags.OutputDirectoryNfoTagsOptions()
|
||||
:members:
|
||||
:member-order: bysource
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
.. _source-variables:
|
||||
|
||||
Source Variables
|
||||
----------------
|
||||
Source variables are ``{variables}`` that contain metadata from downloaded media.
|
||||
These variables can be used in StringFormatters, but not OverrideFormatters.
|
||||
|
||||
.. autoclass:: ytdl_sub.entries.variables.entry_variables.SourceVariables
|
||||
|
||||
.. _youtube-variables:
|
||||
|
||||
Youtube Variables
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
|
@ -128,6 +148,8 @@ Youtube Variables
|
|||
:inherited-members:
|
||||
:undoc-members:
|
||||
|
||||
.. _soundcloud-variables:
|
||||
|
||||
Soundcloud Variables
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
.. automodule:: ytdl_sub.entries.variables.soundcloud_variables
|
||||
|
|
@ -135,16 +157,18 @@ Soundcloud Variables
|
|||
: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.
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
Config Types
|
||||
------------
|
||||
The `config.yaml`_ uses various types for its configurable fields. Below is a definition for each type.
|
||||
|
||||
String Formatter
|
||||
^^^^^^^^^^^^^^^^
|
||||
.. autoclass:: ytdl_sub.validators.string_formatter_validators.StringFormatterValidator()
|
||||
|
||||
Overrides Formatter
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
.. autoclass:: ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator()
|
||||
|
||||
.. autoclass:: ytdl_sub.validators.string_datetime.StringDatetimeValidator()
|
||||
|
||||
.. autoclass:: ytdl_sub.validators.string_formatter_validators.DictFormatterValidator()
|
||||
|
||||
.. autoclass:: ytdl_sub.validators.string_formatter_validators.OverridesDictFormatterValidator()
|
||||
|
|
@ -2,20 +2,20 @@ ytdl-sub: to enjoy media in your favorite player
|
|||
================================================
|
||||
|
||||
ytdl-sub is an `open-source <https://github.com/jmbannon/ytdl-sub>`_
|
||||
python app that strives to automate downloading media and preparing it for
|
||||
python app that automates downloading media and preparing it for
|
||||
consumption in your favorite media player in the most hassle-free way
|
||||
possible.
|
||||
|
||||
If you are new to ytdl-sub, head over to the
|
||||
:doc:`Getting Started <getting_started>`
|
||||
page. This guide shows how you can install ytdl-sub, configure it to download
|
||||
page. This guide explains how you can use ytdl-sub, install, configure it to download
|
||||
various types of media, and start downloading.
|
||||
|
||||
Contents
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 10
|
||||
:maxdepth: 2
|
||||
|
||||
getting_started
|
||||
config
|
||||
|
|
|
|||
|
|
@ -9,9 +9,13 @@ from ytdl_sub.entries.base_entry import BaseEntry
|
|||
# pylint: disable=no-member
|
||||
|
||||
|
||||
class BaseEntryVariables:
|
||||
class SourceVariables:
|
||||
"""
|
||||
Abstract entry object to represent usable variables for formatting presets and subscriptions
|
||||
Source variables are ``{variables}`` that contain metadata from downloaded media.
|
||||
These variables can be used with fields that expect
|
||||
:class:`~ytdl_sub.validators.string_formatter_validators.StringFormatterValidator`,
|
||||
but not
|
||||
:class:`~ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator`.
|
||||
"""
|
||||
|
||||
@property
|
||||
|
|
@ -45,7 +49,7 @@ class BaseEntryVariables:
|
|||
return {property_name: getattr(self, property_name) for property_name in property_names}
|
||||
|
||||
|
||||
class EntryVariables(BaseEntryVariables):
|
||||
class EntryVariables(SourceVariables):
|
||||
@property
|
||||
def title(self: BaseEntry) -> str:
|
||||
"""
|
||||
|
|
|
|||
|
|
@ -13,7 +13,28 @@ from ytdl_sub.validators.validators import Validator
|
|||
|
||||
class StringFormatterValidator(Validator):
|
||||
"""
|
||||
Ensures user-created formatter strings are valid
|
||||
String that can use
|
||||
:class:`source variables <ytdl_sub.entries.variables.entry_variables.SourceVariables>`
|
||||
and
|
||||
:class:`overrides <ytdl_sub.config.preset_options.Overrides>`
|
||||
for populating things like file paths and metadata.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
"{tv_show_file_name}.s{upload_year}.e{upload_month}{upload_day_padded}.{ext}"
|
||||
|
||||
is valid when using
|
||||
:class:`youtube variables <ytdl_sub.entries.variables.youtube_variables.YoutubeVideoVariables>`
|
||||
with the following overrides:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
presets:
|
||||
my_example_preset:
|
||||
overrides:
|
||||
tv_show_file_name: "sweet_tv_show"
|
||||
|
||||
and would resolve to something like ``sweet_tv_show.s2022.e502.mp4``.
|
||||
"""
|
||||
|
||||
_expected_value_type = str
|
||||
|
|
@ -132,12 +153,22 @@ class StringFormatterValidator(Validator):
|
|||
return formatter.format_string
|
||||
|
||||
|
||||
# pylint: disable=line-too-long
|
||||
class OverridesStringFormatterValidator(StringFormatterValidator):
|
||||
"""
|
||||
A string formatter that should strictly use overrides that resolve without any entry variables.
|
||||
String that can `only` use :class:`overrides <ytdl_sub.config.preset_options.Overrides>`.
|
||||
|
||||
Used in fields that do not touch the downloaded files themselves, but instead, `single`
|
||||
things like
|
||||
:func:`output_directory <ytdl_sub.config.preset_options.OutputOptions.output_directory>`
|
||||
or the fields in
|
||||
:class:`nfo_output_directory <ytdl_sub.plugins.output_directory_nfo_tags.OutputDirectoryNfoTagsOptions>`
|
||||
"""
|
||||
|
||||
|
||||
# pylint: enable=line-too-long
|
||||
|
||||
|
||||
class DictFormatterValidator(LiteralDictValidator):
|
||||
"""
|
||||
Validates a dictionary made up of key: string_formatters
|
||||
|
|
|
|||
Loading…
Reference in a new issue