diff --git a/docs/source/code_reference/entry_variables.rst b/docs/source/code_reference/entry_variables.rst index a9e4f278..d6c0c886 100644 --- a/docs/source/code_reference/entry_variables.rst +++ b/docs/source/code_reference/entry_variables.rst @@ -2,7 +2,10 @@ Entry Variables =============== -.. autoclass:: ytdl_sub.entries.script.variable_definitions.VariableDefinitions() - :members: - :inherited-members: - :undoc-members: \ No newline at end of file +.. .. autoclass:: ytdl_sub.entries.script.variable_definitions.VariableDefinitions +.. :members: +.. :inherited-members: +.. :undoc-members: + +.. autoclass:: ytdl_sub.entries.script.variable_definitions.VariableDefinitions + :members: \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 3c6033ae..b4a8f222 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,5 +1,9 @@ # Configuration file for the Sphinx documentation builder. -# + +import os +import sys +sys.path.insert(0, os.path.abspath('../../src')) + # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html @@ -17,7 +21,9 @@ release = "2023.12.15" extensions = [ "sphinx.ext.autodoc", "sphinx.ext.autosectionlabel", + # "sphinx.ext.autosummary", "sphinx.ext.extlinks", + "sphinx.ext.napoleon", "sphinx_copybutton", "sphinx_design", ] @@ -49,6 +55,8 @@ html_theme_options = { "announcement": ( "Migration to beautiful subscriptions is now live" ), + "navigation_depth": 10, + "show_toc_level": 10, } html_static_path = ["_static"] @@ -59,3 +67,19 @@ autosectionlabel_prefix_document = True extlinks = {"yt-dlp": ("https://github.com/yt-dlp/yt-dlp/%s", "yt-dlp%s")} + +# -- Options for autodoc ---------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration + +# Automatically extract typehints when specified and place them in +# descriptions of the relevant function/method. +autodoc_default_options = { + "autodoc_typehints_format": "short", + "autodoc_class_signature": "separated", + "add_module_names": False, + # "add_class_names": False, +} + +python_use_unqualified_type_names = True +napoleon_numpy_docstring = True +napoleon_use_rtype = False diff --git a/src/ytdl_sub/entries/script/variable_definitions.py b/src/ytdl_sub/entries/script/variable_definitions.py index 6c576db4..4590223a 100644 --- a/src/ytdl_sub/entries/script/variable_definitions.py +++ b/src/ytdl_sub/entries/script/variable_definitions.py @@ -146,240 +146,167 @@ class VariableDefinitions: @property def webpage_url(self) -> MetadataVariable: """ - Returns - ------- - str - The url to the webpage. + The url to the webpage. """ return MetadataVariable(metadata_key="webpage_url", variable_name="webpage_url") @property def info_json_ext(self) -> Variable: """ - Returns - ------- - str - The "info.json" extension + The "info.json" extension """ return Variable("info_json_ext") @property def description(self) -> MetadataVariable: """ - Returns - ------- - str - The description if it exists. Otherwise, returns an emtpy string. + The description if it exists. Otherwise, returns an emtpy string. """ return MetadataVariable(variable_name="description", metadata_key="description") @property def uploader_id(self) -> MetadataVariable: """ - Returns - ------- - str - The uploader id if it exists, otherwise return the unique ID. + The uploader id if it exists, otherwise return the unique ID. """ return MetadataVariable(variable_name="uploader_id", metadata_key="uploader_id") @property def uploader(self) -> MetadataVariable: """ - Returns - ------- - str - The uploader if it exists, otherwise return the uploader ID. + The uploader if it exists, otherwise return the uploader ID. """ return MetadataVariable(variable_name="uploader", metadata_key="uploader") @property def uploader_url(self) -> MetadataVariable: """ - Returns - ------- - str - The uploader url if it exists, otherwise returns the webpage_url. + The uploader url if it exists, otherwise returns the webpage_url. """ return MetadataVariable("uploader_url", metadata_key="uploader_url") @property def source_title(self) -> MetadataVariable: """ - Returns - ------- - str - Name of the source (i.e. channel with multiple playlists) if it exists, otherwise - returns its playlist_title. + Name of the source (i.e. channel with multiple playlists) if it exists, otherwise returns its playlist_title. """ return MetadataVariable("source_title", metadata_key=self.title.metadata_key) @property def source_uid(self) -> MetadataVariable: """ - Returns - ------- - str - The source unique id if it exists, otherwise returns the playlist unique ID. + The source unique id if it exists, otherwise returns the playlist unique ID. """ return MetadataVariable("source_uid", metadata_key=self.uid.metadata_key) @property def source_index(self) -> MetadataVariable: """ - Returns - ------- - int - Source index if it exists, otherwise returns ``1``. + Source index if it exists, otherwise returns ``1``. - It is recommended to not use this unless you know the source will never add new content - (it is easy for this value to change). + It is recommended to not use this unless you know the source will never add new content (it is easy for this value to change). """ return MetadataVariable("source_index", metadata_key=self.playlist_index.metadata_key) @property def source_index_padded(self) -> Variable: """ - Returns - ------- - int - The source index, padded. + The source index, padded. """ return Variable("source_index_padded") @property def source_count(self) -> MetadataVariable: """ - Returns - ------- - int - The source count if it exists, otherwise returns the playlist count. + The source count if it exists, otherwise returns the playlist count. """ return MetadataVariable("source_count", metadata_key=self.playlist_count.metadata_key) @property def source_webpage_url(self) -> MetadataVariable: """ - Returns - ------- - str - The source webpage url if it exists, otherwise returns the playlist webpage url. + The source webpage url if it exists, otherwise returns the playlist webpage url. """ return MetadataVariable("source_webpage_url", metadata_key=self.webpage_url.metadata_key) @property def source_description(self) -> MetadataVariable: """ - Returns - ------- - str - The source description if it exists, otherwise returns the playlist description. + The source description if it exists, otherwise returns the playlist description. """ return MetadataVariable("source_description", metadata_key=self.description.metadata_key) @property def playlist_uid(self) -> MetadataVariable: """ - Returns - ------- - str - The playlist unique ID if it exists, otherwise return the entry unique ID. + The playlist unique ID if it exists, otherwise return the entry unique ID. """ return MetadataVariable(variable_name="playlist_uid", metadata_key="playlist_id") @property def playlist_title(self) -> MetadataVariable: """ - Returns - ------- - str - Name of its parent playlist/channel if it exists, otherwise returns its title. + Name of its parent playlist/channel if it exists, otherwise returns its title. """ return MetadataVariable(variable_name="playlist_title", metadata_key="playlist_title") @property def playlist_index(self) -> MetadataVariable: """ - Returns - ------- - int - Playlist index if it exists, otherwise returns ``1``. + Playlist index if it exists, otherwise returns ``1``. - Note that for channels/playlists, any change (i.e. adding or removing a video) will make - this value change. Use with caution. + Note that for channels/playlists, any change (i.e. adding or removing a video) will make this value change. Use with caution. """ return MetadataVariable(metadata_key="playlist_index", variable_name="playlist_index") @property def playlist_index_reversed(self) -> Variable: """ - Returns - ------- - int - Playlist index reversed via ``playlist_count - playlist_index + 1`` + Playlist index reversed via ``playlist_count - playlist_index + 1`` """ return Variable("playlist_index_reversed") @property def playlist_index_padded(self) -> Variable: """ - Returns - ------- - str - playlist_index padded two digits + playlist_index padded two digits """ return Variable("playlist_index_padded") @property def playlist_index_reversed_padded(self) -> Variable: """ - Returns - ------- - str - playlist_index_reversed padded two digits + playlist_index_reversed padded two digits """ return Variable("playlist_index_reversed_padded") @property def playlist_index_padded6(self) -> Variable: """ - Returns - ------- - str - playlist_index padded six digits. + playlist_index padded six digits. """ return Variable("playlist_index_padded6") @property def playlist_index_reversed_padded6(self) -> Variable: """ - Returns - ------- - str - playlist_index_reversed padded six digits. + playlist_index_reversed padded six digits. """ return Variable("playlist_index_reversed_padded6") @property def playlist_count(self) -> MetadataVariable: """ - Returns - ------- - int - Playlist count if it exists, otherwise returns ``1``. + Playlist count if it exists, otherwise returns ``1``. - Note that for channels/playlists, any change (i.e. adding or removing a video) will make - this value change. Use with caution. + Note that for channels/playlists, any change (i.e. adding or removing a video) will make this value change. Use with caution. """ return MetadataVariable(variable_name="playlist_count", metadata_key="playlist_count") @property def playlist_description(self) -> MetadataVariable: """ - Returns - ------- - str - The playlist description if it exists, otherwise returns the entry's description. + The playlist description if it exists, otherwise returns the entry's description. """ return MetadataVariable( variable_name="playlist_description", metadata_key=self.description.metadata_key @@ -388,10 +315,7 @@ class VariableDefinitions: @property def playlist_webpage_url(self) -> MetadataVariable: """ - Returns - ------- - str - The playlist webpage url if it exists. Otherwise, returns the entry webpage url. + The playlist webpage url if it exists. Otherwise, returns the entry webpage url. """ return MetadataVariable( variable_name="playlist_webpage_url", metadata_key=self.webpage_url.metadata_key @@ -400,21 +324,14 @@ class VariableDefinitions: @property def playlist_max_upload_date(self) -> Variable: """ - Returns - ------- - Max upload_date for all entries in this entry's playlist if it exists, otherwise returns - ``upload_date`` + Max upload_date for all entries in this entry's playlist if it exists, otherwise returns ``upload_date`` """ return Variable("playlist_max_upload_date") @property def playlist_max_upload_year(self) -> Variable: """ - Returns - ------- - int - Max upload_year for all entries in this entry's playlist if it exists, otherwise returns - ``upload_year`` + Max upload_year for all entries in this entry's playlist if it exists, otherwise returns ``upload_year`` """ # override in EntryParent return Variable("playlist_max_upload_year") @@ -422,41 +339,28 @@ class VariableDefinitions: @property def playlist_max_upload_year_truncated(self) -> Variable: """ - Returns - ------- - int - The max playlist truncated upload year for all entries in this entry's playlist if it - exists, otherwise returns ``upload_year_truncated``. + The max playlist truncated upload year for all entries in this entry's playlist if it exists, otherwise returns ``upload_year_truncated``. """ return Variable("playlist_max_upload_year_truncated") @property def playlist_uploader_id(self) -> MetadataVariable: """ - Returns - ------- - str - The playlist uploader id if it exists, otherwise returns the entry uploader ID. + The playlist uploader id if it exists, otherwise returns the entry uploader ID. """ return MetadataVariable("playlist_uploader_id", metadata_key="playlist_uploader_id") @property def playlist_uploader(self) -> MetadataVariable: """ - Returns - ------- - str - The playlist uploader if it exists, otherwise return the entry uploader. + The playlist uploader if it exists, otherwise return the entry uploader. """ return MetadataVariable("playlist_uploader", metadata_key=self.uploader.metadata_key) @property def playlist_uploader_url(self) -> MetadataVariable: """ - Returns - ------- - str - The playlist uploader url if it exists, otherwise returns the playlist webpage_url. + The playlist uploader url if it exists, otherwise returns the playlist webpage_url. """ return MetadataVariable( "playlist_uploader_url", metadata_key=self.uploader_url.metadata_key @@ -465,81 +369,56 @@ class VariableDefinitions: @property def source_uploader_id(self) -> MetadataVariable: """ - Returns - ------- - str - The source uploader id if it exists, otherwise returns the playlist_uploader_id + The source uploader id if it exists, otherwise returns the playlist_uploader_id """ return MetadataVariable("source_uploader_id", metadata_key=self.uploader_id.metadata_key) @property def source_uploader(self) -> MetadataVariable: """ - Returns - ------- - str - The source uploader if it exists, otherwise return the playlist_uploader + The source uploader if it exists, otherwise return the playlist_uploader """ return MetadataVariable("source_uploader", metadata_key=self.uploader.metadata_key) @property def source_uploader_url(self) -> MetadataVariable: """ - Returns - ------- - str - The source uploader url if it exists, otherwise returns the source webpage_url. + The source uploader url if it exists, otherwise returns the source webpage_url. """ return MetadataVariable("source_uploader_url", metadata_key=self.uploader_url.metadata_key) @property def creator(self) -> MetadataVariable: """ - Returns - ------- - str - The creator name if it exists, otherwise returns the channel. + The creator name if it exists, otherwise returns the channel. """ return MetadataVariable(variable_name="creator", metadata_key="creator") @property def channel(self) -> MetadataVariable: """ - Returns - ------- - str - The channel name if it exists, otherwise returns the uploader. + The channel name if it exists, otherwise returns the uploader. """ return MetadataVariable(variable_name="channel", metadata_key="channel") @property def channel_id(self) -> MetadataVariable: """ - Returns - ------- - str - The channel id if it exists, otherwise returns the entry uploader ID. + The channel id if it exists, otherwise returns the entry uploader ID. """ return MetadataVariable(variable_name="channel_id", metadata_key="channel_id") @property def ext(self) -> MetadataVariable: """ - Returns - ------- - str - The downloaded entry's file extension + The downloaded entry's file extension """ return MetadataVariable(variable_name="ext", metadata_key="ext") @property def thumbnail_ext(self) -> Variable: """ - Returns - ------- - str - The download entry's thumbnail extension. Will always return 'jpg'. Until there is a - need to support other image types, we always convert to jpg. + The download entry's thumbnail extension. Will always return 'jpg'. Until there is a need to support other image types, we always convert to jpg. """ return Variable("thumbnail_ext") @@ -581,408 +460,280 @@ class VariableDefinitions: @property def download_index(self) -> Variable: """ - Returns - ------- - int - The i'th entry downloaded. NOTE that this is fetched dynamically from the download - archive. + The i'th entry downloaded. NOTE that this is fetched dynamically from the download archive. """ return Variable(variable_name="download_index") @property def download_index_padded6(self) -> Variable: """ - Returns - ------- - str - The download_index padded six digits + The download_index padded six digits """ return Variable("download_index_padded6") @property def upload_date_index(self) -> Variable: """ - Returns - ------- - int - The i'th entry downloaded with this upload date. + The i'th entry downloaded with this upload date. """ return Variable(variable_name="upload_date_index") @property def upload_date_index_padded(self) -> Variable: """ - Returns - ------- - int - The upload_date_index padded two digits + The upload_date_index padded two digits """ return Variable("upload_date_index_padded") @property def upload_date_index_reversed(self) -> Variable: """ - Returns - ------- - int - 100 - upload_date_index + 100 - upload_date_index """ return Variable("upload_date_index_reversed") @property def upload_date_index_reversed_padded(self) -> Variable: """ - Returns - ------- - int - The upload_date_index padded two digits + The upload_date_index padded two digits """ return Variable("upload_date_index_reversed_padded") @property def upload_date(self) -> MetadataVariable: """ - Returns - ------- - str - The entry’s uploaded date, in YYYYMMDD format. If not present, return today’s date. + The entry's uploaded date, in YYYYMMDD format. If not present, return today's date. """ return MetadataVariable(variable_name="upload_date", metadata_key="upload_date") @property def upload_year(self) -> Variable: """ - Returns - ------- - int - The entry's upload year + The entry's upload year """ return Variable("upload_year") @property def upload_year_truncated(self) -> Variable: """ - Returns - ------- - int - The last two digits of the upload year, i.e. 22 in 2022 + The last two digits of the upload year, i.e. 22 in 2022 """ return Variable("upload_year_truncated") @property def upload_year_truncated_reversed(self) -> Variable: """ - Returns - ------- - int - The upload year truncated, but reversed using ``100 - {upload_year_truncated}``, i.e. - 2022 returns ``100 - 22`` = ``78`` + The upload year truncated, but reversed using ``100 - {upload_year_truncated}``, i.e. 2022 returns ``100 - 22`` = ``78`` """ return Variable("upload_year_truncated_reversed") @property def upload_month_reversed(self) -> Variable: """ - Returns - ------- - int - The upload month, but reversed using ``13 - {upload_month}``, i.e. March returns ``10`` + The upload month, but reversed using ``13 - {upload_month}``, i.e. March returns ``10`` """ return Variable("upload_month_reversed") @property def upload_month_reversed_padded(self) -> Variable: """ - Returns - ------- - str - The reversed upload month, but padded. i.e. November returns "02" + The reversed upload month, but padded. i.e. November returns "02" """ return Variable("upload_month_reversed_padded") @property def upload_month_padded(self) -> Variable: """ - Returns - ------- - str - The entry's upload month padded to two digits, i.e. March returns "03" + The entry's upload month padded to two digits, i.e. March returns "03" """ return Variable("upload_month_padded") @property def upload_day_padded(self) -> Variable: """ - Returns - ------- - str - The entry's upload day padded to two digits, i.e. the fifth returns "05" + The entry's upload day padded to two digits, i.e. the fifth returns "05" """ return Variable("upload_day_padded") @property def upload_month(self) -> Variable: """ - Returns - ------- - int - The upload month as an integer (no padding). + The upload month as an integer (no padding). """ return Variable("upload_month") @property def upload_day(self) -> Variable: """ - Returns - ------- - int - The upload day as an integer (no padding). + The upload day as an integer (no padding). """ return Variable("upload_day") @property def upload_day_reversed(self) -> Variable: """ - Returns - ------- - int - The upload day, but reversed using ``{total_days_in_month} + 1 - {upload_day}``, - i.e. August 8th would have upload_day_reversed of ``31 + 1 - 8`` = ``24`` + The upload day, but reversed using ``{total_days_in_month} + 1 - {upload_day}``, i.e. August 8th would have upload_day_reversed of ``31 + 1 - 8`` = ``24`` """ return Variable("upload_day_reversed") @property def upload_day_reversed_padded(self) -> Variable: """ - Returns - ------- - str - The reversed upload day, but padded. i.e. August 30th returns "02". + The reversed upload day, but padded. i.e. August 30th returns "02". """ return Variable("upload_day_reversed_padded") @property def upload_day_of_year(self) -> Variable: """ - Returns - ------- - int - The day of the year, i.e. February 1st returns ``32`` + The day of the year, i.e. February 1st returns ``32`` """ return Variable("upload_day_of_year") @property def upload_day_of_year_padded(self) -> Variable: """ - Returns - ------- - str - The upload day of year, but padded i.e. February 1st returns "032" + The upload day of year, but padded i.e. February 1st returns "032" """ return Variable("upload_day_of_year_padded") @property def upload_day_of_year_reversed(self) -> Variable: """ - Returns - ------- - int - The upload day, but reversed using ``{total_days_in_year} + 1 - {upload_day}``, - i.e. February 2nd would have upload_day_of_year_reversed of ``365 + 1 - 32`` = ``334`` + The upload day, but reversed using ``{total_days_in_year} + 1 - {upload_day}``, i.e. February 2nd would have upload_day_of_year_reversed of ``365 + 1 - 32`` = ``334`` """ return Variable("upload_day_of_year_reversed") @property def upload_day_of_year_reversed_padded(self) -> Variable: """ - Returns - ------- - str - The reversed upload day of year, but padded i.e. December 31st returns "001" + The reversed upload day of year, but padded i.e. December 31st returns "001" """ return Variable("upload_day_of_year_reversed_padded") @property def upload_date_standardized(self) -> Variable: """ - Returns - ------- - str - The uploaded date formatted as YYYY-MM-DD + The uploaded date formatted as YYYY-MM-DD """ return Variable("upload_date_standardized") @property def release_date(self) -> MetadataVariable: """ - Returns - ------- - str - The entry’s release date, in YYYYMMDD format. If not present, return the upload date. + The entry's release date, in YYYYMMDD format. If not present, return the upload date. """ return MetadataVariable(variable_name="release_date", metadata_key="release_date") @property def release_year(self) -> Variable: """ - Returns - ------- - int - The entry's release year + The entry's release year """ return Variable("release_year") @property def release_year_truncated(self) -> Variable: """ - Returns - ------- - int - The last two digits of the release year, i.e. 22 in 2022 + The last two digits of the release year, i.e. 22 in 2022 """ return Variable("release_year_truncated") @property def release_year_truncated_reversed(self) -> Variable: """ - Returns - ------- - int - The release year truncated, but reversed using ``100 - {release_year_truncated}``, i.e. - 2022 returns ``100 - 22`` = ``78`` + The release year truncated, but reversed using ``100 - {release_year_truncated}``, i.e. 2022 returns ``100 - 22`` = ``78`` """ return Variable("release_year_truncated_reversed") @property def release_month_reversed(self) -> Variable: """ - Returns - ------- - int - The release month, but reversed - using ``13 - {release_month}``, i.e. March returns ``10`` + The release month, but reversed using ``13 - {release_month}``, i.e. March returns ``10`` """ return Variable("release_month_reversed") @property def release_month_reversed_padded(self) -> Variable: """ - Returns - ------- - str - The reversed release month, but padded. i.e. November returns "02" + The reversed release month, but padded. i.e. November returns "02" """ return Variable("release_month_reversed_padded") @property def release_month_padded(self) -> Variable: """ - Returns - ------- - str - The entry's release month padded to two digits, i.e. March returns "03" + The entry's release month padded to two digits, i.e. March returns "03" """ return Variable("release_month_padded") @property def release_day_padded(self) -> Variable: """ - Returns - ------- - str - The entry's release day padded to two digits, i.e. the fifth returns "05" + The entry's release day padded to two digits, i.e. the fifth returns "05" """ return Variable("release_day_padded") @property def release_month(self) -> Variable: """ - Returns - ------- - int - The release month as an integer (no padding). + The release month as an integer (no padding). """ return Variable("release_month") @property def release_day(self) -> Variable: """ - Returns - ------- - int - The release day as an integer (no padding). + The release day as an integer (no padding). """ return Variable("release_day") @property def release_day_reversed(self) -> Variable: """ - Returns - ------- - int - The release day, but reversed using ``{total_days_in_month} + 1 - {release_day}``, - i.e. August 8th would have release_day_reversed of ``31 + 1 - 8`` = ``24`` + The release day, but reversed using ``{total_days_in_month} + 1 - {release_day}``, i.e. August 8th would have release_day_reversed of ``31 + 1 - 8`` = ``24`` """ return Variable("release_day_reversed") @property def release_day_reversed_padded(self) -> Variable: """ - Returns - ------- - str - The reversed release day, but padded. i.e. August 30th returns "02". + The reversed release day, but padded. i.e. August 30th returns "02". """ return Variable("release_day_reversed_padded") @property def release_day_of_year(self) -> Variable: """ - Returns - ------- - int - The day of the year, i.e. February 1st returns ``32`` + The day of the year, i.e. February 1st returns ``32`` """ return Variable("release_day_of_year") @property def release_day_of_year_padded(self) -> Variable: """ - Returns - ------- - str - The release day of year, but padded i.e. February 1st returns "032" + The release day of year, but padded i.e. February 1st returns "032" """ return Variable("release_day_of_year_padded") @property def release_day_of_year_reversed(self) -> Variable: """ - Returns - ------- - int - The release day, but reversed using ``{total_days_in_year} + 1 - {release_day}``, - i.e. February 2nd would have release_day_of_year_reversed of ``365 + 1 - 32`` = ``334`` + The release day, but reversed using ``{total_days_in_year} + 1 - {release_day}``, i.e. February 2nd would have release_day_of_year_reversed of ``365 + 1 - 32`` = ``334`` """ return Variable("release_day_of_year_reversed") @property def release_day_of_year_reversed_padded(self) -> Variable: """ - Returns - ------- - str - The reversed release day of year, but padded i.e. December 31st returns "001" + The reversed release day of year, but padded i.e. December 31st returns "001" """ return Variable("release_day_of_year_reversed_padded") @property def release_date_standardized(self) -> Variable: """ - Returns - ------- - str - The release date formatted as YYYY-MM-DD + The release date formatted as YYYY-MM-DD """ return Variable("release_date_standardized")