From f4d5dd226008adc805da3355a7dbc16fa4ca0a3a Mon Sep 17 00:00:00 2001 From: Jesse Bannon Date: Fri, 29 Dec 2023 14:06:16 -0800 Subject: [PATCH] docs --- .../scripting/entry_variables.rst | 434 +++++++++++++----- .../scripting/scripting_functions.rst | 2 +- .../entries/script/variable_definitions.py | 337 +++++++++----- tools/docgen/entry_variables.py | 6 +- tools/docgen/utils.py | 12 +- 5 files changed, 549 insertions(+), 242 deletions(-) diff --git a/docs/source/config_reference/scripting/entry_variables.rst b/docs/source/config_reference/scripting/entry_variables.rst index c4467330..c3012408 100644 --- a/docs/source/config_reference/scripting/entry_variables.rst +++ b/docs/source/config_reference/scripting/entry_variables.rst @@ -7,110 +7,163 @@ Entry Variables channel ~~~~~~~ -The channel name if it exists, otherwise returns the uploader. +:type: ``String`` +:description: + The channel name if it exists, otherwise returns the uploader. channel_id ~~~~~~~~~~ -The channel id if it exists, otherwise returns the entry uploader ID. +:type: ``String`` +:description: + The channel id if it exists, otherwise returns the entry uploader ID. chapters ~~~~~~~~ -Chapters if they exist +:type: ``Array`` +:description: + Chapters if they exist comments ~~~~~~~~ -Comments if they are requested +:type: ``Array`` +:description: + Comments if they are requested creator ~~~~~~~ -The creator name if it exists, otherwise returns the channel. +:type: ``String`` +:description: + The creator name if it exists, otherwise returns the channel. description ~~~~~~~~~~~ -The description if it exists. Otherwise, returns an emtpy string. +:type: ``String`` +:description: + The description if it exists. Otherwise, returns an emtpy string. duration ~~~~~~~~ -The duration of the entry in seconds +:type: ``Integer`` +:description: + The duration of the entry in seconds if it exists. Defaults to zero otherwise. epoch ~~~~~ -The unix epoch of when the metadata was scraped by yt-dlp. +:type: ``Integer`` +:description: + The unix epoch of when the metadata was scraped by yt-dlp. epoch_date ~~~~~~~~~~ -The epoch's date, in YYYYMMDD format. +:type: ``String`` +:description: + The epoch's date, in YYYYMMDD format. epoch_hour ~~~~~~~~~~ -The epoch's hour +:type: ``String`` +:description: + The epoch's hour ext ~~~ -The downloaded entry's file extension +:type: ``String`` +:description: + The downloaded entry's file extension extractor ~~~~~~~~~ -The yt-dlp extractor name +:type: ``String`` +:description: + The yt-dlp extractor name extractor_key ~~~~~~~~~~~~~ -The yt-dlp extractor key +:type: ``String`` +:description: + The yt-dlp extractor key ie_key ~~~~~~ -The ie_key, used in legacy yt-dlp things as the 'info-extractor key' +:type: ``String`` +:description: + The ie_key, used in legacy yt-dlp things as the 'info-extractor key'. + If it does not exist, return ``extractor_key`` info_json_ext ~~~~~~~~~~~~~ -The "info.json" extension +:type: ``String`` +:description: + The "info.json" extension requested_subtitles ~~~~~~~~~~~~~~~~~~~ -Subtitles if they are requested and exist +:type: ``Map`` +:description: + Subtitles if they are requested and exist sponsorblock_chapters ~~~~~~~~~~~~~~~~~~~~~ -Sponsorblock Chapters if they are requested and exist +:type: ``Array`` +:description: + Sponsorblock Chapters if they are requested and exist thumbnail_ext ~~~~~~~~~~~~~ -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. +:type: ``String`` +:description: + 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. title ~~~~~ -The title of the entry. If a title does not exist, returns its unique ID. +:type: ``String`` +:description: + The title of the entry. If a title does not exist, returns its unique ID. title_sanitized_plex ~~~~~~~~~~~~~~~~~~~~ -The sanitized title with additional sanitizing for Plex. It replaces numbers with -fixed-width numbers so Plex does not recognize them as season or episode numbers. +:type: ``String`` +:description: + The sanitized title with additional sanitizing for Plex. It replaces numbers with + fixed-width numbers so Plex does not recognize them as season or episode numbers. uid ~~~ -The entry's unique ID +:type: ``String`` +:description: + The entry's unique ID uid_sanitized_plex ~~~~~~~~~~~~~~~~~~ -The sanitized uid with additional sanitizing for Plex. Replaces numbers with -fixed-width numbers so Plex does not recognize them as season or episode numbers. +:type: ``String`` +:description: + The sanitized uid with additional sanitizing for Plex. Replaces numbers with + fixed-width numbers so Plex does not recognize them as season or episode numbers. uploader ~~~~~~~~ -The uploader if it exists, otherwise return the uploader ID. +:type: ``String`` +:description: + The uploader if it exists, otherwise return the uploader ID. uploader_id ~~~~~~~~~~~ -The uploader id if it exists, otherwise return the unique ID. +:type: ``String`` +:description: + The uploader id if it exists, otherwise return the unique ID. uploader_url ~~~~~~~~~~~~ -The uploader url if it exists, otherwise returns the webpage_url. +:type: ``String`` +:description: + The uploader url if it exists, otherwise returns the webpage_url. webpage_url ~~~~~~~~~~~ -The url to the webpage. +:type: ``String`` +:description: + The url to the webpage. ---------------------------------------------------------------------------------------------------- @@ -119,19 +172,27 @@ Metadata Variables entry_metadata ~~~~~~~~~~~~~~ -The entry's info.json +:type: ``Map`` +:description: + The entry's info.json playlist_metadata ~~~~~~~~~~~~~~~~~ -Metadata from the playlist (i.e. the parent metadata, like playlist -> entry) +:type: ``Map`` +:description: + Metadata from the playlist (i.e. the parent metadata, like playlist -> entry) sibling_metadata ~~~~~~~~~~~~~~~~ -Metadata from any sibling entries that reside in the same playlist as this entry. +:type: ``Array`` +:description: + Metadata from any sibling entries that reside in the same playlist as this entry. source_metadata ~~~~~~~~~~~~~~~ -Metadata from the source (i.e. the grandparent metadata, like channel -> playlist -> entry) +:type: ``Map`` +:description: + Metadata from the source (i.e. the grandparent metadata, like channel -> playlist -> entry) ---------------------------------------------------------------------------------------------------- @@ -140,80 +201,114 @@ Playlist Variables playlist_count ~~~~~~~~~~~~~~ -Playlist count if it exists, otherwise returns ``1``. +:type: ``Integer`` +:description: + 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. playlist_description ~~~~~~~~~~~~~~~~~~~~ -The playlist description if it exists, otherwise returns the entry's description. +:type: ``String`` +:description: + The playlist description if it exists, otherwise returns the entry's description. playlist_index ~~~~~~~~~~~~~~ -Playlist index if it exists, otherwise returns ``1``. +:type: ``Integer`` +:description: + 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. playlist_index_padded ~~~~~~~~~~~~~~~~~~~~~ -playlist_index padded two digits +:type: ``String`` +:description: + playlist_index padded two digits playlist_index_padded6 ~~~~~~~~~~~~~~~~~~~~~~ -playlist_index padded six digits. +:type: ``String`` +:description: + playlist_index padded six digits. playlist_index_reversed ~~~~~~~~~~~~~~~~~~~~~~~ -Playlist index reversed via ``playlist_count - playlist_index + 1`` +:type: ``Integer`` +:description: + Playlist index reversed via ``playlist_count - playlist_index + 1`` playlist_index_reversed_padded ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -playlist_index_reversed padded two digits +:type: ``String`` +:description: + playlist_index_reversed padded two digits playlist_index_reversed_padded6 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -playlist_index_reversed padded six digits. +:type: ``String`` +:description: + playlist_index_reversed padded six digits. playlist_max_upload_date ~~~~~~~~~~~~~~~~~~~~~~~~ -Max upload_date for all entries in this entry's playlist if it exists, otherwise returns -``upload_date`` +:type: ``String`` +:description: + Max upload_date for all entries in this entry's playlist if it exists, otherwise returns + ``upload_date`` playlist_max_upload_year ~~~~~~~~~~~~~~~~~~~~~~~~ -Max upload_year for all entries in this entry's playlist if it exists, otherwise returns -``upload_year`` +:type: ``Integer`` +:description: + Max upload_year for all entries in this entry's playlist if it exists, otherwise returns + ``upload_year`` playlist_max_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``. +:type: ``Integer`` +:description: + The max playlist truncated upload year for all entries in this entry's playlist if it + exists, otherwise returns ``upload_year_truncated``. playlist_title ~~~~~~~~~~~~~~ -Name of its parent playlist/channel if it exists, otherwise returns its title. +:type: ``String`` +:description: + Name of its parent playlist/channel if it exists, otherwise returns its title. playlist_uid ~~~~~~~~~~~~ -The playlist unique ID if it exists, otherwise return the entry unique ID. +:type: ``String`` +:description: + The playlist unique ID if it exists, otherwise return the entry unique ID. playlist_uploader ~~~~~~~~~~~~~~~~~ -The playlist uploader if it exists, otherwise return the entry uploader. +:type: ``String`` +:description: + The playlist uploader if it exists, otherwise return the entry uploader. playlist_uploader_id ~~~~~~~~~~~~~~~~~~~~ -The playlist uploader id if it exists, otherwise returns the entry uploader ID. +:type: ``String`` +:description: + The playlist uploader id if it exists, otherwise returns the entry uploader ID. playlist_uploader_url ~~~~~~~~~~~~~~~~~~~~~ -The playlist uploader url if it exists, otherwise returns the playlist webpage_url. +:type: ``String`` +:description: + The playlist uploader url if it exists, otherwise returns the playlist webpage_url. playlist_webpage_url ~~~~~~~~~~~~~~~~~~~~ -The playlist webpage url if it exists. Otherwise, returns the entry webpage url. +:type: ``String`` +:description: + The playlist webpage url if it exists. Otherwise, returns the entry webpage url. ---------------------------------------------------------------------------------------------------- @@ -222,75 +317,108 @@ Release Date Variables release_date ~~~~~~~~~~~~ -The entry’s release date, in YYYYMMDD format. If not present, return the upload date. +:type: ``String`` +:description: + The entry’s release date, in YYYYMMDD format. If not present, return the upload date. release_date_standardized ~~~~~~~~~~~~~~~~~~~~~~~~~ -The release date formatted as YYYY-MM-DD +:type: ``String`` +:description: + The uploaded date formatted as YYYY-MM-DD release_day ~~~~~~~~~~~ -The release day as an integer (no padding). +:type: ``Integer`` +:description: + The upload day as an integer (no padding). release_day_of_year ~~~~~~~~~~~~~~~~~~~ -The day of the year, i.e. February 1st returns ``32`` +:type: ``Integer`` +:description: + The day of the year, i.e. February 1st returns ``32`` release_day_of_year_padded ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The release day of year, but padded i.e. February 1st returns "032" +:type: ``String`` +:description: + The upload day of year, but padded i.e. February 1st returns "032" release_day_of_year_reversed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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`` +:type: ``Integer`` +:description: + The upload 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`` release_day_of_year_reversed_padded ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The reversed release day of year, but padded i.e. December 31st returns "001" +:type: ``String`` +:description: + The reversed upload day of year, but padded i.e. December 31st returns "001" release_day_padded ~~~~~~~~~~~~~~~~~~ -The entry's release day padded to two digits, i.e. the fifth returns "05" +:type: ``String`` +:description: + The entry's upload day padded to two digits, i.e. the fifth returns "05" release_day_reversed ~~~~~~~~~~~~~~~~~~~~ -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`` +:type: ``Integer`` +:description: + The upload 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`` release_day_reversed_padded ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The reversed release day, but padded. i.e. August 30th returns "02". +:type: ``String`` +:description: + The reversed upload day, but padded. i.e. August 30th returns "02". release_month ~~~~~~~~~~~~~ -The release month as an integer (no padding). +:type: ``Integer`` +:description: + The upload month as an integer (no padding). release_month_padded ~~~~~~~~~~~~~~~~~~~~ -The entry's release month padded to two digits, i.e. March returns "03" +:type: ``String`` +:description: + The entry's upload month padded to two digits, i.e. March returns "03" release_month_reversed ~~~~~~~~~~~~~~~~~~~~~~ -The release month, but reversed -using ``13 - {release_month}``, i.e. March returns ``10`` +:type: ``Integer`` +:description: + The upload month, but reversed using ``13 - {release_month}``, i.e. March returns ``10`` release_month_reversed_padded ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The reversed release month, but padded. i.e. November returns "02" +:type: ``String`` +:description: + The reversed upload month, but padded. i.e. November returns "02" release_year ~~~~~~~~~~~~ -The entry's release year +:type: ``Integer`` +:description: + The entry's upload year release_year_truncated ~~~~~~~~~~~~~~~~~~~~~~ -The last two digits of the release year, i.e. 22 in 2022 +:type: ``Integer`` +:description: + The last two digits of the upload year, i.e. 22 in 2022 release_year_truncated_reversed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The release year truncated, but reversed using ``100 - {release_year_truncated}``, i.e. -2022 returns ``100 - 22`` = ``78`` +:type: ``Integer`` +:description: + The upload year truncated, but reversed using ``100 - {release_year_truncated}``, i.e. + 2022 returns ``100 - 22`` = ``78`` ---------------------------------------------------------------------------------------------------- @@ -299,47 +427,67 @@ Source Variables source_count ~~~~~~~~~~~~ -The source count if it exists, otherwise returns the playlist count. +:type: ``Integer`` +:description: + The source count if it exists, otherwise returns ``1``. source_description ~~~~~~~~~~~~~~~~~~ -The source description if it exists, otherwise returns the playlist description. +:type: ``String`` +:description: + The source description if it exists, otherwise returns the playlist description. source_index ~~~~~~~~~~~~ -Source index if it exists, otherwise returns ``1``. +:type: ``Integer`` +:description: + 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). source_index_padded ~~~~~~~~~~~~~~~~~~~ -The source index, padded. +:type: ``String`` +:description: + The source index, padded two digits. source_title ~~~~~~~~~~~~ -Name of the source (i.e. channel with multiple playlists) if it exists, otherwise -returns its playlist_title. +:type: ``String`` +:description: + Name of the source (i.e. channel with multiple playlists) if it exists, otherwise + returns its playlist_title. source_uid ~~~~~~~~~~ -The source unique id if it exists, otherwise returns the playlist unique ID. +:type: ``String`` +:description: + The source unique id if it exists, otherwise returns the playlist unique ID. source_uploader ~~~~~~~~~~~~~~~ -The source uploader if it exists, otherwise return the playlist_uploader +:type: ``String`` +:description: + The source uploader if it exists, otherwise return the playlist_uploader source_uploader_id ~~~~~~~~~~~~~~~~~~ -The source uploader id if it exists, otherwise returns the playlist_uploader_id +:type: ``String`` +:description: + The source uploader id if it exists, otherwise returns the playlist_uploader_id source_uploader_url ~~~~~~~~~~~~~~~~~~~ -The source uploader url if it exists, otherwise returns the source webpage_url. +:type: ``String`` +:description: + The source uploader url if it exists, otherwise returns the source webpage_url. source_webpage_url ~~~~~~~~~~~~~~~~~~ -The source webpage url if it exists, otherwise returns the playlist webpage url. +:type: ``String`` +:description: + The source webpage url if it exists, otherwise returns the playlist webpage url. ---------------------------------------------------------------------------------------------------- @@ -348,74 +496,108 @@ Upload Date Variables upload_date ~~~~~~~~~~~ -The entry’s uploaded date, in YYYYMMDD format. If not present, return today’s date. +:type: ``String`` +:description: + The entry’s uploaded date, in YYYYMMDD format. If not present, return today’s date. upload_date_standardized ~~~~~~~~~~~~~~~~~~~~~~~~ -The uploaded date formatted as YYYY-MM-DD +:type: ``String`` +:description: + The uploaded date formatted as YYYY-MM-DD upload_day ~~~~~~~~~~ -The upload day as an integer (no padding). +:type: ``Integer`` +:description: + The upload day as an integer (no padding). upload_day_of_year ~~~~~~~~~~~~~~~~~~ -The day of the year, i.e. February 1st returns ``32`` +:type: ``Integer`` +:description: + The day of the year, i.e. February 1st returns ``32`` upload_day_of_year_padded ~~~~~~~~~~~~~~~~~~~~~~~~~ -The upload day of year, but padded i.e. February 1st returns "032" +:type: ``String`` +:description: + The upload day of year, but padded i.e. February 1st returns "032" upload_day_of_year_reversed ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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`` +:type: ``Integer`` +:description: + 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`` upload_day_of_year_reversed_padded ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The reversed upload day of year, but padded i.e. December 31st returns "001" +:type: ``String`` +:description: + The reversed upload day of year, but padded i.e. December 31st returns "001" upload_day_padded ~~~~~~~~~~~~~~~~~ -The entry's upload day padded to two digits, i.e. the fifth returns "05" +:type: ``String`` +:description: + The entry's upload day padded to two digits, i.e. the fifth returns "05" upload_day_reversed ~~~~~~~~~~~~~~~~~~~ -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`` +:type: ``Integer`` +:description: + 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`` upload_day_reversed_padded ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The reversed upload day, but padded. i.e. August 30th returns "02". +:type: ``String`` +:description: + The reversed upload day, but padded. i.e. August 30th returns "02". upload_month ~~~~~~~~~~~~ -The upload month as an integer (no padding). +:type: ``Integer`` +:description: + The upload month as an integer (no padding). upload_month_padded ~~~~~~~~~~~~~~~~~~~ -The entry's upload month padded to two digits, i.e. March returns "03" +:type: ``String`` +:description: + The entry's upload month padded to two digits, i.e. March returns "03" upload_month_reversed ~~~~~~~~~~~~~~~~~~~~~ -The upload month, but reversed using ``13 - {upload_month}``, i.e. March returns ``10`` +:type: ``Integer`` +:description: + The upload month, but reversed using ``13 - {upload_month}``, i.e. March returns ``10`` upload_month_reversed_padded ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The reversed upload month, but padded. i.e. November returns "02" +:type: ``String`` +:description: + The reversed upload month, but padded. i.e. November returns "02" upload_year ~~~~~~~~~~~ -The entry's upload year +:type: ``Integer`` +:description: + The entry's upload year upload_year_truncated ~~~~~~~~~~~~~~~~~~~~~ -The last two digits of the upload year, i.e. 22 in 2022 +:type: ``Integer`` +:description: + The last two digits of the upload year, i.e. 22 in 2022 upload_year_truncated_reversed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The upload year truncated, but reversed using ``100 - {upload_year_truncated}``, i.e. -2022 returns ``100 - 22`` = ``78`` +:type: ``Integer`` +:description: + The upload year truncated, but reversed using ``100 - {upload_year_truncated}``, i.e. + 2022 returns ``100 - 22`` = ``78`` ---------------------------------------------------------------------------------------------------- @@ -424,29 +606,43 @@ Ytdl-Sub Variables download_index ~~~~~~~~~~~~~~ -The i'th entry downloaded. NOTE that this is fetched dynamically from the download -archive. +:type: ``Integer`` +:description: + The i'th entry downloaded. NOTE that this is fetched dynamically from the download + archive. download_index_padded6 ~~~~~~~~~~~~~~~~~~~~~~ -The download_index padded six digits +:type: ``String`` +:description: + The download_index padded six digits upload_date_index ~~~~~~~~~~~~~~~~~ -The i'th entry downloaded with this upload date. +:type: ``Integer`` +:description: + The i'th entry downloaded with this upload date. upload_date_index_padded ~~~~~~~~~~~~~~~~~~~~~~~~ -The upload_date_index padded two digits +:type: ``String`` +:description: + The upload_date_index padded two digits upload_date_index_reversed ~~~~~~~~~~~~~~~~~~~~~~~~~~ -100 - upload_date_index +:type: ``Integer`` +:description: + 100 - upload_date_index upload_date_index_reversed_padded ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The upload_date_index padded two digits +:type: ``String`` +:description: + The upload_date_index padded two digits ytdl_sub_input_url ~~~~~~~~~~~~~~~~~~ -The input URL used in ytdl-sub to create this entry. +:type: ``String`` +:description: + The input URL used in ytdl-sub to create this entry. diff --git a/docs/source/config_reference/scripting/scripting_functions.rst b/docs/source/config_reference/scripting/scripting_functions.rst index d757f07c..c271669e 100644 --- a/docs/source/config_reference/scripting/scripting_functions.rst +++ b/docs/source/config_reference/scripting/scripting_functions.rst @@ -603,7 +603,7 @@ Takes a date in the form of YYYYMMDD and returns a Map containing: - year (Integer) - month (Integer) - day (Integer) -- year_truncated (String, YY from YY[YY]) +- year_truncated (Integer, YY from YY[YY]) - month_padded (String) - day_padded (String) - year_truncated_reversed (Integer, 100 - year_truncated) diff --git a/src/ytdl_sub/entries/script/variable_definitions.py b/src/ytdl_sub/entries/script/variable_definitions.py index 3a61e62c..b05fcdfb 100644 --- a/src/ytdl_sub/entries/script/variable_definitions.py +++ b/src/ytdl_sub/entries/script/variable_definitions.py @@ -27,14 +27,16 @@ class MetadataVariableDefinitions(ABC): @cached_property def entry_metadata(self: "VariableDefinitions") -> MapVariable: """ - The entry's info.json + :description: + The entry's info.json """ return MapVariable(variable_name="entry_metadata", definition="{ {} }") @cached_property def playlist_metadata(self: "VariableDefinitions") -> MapMetadataVariable: """ - Metadata from the playlist (i.e. the parent metadata, like playlist -> entry) + :description: + Metadata from the playlist (i.e. the parent metadata, like playlist -> entry) """ return MapMetadataVariable.from_entry( metadata_key="playlist_metadata", @@ -44,7 +46,9 @@ class MetadataVariableDefinitions(ABC): @cached_property def source_metadata(self: "VariableDefinitions") -> MapMetadataVariable: """ - Metadata from the source (i.e. the grandparent metadata, like channel -> playlist -> entry) + :description: + Metadata from the source + (i.e. the grandparent metadata, like channel -> playlist -> entry) """ return MapMetadataVariable.from_entry( metadata_key="source_metadata", @@ -54,7 +58,8 @@ class MetadataVariableDefinitions(ABC): @cached_property def sibling_metadata(self: "VariableDefinitions") -> ArrayMetadataVariable: """ - Metadata from any sibling entries that reside in the same playlist as this entry. + :description: + Metadata from any sibling entries that reside in the same playlist as this entry. """ return ArrayMetadataVariable.from_entry( metadata_key="sibling_metadata", @@ -66,7 +71,8 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_uid(self: "VariableDefinitions") -> StringMetadataVariable: """ - The playlist unique ID if it exists, otherwise return the entry unique ID. + :description: + The playlist unique ID if it exists, otherwise return the entry unique ID. """ return StringMetadataVariable.from_playlist( metadata_key="playlist_id", variable_name="playlist_uid", default=self.uid @@ -75,7 +81,8 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_title(self: "VariableDefinitions") -> StringMetadataVariable: """ - Name of its parent playlist/channel if it exists, otherwise returns its title. + :description: + Name of its parent playlist/channel if it exists, otherwise returns its title. """ return StringMetadataVariable.from_playlist( metadata_key="playlist_title", default=self.title @@ -84,17 +91,19 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_index(self: "VariableDefinitions") -> IntegerMetadataVariable: """ - Playlist index if it exists, otherwise returns ``1``. + :description: + 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 IntegerMetadataVariable.from_entry(metadata_key="playlist_index", default=1) @cached_property def playlist_index_reversed(self: "VariableDefinitions") -> IntegerVariable: """ - Playlist index reversed via ``playlist_count - playlist_index + 1`` + :description: + Playlist index reversed via ``playlist_count - playlist_index + 1`` """ return IntegerVariable( variable_name="playlist_index_reversed", @@ -110,14 +119,16 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_index_padded(self: "VariableDefinitions") -> StringVariable: """ - playlist_index padded two digits + :description: + playlist_index padded two digits """ return self.playlist_index.to_padded_int(variable_name="playlist_index_padded", pad=2) @cached_property def playlist_index_reversed_padded(self: "VariableDefinitions") -> StringVariable: """ - playlist_index_reversed padded two digits + :description: + playlist_index_reversed padded two digits """ return self.playlist_index_reversed.to_padded_int( variable_name="playlist_index_reversed_padded", @@ -127,14 +138,16 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_index_padded6(self: "VariableDefinitions") -> StringVariable: """ - playlist_index padded six digits. + :description: + playlist_index padded six digits. """ return self.playlist_index.to_padded_int(variable_name="playlist_index_padded6", pad=6) @cached_property def playlist_index_reversed_padded6(self: "VariableDefinitions") -> StringVariable: """ - playlist_index_reversed padded six digits. + :description: + playlist_index_reversed padded six digits. """ return self.playlist_index_reversed.to_padded_int( variable_name="playlist_index_reversed_padded6", pad=6 @@ -143,17 +156,19 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_count(self: "VariableDefinitions") -> IntegerMetadataVariable: """ - Playlist count if it exists, otherwise returns ``1``. + :description: + 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 IntegerMetadataVariable.from_entry(metadata_key="playlist_count", default=1) @cached_property def playlist_description(self: "VariableDefinitions") -> StringMetadataVariable: """ - The playlist description if it exists, otherwise returns the entry's description. + :description: + The playlist description if it exists, otherwise returns the entry's description. """ return StringMetadataVariable.from_playlist( metadata_key=self.description.metadata_key, @@ -164,7 +179,8 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_webpage_url(self: "VariableDefinitions") -> StringMetadataVariable: """ - The playlist webpage url if it exists. Otherwise, returns the entry webpage url. + :description: + The playlist webpage url if it exists. Otherwise, returns the entry webpage url. """ return StringMetadataVariable.from_playlist( metadata_key=self.webpage_url.metadata_key, @@ -175,8 +191,9 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_max_upload_date(self: "VariableDefinitions") -> StringDateVariable: """ - Max upload_date for all entries in this entry's playlist if it exists, otherwise returns - ``upload_date`` + :description: + Max upload_date for all entries in this entry's playlist if it exists, otherwise returns + ``upload_date`` """ return StringVariable( variable_name="playlist_max_upload_date", @@ -194,8 +211,9 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_max_upload_year(self: "VariableDefinitions") -> IntegerVariable: """ - Max upload_year for all entries in this entry's playlist if it exists, otherwise returns - ``upload_year`` + :description: + Max upload_year for all entries in this entry's playlist if it exists, otherwise returns + ``upload_year`` """ return self.playlist_max_upload_date.get_integer_date_metadata( date_metadata_key="year", @@ -205,8 +223,9 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_max_upload_year_truncated(self: "VariableDefinitions") -> IntegerVariable: """ - The max playlist truncated upload year for all entries in this entry's playlist if it - exists, otherwise returns ``upload_year_truncated``. + :description: + The max playlist truncated upload year for all entries in this entry's playlist if it + exists, otherwise returns ``upload_year_truncated``. """ return self.playlist_max_upload_date.get_integer_date_metadata( date_metadata_key="year_truncated", variable_name="playlist_max_upload_year_truncated" @@ -215,7 +234,8 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_uploader_id(self: "VariableDefinitions") -> StringMetadataVariable: """ - The playlist uploader id if it exists, otherwise returns the entry uploader ID. + :description: + The playlist uploader id if it exists, otherwise returns the entry uploader ID. """ return StringMetadataVariable.from_entry( metadata_key="playlist_uploader_id", @@ -225,7 +245,8 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_uploader(self: "VariableDefinitions") -> StringMetadataVariable: """ - The playlist uploader if it exists, otherwise return the entry uploader. + :description: + The playlist uploader if it exists, otherwise return the entry uploader. """ return StringMetadataVariable.from_playlist( metadata_key=self.uploader.metadata_key, @@ -236,7 +257,8 @@ class PlaylistVariableDefinitions(ABC): @cached_property def playlist_uploader_url(self: "VariableDefinitions") -> StringMetadataVariable: """ - The playlist uploader url if it exists, otherwise returns the playlist webpage_url. + :description: + The playlist uploader url if it exists, otherwise returns the playlist webpage_url. """ return StringMetadataVariable.from_playlist( metadata_key=self.uploader_url.metadata_key, @@ -249,8 +271,9 @@ class SourceVariableDefinitions(ABC): @cached_property def source_title(self: "VariableDefinitions") -> StringMetadataVariable: """ - Name of the source (i.e. channel with multiple playlists) if it exists, otherwise - returns its playlist_title. + :description: + Name of the source (i.e. channel with multiple playlists) if it exists, otherwise + returns its playlist_title. """ return StringMetadataVariable.from_source( metadata_key=self.title.metadata_key, @@ -261,7 +284,8 @@ class SourceVariableDefinitions(ABC): @cached_property def source_uid(self: "VariableDefinitions") -> StringMetadataVariable: """ - The source unique id if it exists, otherwise returns the playlist unique ID. + :description: + The source unique id if it exists, otherwise returns the playlist unique ID. """ return StringMetadataVariable.from_source( metadata_key=self.uid.metadata_key, @@ -272,10 +296,11 @@ class SourceVariableDefinitions(ABC): @cached_property def source_index(self: "VariableDefinitions") -> IntegerMetadataVariable: """ - Source index if it exists, otherwise returns ``1``. + :description: + 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 IntegerMetadataVariable.from_playlist( metadata_key=self.playlist_index.metadata_key, @@ -286,14 +311,16 @@ class SourceVariableDefinitions(ABC): @cached_property def source_index_padded(self: "VariableDefinitions") -> StringVariable: """ - The source index, padded two digits. + :description: + The source index, padded two digits. """ return self.source_index.to_padded_int(variable_name="source_index_padded", pad=2) @cached_property def source_count(self: "VariableDefinitions") -> IntegerMetadataVariable: """ - The source count if it exists, otherwise returns ``1``. + :description: + The source count if it exists, otherwise returns ``1``. """ return IntegerMetadataVariable.from_playlist( metadata_key=self.playlist_count.metadata_key, @@ -304,7 +331,8 @@ class SourceVariableDefinitions(ABC): @cached_property def source_webpage_url(self: "VariableDefinitions") -> StringMetadataVariable: """ - The source webpage url if it exists, otherwise returns the playlist webpage url. + :description: + The source webpage url if it exists, otherwise returns the playlist webpage url. """ return StringMetadataVariable.from_source( metadata_key=self.webpage_url.metadata_key, @@ -315,7 +343,8 @@ class SourceVariableDefinitions(ABC): @cached_property def source_description(self: "VariableDefinitions") -> StringMetadataVariable: """ - The source description if it exists, otherwise returns the playlist description. + :description: + The source description if it exists, otherwise returns the playlist description. """ return StringMetadataVariable.from_source( metadata_key=self.description.metadata_key, @@ -326,7 +355,8 @@ class SourceVariableDefinitions(ABC): @cached_property def source_uploader_id(self: "VariableDefinitions") -> StringMetadataVariable: """ - The source uploader id if it exists, otherwise returns the playlist_uploader_id + :description: + The source uploader id if it exists, otherwise returns the playlist_uploader_id """ return StringMetadataVariable.from_source( metadata_key=self.uploader_id.metadata_key, @@ -337,7 +367,8 @@ class SourceVariableDefinitions(ABC): @cached_property def source_uploader(self: "VariableDefinitions") -> StringMetadataVariable: """ - The source uploader if it exists, otherwise return the playlist_uploader + :description: + The source uploader if it exists, otherwise return the playlist_uploader """ return StringMetadataVariable.from_source( metadata_key=self.uploader.metadata_key, @@ -348,7 +379,8 @@ class SourceVariableDefinitions(ABC): @cached_property def source_uploader_url(self: "VariableDefinitions") -> StringMetadataVariable: """ - The source uploader url if it exists, otherwise returns the source webpage_url. + :description: + The source uploader url if it exists, otherwise returns the source webpage_url. """ return StringMetadataVariable.from_source( metadata_key=self.uploader_url.metadata_key, @@ -361,14 +393,16 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_date(self: "VariableDefinitions") -> StringDateMetadataVariable: """ - The entry’s uploaded date, in YYYYMMDD format. If not present, return today’s date. + :description: + The entry’s uploaded date, in YYYYMMDD format. If not present, return today’s date. """ return StringDateMetadataVariable.from_entry(metadata_key="upload_date").as_date_variable() @cached_property def upload_year(self: "VariableDefinitions") -> IntegerVariable: """ - The entry's upload year + :description: + The entry's upload year """ return self.upload_date.get_integer_date_metadata( date_metadata_key="year", variable_name="upload_year" @@ -377,7 +411,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_year_truncated(self: "VariableDefinitions") -> IntegerVariable: """ - The last two digits of the upload year, i.e. 22 in 2022 + :description: + The last two digits of the upload year, i.e. 22 in 2022 """ return self.upload_date.get_integer_date_metadata( date_metadata_key="year_truncated", variable_name="upload_year_truncated" @@ -386,8 +421,9 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_year_truncated_reversed(self: "VariableDefinitions") -> IntegerVariable: """ - The upload year truncated, but reversed using ``100 - {upload_year_truncated}``, i.e. - 2022 returns ``100 - 22`` = ``78`` + :description: + The upload year truncated, but reversed using ``100 - {upload_year_truncated}``, i.e. + 2022 returns ``100 - 22`` = ``78`` """ return self.upload_date.get_integer_date_metadata( date_metadata_key="year_truncated_reversed", @@ -397,7 +433,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_month_reversed(self: "VariableDefinitions") -> IntegerVariable: """ - The upload month, but reversed using ``13 - {upload_month}``, i.e. March returns ``10`` + :description: + The upload month, but reversed using ``13 - {upload_month}``, i.e. March returns ``10`` """ return self.upload_date.get_integer_date_metadata( date_metadata_key="month_reversed", variable_name="upload_month_reversed" @@ -406,7 +443,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_month_reversed_padded(self: "VariableDefinitions") -> StringVariable: """ - The reversed upload month, but padded. i.e. November returns "02" + :description: + The reversed upload month, but padded. i.e. November returns "02" """ return self.upload_date.get_string_date_metadata( date_metadata_key="month_reversed_padded", variable_name="upload_month_reversed_padded" @@ -415,7 +453,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_month_padded(self: "VariableDefinitions") -> StringVariable: """ - The entry's upload month padded to two digits, i.e. March returns "03" + :description: + The entry's upload month padded to two digits, i.e. March returns "03" """ return self.upload_date.get_string_date_metadata( date_metadata_key="month_padded", variable_name="upload_month_padded" @@ -424,7 +463,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_day_padded(self: "VariableDefinitions") -> StringVariable: """ - The entry's upload day padded to two digits, i.e. the fifth returns "05" + :description: + The entry's upload day padded to two digits, i.e. the fifth returns "05" """ return self.upload_date.get_string_date_metadata( date_metadata_key="day_padded", variable_name="upload_day_padded" @@ -433,7 +473,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_month(self: "VariableDefinitions") -> IntegerVariable: """ - The upload month as an integer (no padding). + :description: + The upload month as an integer (no padding). """ return self.upload_date.get_integer_date_metadata( date_metadata_key="month", variable_name="upload_month" @@ -442,7 +483,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_day(self: "VariableDefinitions") -> IntegerVariable: """ - The upload day as an integer (no padding). + :description: + The upload day as an integer (no padding). """ return self.upload_date.get_integer_date_metadata( date_metadata_key="day", variable_name="upload_day" @@ -451,8 +493,9 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_day_reversed(self: "VariableDefinitions") -> IntegerVariable: """ - 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`` + :description: + 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 self.upload_date.get_integer_date_metadata( date_metadata_key="day_reversed", variable_name="upload_day_reversed" @@ -461,7 +504,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_day_reversed_padded(self: "VariableDefinitions") -> StringVariable: """ - The reversed upload day, but padded. i.e. August 30th returns "02". + :description: + The reversed upload day, but padded. i.e. August 30th returns "02". """ return self.upload_date.get_string_date_metadata( date_metadata_key="day_reversed_padded", variable_name="upload_day_reversed_padded" @@ -470,7 +514,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_day_of_year(self: "VariableDefinitions") -> IntegerVariable: """ - The day of the year, i.e. February 1st returns ``32`` + :description: + The day of the year, i.e. February 1st returns ``32`` """ return self.upload_date.get_integer_date_metadata( date_metadata_key="day_of_year", variable_name="upload_day_of_year" @@ -479,7 +524,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_day_of_year_padded(self: "VariableDefinitions") -> StringVariable: """ - The upload day of year, but padded i.e. February 1st returns "032" + :description: + The upload day of year, but padded i.e. February 1st returns "032" """ return self.upload_date.get_string_date_metadata( date_metadata_key="day_of_year_padded", variable_name="upload_day_of_year_padded" @@ -488,8 +534,9 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_day_of_year_reversed(self: "VariableDefinitions") -> IntegerVariable: """ - 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`` + :description: + 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 self.upload_date.get_integer_date_metadata( date_metadata_key="day_of_year_reversed", variable_name="upload_day_of_year_reversed" @@ -498,7 +545,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_day_of_year_reversed_padded(self: "VariableDefinitions") -> StringVariable: """ - The reversed upload day of year, but padded i.e. December 31st returns "001" + :description: + The reversed upload day of year, but padded i.e. December 31st returns "001" """ return self.upload_date.get_string_date_metadata( date_metadata_key="day_of_year_reversed_padded", @@ -508,7 +556,8 @@ class UploadDateVariableDefinitions(ABC): @cached_property def upload_date_standardized(self: "VariableDefinitions") -> StringVariable: """ - The uploaded date formatted as YYYY-MM-DD + :description: + The uploaded date formatted as YYYY-MM-DD """ return self.upload_date.get_string_date_metadata( date_metadata_key="date_standardized", variable_name="upload_date_standardized" @@ -519,7 +568,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_date(self: "VariableDefinitions") -> StringDateMetadataVariable: """ - The entry’s release date, in YYYYMMDD format. If not present, return the upload date. + :description: + The entry’s release date, in YYYYMMDD format. If not present, return the upload date. """ return StringMetadataVariable.from_entry( metadata_key="release_date", default=self.upload_date @@ -528,7 +578,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_year(self: "VariableDefinitions") -> IntegerVariable: """ - The entry's upload year + :description: + The entry's upload year """ return self.release_date.get_integer_date_metadata( date_metadata_key="year", variable_name="release_year" @@ -537,7 +588,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_year_truncated(self: "VariableDefinitions") -> IntegerVariable: """ - The last two digits of the upload year, i.e. 22 in 2022 + :description: + The last two digits of the upload year, i.e. 22 in 2022 """ return self.release_date.get_integer_date_metadata( date_metadata_key="year_truncated", variable_name="release_year_truncated" @@ -546,8 +598,9 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_year_truncated_reversed(self: "VariableDefinitions") -> IntegerVariable: """ - The upload year truncated, but reversed using ``100 - {release_year_truncated}``, i.e. - 2022 returns ``100 - 22`` = ``78`` + :description: + The upload year truncated, but reversed using ``100 - {release_year_truncated}``, i.e. + 2022 returns ``100 - 22`` = ``78`` """ return self.release_date.get_integer_date_metadata( date_metadata_key="year_truncated_reversed", @@ -557,7 +610,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_month_reversed(self: "VariableDefinitions") -> IntegerVariable: """ - The upload month, but reversed using ``13 - {release_month}``, i.e. March returns ``10`` + :description: + The upload month, but reversed using ``13 - {release_month}``, i.e. March returns ``10`` """ return self.release_date.get_integer_date_metadata( date_metadata_key="month_reversed", variable_name="release_month_reversed" @@ -566,7 +620,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_month_reversed_padded(self: "VariableDefinitions") -> StringVariable: """ - The reversed upload month, but padded. i.e. November returns "02" + :description: + The reversed upload month, but padded. i.e. November returns "02" """ return self.release_date.get_string_date_metadata( date_metadata_key="month_reversed_padded", variable_name="release_month_reversed_padded" @@ -575,7 +630,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_month_padded(self: "VariableDefinitions") -> StringVariable: """ - The entry's upload month padded to two digits, i.e. March returns "03" + :description: + The entry's upload month padded to two digits, i.e. March returns "03" """ return self.release_date.get_string_date_metadata( date_metadata_key="month_padded", variable_name="release_month_padded" @@ -584,7 +640,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_day_padded(self: "VariableDefinitions") -> StringVariable: """ - The entry's upload day padded to two digits, i.e. the fifth returns "05" + :description: + The entry's upload day padded to two digits, i.e. the fifth returns "05" """ return self.release_date.get_string_date_metadata( date_metadata_key="day_padded", variable_name="release_day_padded" @@ -593,7 +650,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_month(self: "VariableDefinitions") -> IntegerVariable: """ - The upload month as an integer (no padding). + :description: + The upload month as an integer (no padding). """ return self.release_date.get_integer_date_metadata( date_metadata_key="month", variable_name="release_month" @@ -602,7 +660,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_day(self: "VariableDefinitions") -> IntegerVariable: """ - The upload day as an integer (no padding). + :description: + The upload day as an integer (no padding). """ return self.release_date.get_integer_date_metadata( date_metadata_key="day", variable_name="release_day" @@ -611,8 +670,9 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_day_reversed(self: "VariableDefinitions") -> IntegerVariable: """ - The upload 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`` + :description: + The upload 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 self.release_date.get_integer_date_metadata( date_metadata_key="day_reversed", variable_name="release_day_reversed" @@ -621,7 +681,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_day_reversed_padded(self: "VariableDefinitions") -> StringVariable: """ - The reversed upload day, but padded. i.e. August 30th returns "02". + :description: + The reversed upload day, but padded. i.e. August 30th returns "02". """ return self.release_date.get_string_date_metadata( date_metadata_key="day_reversed_padded", variable_name="release_day_reversed_padded" @@ -630,7 +691,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_day_of_year(self: "VariableDefinitions") -> IntegerVariable: """ - The day of the year, i.e. February 1st returns ``32`` + :description: + The day of the year, i.e. February 1st returns ``32`` """ return self.release_date.get_integer_date_metadata( date_metadata_key="day_of_year", variable_name="release_day_of_year" @@ -639,7 +701,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_day_of_year_padded(self: "VariableDefinitions") -> StringVariable: """ - The upload day of year, but padded i.e. February 1st returns "032" + :description: + The upload day of year, but padded i.e. February 1st returns "032" """ return self.release_date.get_string_date_metadata( date_metadata_key="day_of_year_padded", variable_name="release_day_of_year_padded" @@ -648,8 +711,9 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_day_of_year_reversed(self: "VariableDefinitions") -> IntegerVariable: """ - The upload 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`` + :description: + The upload 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 self.release_date.get_integer_date_metadata( date_metadata_key="day_of_year_reversed", variable_name="release_day_of_year_reversed" @@ -658,7 +722,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_day_of_year_reversed_padded(self: "VariableDefinitions") -> StringVariable: """ - The reversed upload day of year, but padded i.e. December 31st returns "001" + :description: + The reversed upload day of year, but padded i.e. December 31st returns "001" """ return self.release_date.get_string_date_metadata( date_metadata_key="day_of_year_reversed_padded", @@ -668,7 +733,8 @@ class ReleaseDateVariableDefinitions(ABC): @cached_property def release_date_standardized(self: "VariableDefinitions") -> StringVariable: """ - The uploaded date formatted as YYYY-MM-DD + :description: + The uploaded date formatted as YYYY-MM-DD """ return self.release_date.get_string_date_metadata( date_metadata_key="date_standardized", variable_name="release_date_standardized" @@ -679,43 +745,49 @@ class YtdlSubVariableDefinitions(ABC): @cached_property def ytdl_sub_input_url(self: "VariableDefinitions") -> StringVariable: """ - The input URL used in ytdl-sub to create this entry. + :description: + The input URL used in ytdl-sub to create this entry. """ return StringVariable(variable_name="ytdl_sub_input_url", definition="{ %string('') }") @cached_property def download_index(self: "VariableDefinitions") -> IntegerVariable: """ - The i'th entry downloaded. NOTE that this is fetched dynamically from the download - archive. + :description: + The i'th entry downloaded. NOTE that this is fetched dynamically from the download + archive. """ return IntegerVariable(variable_name="download_index", definition="{ %int(1) }") @cached_property def download_index_padded6(self: "VariableDefinitions") -> StringVariable: """ - The download_index padded six digits + :description: + The download_index padded six digits """ return self.download_index.to_padded_int(variable_name="download_index_padded6", pad=6) @cached_property def upload_date_index(self: "VariableDefinitions") -> IntegerVariable: """ - The i'th entry downloaded with this upload date. + :description: + The i'th entry downloaded with this upload date. """ return IntegerVariable(variable_name="upload_date_index", definition="{ %int(1) }") @cached_property def upload_date_index_padded(self: "VariableDefinitions") -> StringVariable: """ - The upload_date_index padded two digits + :description: + The upload_date_index padded two digits """ return self.upload_date_index.to_padded_int(variable_name="upload_date_index_padded", pad=2) @cached_property def upload_date_index_reversed(self: "VariableDefinitions") -> IntegerVariable: """ - 100 - upload_date_index + :description: + 100 - upload_date_index """ return IntegerVariable( variable_name="upload_date_index_reversed", @@ -725,7 +797,8 @@ class YtdlSubVariableDefinitions(ABC): @cached_property def upload_date_index_reversed_padded(self: "VariableDefinitions") -> StringVariable: """ - The upload_date_index padded two digits + :description: + The upload_date_index padded two digits """ return self.upload_date_index_reversed.to_padded_int( variable_name="upload_date_index_reversed_padded", pad=2 @@ -736,58 +809,66 @@ class EntryVariableDefinitions(ABC): @cached_property def uid(self: "VariableDefinitions") -> StringMetadataVariable: """ - The entry's unique ID + :description: + The entry's unique ID """ return StringMetadataVariable.from_entry(metadata_key="id", variable_name="uid") @cached_property def duration(self: "VariableDefinitions") -> IntegerMetadataVariable: """ - The duration of the entry in seconds if it exists. Defaults to zero otherwise. + :description: + The duration of the entry in seconds if it exists. Defaults to zero otherwise. """ return IntegerMetadataVariable.from_entry(metadata_key="duration", default=0) @cached_property def uid_sanitized_plex(self: "VariableDefinitions") -> StringVariable: """ - The sanitized uid with additional sanitizing for Plex. Replaces numbers with - fixed-width numbers so Plex does not recognize them as season or episode numbers. + :description: + The sanitized uid with additional sanitizing for Plex. Replaces numbers with + fixed-width numbers so Plex does not recognize them as season or episode numbers. """ return self.uid.to_sanitized_plex(variable_name="uid_sanitized_plex") @cached_property def ie_key(self: "VariableDefinitions") -> StringMetadataVariable: """ - The ie_key, used in legacy yt-dlp things as the 'info-extractor key'. - If it does not exist, return ``extractor_key`` + :description: + The ie_key, used in legacy yt-dlp things as the 'info-extractor key'. + If it does not exist, return ``extractor_key`` """ return StringMetadataVariable.from_entry(metadata_key="ie_key", default=self.extractor_key) @cached_property def extractor_key(self: "VariableDefinitions") -> StringMetadataVariable: """ - The yt-dlp extractor key + :description: + The yt-dlp extractor key """ return StringMetadataVariable.from_entry(metadata_key="extractor_key") @cached_property def extractor(self: "VariableDefinitions") -> StringMetadataVariable: """ - The yt-dlp extractor name + :description: + The yt-dlp extractor name """ return StringMetadataVariable.from_entry(metadata_key="extractor") @cached_property def epoch(self: "VariableDefinitions") -> IntegerMetadataVariable: """ - The unix epoch of when the metadata was scraped by yt-dlp. + :description: + The unix epoch of when the metadata was scraped by yt-dlp. """ return IntegerMetadataVariable.from_entry(metadata_key="epoch") @cached_property def epoch_date(self: "VariableDefinitions") -> StringVariable: """ - The epoch's date, in YYYYMMDD format. + :description: + The epoch's date, in YYYYMMDD format. """ return StringVariable( variable_name="epoch_date", @@ -797,7 +878,8 @@ class EntryVariableDefinitions(ABC): @cached_property def epoch_hour(self: "VariableDefinitions") -> StringVariable: """ - The epoch's hour + :description: + The epoch's hour """ return StringVariable( variable_name="epoch_hour", @@ -807,29 +889,33 @@ class EntryVariableDefinitions(ABC): @cached_property def title(self: "VariableDefinitions") -> StringMetadataVariable: """ - The title of the entry. If a title does not exist, returns its unique ID. + :description: + The title of the entry. If a title does not exist, returns its unique ID. """ return StringMetadataVariable.from_entry(metadata_key="title", default=self.uid) @cached_property def title_sanitized_plex(self: "VariableDefinitions") -> StringVariable: """ - The sanitized title with additional sanitizing for Plex. It replaces numbers with - fixed-width numbers so Plex does not recognize them as season or episode numbers. + :description: + The sanitized title with additional sanitizing for Plex. It replaces numbers with + fixed-width numbers so Plex does not recognize them as season or episode numbers. """ return self.title.to_sanitized_plex(variable_name="title_sanitized_plex") @cached_property def webpage_url(self: "VariableDefinitions") -> StringMetadataVariable: """ - The url to the webpage. + :description: + The url to the webpage. """ return StringMetadataVariable.from_entry(metadata_key="webpage_url") @cached_property def info_json_ext(self: "VariableDefinitions") -> StringVariable: """ - The "info.json" extension + :description: + The "info.json" extension """ return StringVariable( variable_name="info_json_ext", @@ -839,7 +925,8 @@ class EntryVariableDefinitions(ABC): @cached_property def description(self: "VariableDefinitions") -> StringMetadataVariable: """ - The description if it exists. Otherwise, returns an emtpy string. + :description: + The description if it exists. Otherwise, returns an emtpy string. """ return StringMetadataVariable.from_entry( metadata_key="description", @@ -849,7 +936,8 @@ class EntryVariableDefinitions(ABC): @cached_property def uploader_id(self: "VariableDefinitions") -> StringMetadataVariable: """ - The uploader id if it exists, otherwise return the unique ID. + :description: + The uploader id if it exists, otherwise return the unique ID. """ return StringMetadataVariable.from_entry( metadata_key="uploader_id", @@ -859,7 +947,8 @@ class EntryVariableDefinitions(ABC): @cached_property def uploader(self: "VariableDefinitions") -> StringMetadataVariable: """ - The uploader if it exists, otherwise return the uploader ID. + :description: + The uploader if it exists, otherwise return the uploader ID. """ return StringMetadataVariable.from_entry( metadata_key="uploader", @@ -869,7 +958,8 @@ class EntryVariableDefinitions(ABC): @cached_property def uploader_url(self: "VariableDefinitions") -> StringMetadataVariable: """ - The uploader url if it exists, otherwise returns the webpage_url. + :description: + The uploader url if it exists, otherwise returns the webpage_url. """ return StringMetadataVariable.from_entry( metadata_key="uploader_url", @@ -879,7 +969,8 @@ class EntryVariableDefinitions(ABC): @cached_property def creator(self: "VariableDefinitions") -> StringMetadataVariable: """ - The creator name if it exists, otherwise returns the channel. + :description: + The creator name if it exists, otherwise returns the channel. """ return StringMetadataVariable.from_entry( metadata_key="creator", @@ -889,7 +980,8 @@ class EntryVariableDefinitions(ABC): @cached_property def channel(self: "VariableDefinitions") -> StringMetadataVariable: """ - The channel name if it exists, otherwise returns the uploader. + :description: + The channel name if it exists, otherwise returns the uploader. """ return StringMetadataVariable.from_entry( metadata_key="channel", @@ -899,7 +991,8 @@ class EntryVariableDefinitions(ABC): @cached_property def channel_id(self: "VariableDefinitions") -> StringMetadataVariable: """ - The channel id if it exists, otherwise returns the entry uploader ID. + :description: + The channel id if it exists, otherwise returns the entry uploader ID. """ return StringMetadataVariable.from_entry( metadata_key="channel_id", @@ -909,15 +1002,17 @@ class EntryVariableDefinitions(ABC): @cached_property def ext(self: "VariableDefinitions") -> StringMetadataVariable: """ - The downloaded entry's file extension + :description: + The downloaded entry's file extension """ return StringMetadataVariable.from_entry(metadata_key="ext") @cached_property def thumbnail_ext(self: "VariableDefinitions") -> StringVariable: """ - 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. + :description: + 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 StringVariable( variable_name="thumbnail_ext", @@ -927,7 +1022,8 @@ class EntryVariableDefinitions(ABC): @cached_property def comments(self: "VariableDefinitions") -> ArrayMetadataVariable: """ - Comments if they are requested + :description: + Comments if they are requested """ return ArrayMetadataVariable( metadata_key="comments", variable_name="comments", definition="{ [] }" @@ -936,7 +1032,8 @@ class EntryVariableDefinitions(ABC): @cached_property def chapters(self: "VariableDefinitions") -> ArrayMetadataVariable: """ - Chapters if they exist + :description: + Chapters if they exist """ return ArrayMetadataVariable( metadata_key="chapters", variable_name="chapters", definition="{ [] }" @@ -945,7 +1042,8 @@ class EntryVariableDefinitions(ABC): @cached_property def sponsorblock_chapters(self: "VariableDefinitions") -> ArrayMetadataVariable: """ - Sponsorblock Chapters if they are requested and exist + :description: + Sponsorblock Chapters if they are requested and exist """ return ArrayMetadataVariable( metadata_key="sponsorblock_chapters", @@ -956,7 +1054,8 @@ class EntryVariableDefinitions(ABC): @cached_property def requested_subtitles(self: "VariableDefinitions") -> MapMetadataVariable: """ - Subtitles if they are requested and exist + :description: + Subtitles if they are requested and exist """ return MapMetadataVariable( metadata_key="requested_subtitles", diff --git a/tools/docgen/entry_variables.py b/tools/docgen/entry_variables.py index 02cca731..df53b13a 100644 --- a/tools/docgen/entry_variables.py +++ b/tools/docgen/entry_variables.py @@ -4,11 +4,12 @@ from typing import Dict from typing import Type from tools.docgen.docgen import DocGen +from tools.docgen.utils import cached_properties from tools.docgen.utils import camel_case_to_human from tools.docgen.utils import get_function_docs from tools.docgen.utils import line_section -from tools.docgen.utils import properties from tools.docgen.utils import section +from ytdl_sub.entries.script.variable_definitions import VARIABLES from ytdl_sub.entries.script.variable_definitions import VariableDefinitions @@ -37,10 +38,11 @@ class EntryVariablesDocGen(DocGen): docs += line_section(section_idx=idx) docs += section(name, level=1) - for variable_function_name in properties(parent_objs[name]): + for variable_function_name in cached_properties(parent_objs[name]): docs += get_function_docs( function_name=variable_function_name, obj=parent_objs[name], + pre_docstring=f":type: ``{getattr(VARIABLES, variable_function_name).human_readable_type()}``\n", level=2, ) diff --git a/tools/docgen/utils.py b/tools/docgen/utils.py index 94cab101..81ddc3fa 100644 --- a/tools/docgen/utils.py +++ b/tools/docgen/utils.py @@ -1,4 +1,5 @@ import inspect +from functools import cached_property from typing import Any from typing import Dict from typing import List @@ -18,6 +19,10 @@ def properties(obj: Type[Any]) -> List[str]: return sorted(prop for prop in dir(obj) if isinstance(getattr(obj, prop), property)) +def cached_properties(obj: Type[Any]) -> List[str]: + return sorted(prop for prop in dir(obj) if isinstance(getattr(obj, prop), cached_property)) + + def static_methods(obj: Type[Any]) -> List[str]: return sorted( name for name in dir(obj) if isinstance(inspect.getattr_static(obj, name), staticmethod) @@ -36,11 +41,16 @@ def camel_case_to_human(string: str) -> str: def get_function_docs( - function_name: str, obj: Any, level: int, display_function_name: Optional[str] = None + function_name: str, + obj: Any, + level: int, + display_function_name: Optional[str] = None, + pre_docstring: Optional[str] = None, ) -> str: display_function_name = display_function_name if display_function_name else function_name docs = section(display_function_name, level=level) + docs += pre_docstring or "" docs += inspect.cleandoc(getattr(obj, function_name).__doc__) docs += "\n" return docs