diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 6a48e5f0..7e551b67 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -53,6 +53,7 @@ html_theme_options = {
}
html_static_path = ["_static"]
+html_css_files = ["custom.css"]
# Make sure the all autosectionlabel targets are unique
diff --git a/docs/source/config_reference/plugins.rst b/docs/source/config_reference/plugins.rst
index 69e3de7e..cdec956b 100644
--- a/docs/source/config_reference/plugins.rst
+++ b/docs/source/config_reference/plugins.rst
@@ -26,6 +26,8 @@ quality
Optional. Specify ffmpeg audio quality. Insert a value between ``0`` (better) and ``9``
(worse) for variable bitrate, or a specific bitrate like ``128`` for 128k.
+----------------------------------------------------------------------------------------------------
+
chapters
--------
Embeds chapters to video files if they are present. Additional options to add SponsorBlock
@@ -89,6 +91,8 @@ Optional. List of SponsorBlock categories to embed as chapters. Supports "sponso
"intro", "outro", "selfpromo", "preview", "filler", "interaction", "music_offtopic",
"poi_highlight", or "all" to include all categories.
+----------------------------------------------------------------------------------------------------
+
date_range
----------
Only download files uploaded within the specified date range.
@@ -111,6 +115,8 @@ before
~~~~~~
Optional. Only download videos before this datetime.
+----------------------------------------------------------------------------------------------------
+
embed_thumbnail
---------------
Whether to embed thumbnails to the audio/video file or not.
@@ -123,6 +129,8 @@ Usage:
my_example_preset:
embed_thumbnail: True
+----------------------------------------------------------------------------------------------------
+
file_convert
------------
Converts video files from one extension to another.
@@ -176,6 +184,8 @@ form of:
The output file will use the extension specified in ``convert_to``. Post-processing args
can still be set with ``convert_with`` set to ``yt-dlp``.
+----------------------------------------------------------------------------------------------------
+
filter_exclude
--------------
Applies a conditional OR on any number of filters comprised of either variables or scripts.
@@ -188,8 +198,12 @@ Usage:
presets:
my_example_preset:
filter_exclude:
- - { %contains( %lower(title), '#short' ) }
- - { %contains( %lower(description), '#short' ) }
+ - >-
+ { %contains( %lower(title), '#short' ) }
+ - >-
+ { %contains( %lower(description), '#short' ) }
+
+----------------------------------------------------------------------------------------------------
filter_include
--------------
@@ -203,7 +217,8 @@ Usage:
presets:
my_example_preset:
filter_include:
- - {description}
+ - >-
+ {description}
- >-
{
%regex_search_any(
@@ -215,6 +230,8 @@ Usage:
)
}
+----------------------------------------------------------------------------------------------------
+
format
------
Set ``--format`` to pass into yt-dlp to download a specific format quality.
@@ -232,6 +249,8 @@ format
~~~~~~
yt-dlp format, uses same syntax as yt-dlp.
+----------------------------------------------------------------------------------------------------
+
match_filters
-------------
Set ``--match-filters``` to pass into yt-dlp to filter entries from being downloaded.
@@ -267,6 +286,8 @@ The filters themselves. If used multiple times, the filter matches if at least o
conditions are met. For logical AND's between match filters, use the ``&`` operator in
a single match filter. These are applied when gathering metadata.
+----------------------------------------------------------------------------------------------------
+
music_tags
----------
Adds tags to every download audio file using
@@ -304,6 +325,8 @@ tags
Key, values of tag names, tag values. Supports source and override variables.
Supports lists which will get written to MP3s as id3v2.4 multi-tags.
+----------------------------------------------------------------------------------------------------
+
nfo_tags
--------
Adds an NFO file for every download file. An NFO file is simply an XML file
@@ -380,6 +403,8 @@ Which translates to
Comedy
Drama
+----------------------------------------------------------------------------------------------------
+
output_directory_nfo_tags
-------------------------
Adds a single NFO file in the output directory. An NFO file is simply an XML file with a
@@ -453,6 +478,8 @@ Which translates to
Comedy
Drama
+----------------------------------------------------------------------------------------------------
+
output_options
--------------
Defines where to output files and thumbnails after all post-processing has completed.
@@ -544,6 +571,8 @@ Optional. The file name for the media's thumbnail image. This can include direct
as ``"Season {upload_year}/{title}.{thumbnail_ext}"``, and will be placed in the output
directory. Can be set to empty string or `null` to disable thumbnail writes.
+----------------------------------------------------------------------------------------------------
+
overrides
---------
Optional. This section allows you to define variables that can be used in any string formatter.
@@ -571,6 +600,8 @@ In addition, any override variable defined will automatically create a ``sanitiz
for use. In the example above, ``output_directory_sanitized`` will exist and perform
sanitization on the value when used.
+----------------------------------------------------------------------------------------------------
+
regex
-----
Performs regex matching on an entry's source or override variables. Regex can be used to filter
@@ -639,6 +670,8 @@ skip_if_match_fails
Defaults to True. If True, when any match fails and has no defaults, the entry will be
skipped. If False, ytdl-sub will error and all downloads will not proceed.
+----------------------------------------------------------------------------------------------------
+
split_by_chapters
-----------------
Splits a file by chapters into multiple files. Each file becomes its own entry with the
@@ -665,6 +698,8 @@ when_no_chapters
Behavior to perform when no chapters are present. Supports "pass" (continue processing),
"drop" (exclude it from output), and "error" (stop processing for everything).
+----------------------------------------------------------------------------------------------------
+
subtitles
---------
Defines how to download and store subtitles. Using this plugin creates two new variables:
@@ -709,6 +744,8 @@ subtitles_type
~~~~~~~~~~~~~~
Optional. One of the subtitle file types "srt", "vtt", "ass", "lrc". Defaults to "srt"
+----------------------------------------------------------------------------------------------------
+
throttle_protection
-------------------
Provides options to make ytdl-sub look more 'human-like' to protect from throttling. For
@@ -752,6 +789,8 @@ Probability to perform any downloads, recomputed for each subscription. This is
recommended to set if you run ytdl-sub in a cron-job, that way you are statistically
guaranteed over time to eventually download the subscription.
+----------------------------------------------------------------------------------------------------
+
video_tags
----------
Adds tags to every downloaded video file using ffmpeg ``-metadata key=value`` args.
@@ -771,6 +810,8 @@ tags
~~~~
Key/values of tag names/values. Supports source and override variables.
+----------------------------------------------------------------------------------------------------
+
ytdl_options
------------
Optional. This section allows you to add any ytdl argument to ytdl-sub's downloader.
diff --git a/docs/source/config_reference/scripting/entry_variables.rst b/docs/source/config_reference/scripting/entry_variables.rst
index 300b558e..c4467330 100644
--- a/docs/source/config_reference/scripting/entry_variables.rst
+++ b/docs/source/config_reference/scripting/entry_variables.rst
@@ -112,6 +112,8 @@ webpage_url
~~~~~~~~~~~
The url to the webpage.
+----------------------------------------------------------------------------------------------------
+
Metadata Variables
------------------
@@ -131,6 +133,8 @@ source_metadata
~~~~~~~~~~~~~~~
Metadata from the source (i.e. the grandparent metadata, like channel -> playlist -> entry)
+----------------------------------------------------------------------------------------------------
+
Playlist Variables
------------------
@@ -211,6 +215,8 @@ playlist_webpage_url
~~~~~~~~~~~~~~~~~~~~
The playlist webpage url if it exists. Otherwise, returns the entry webpage url.
+----------------------------------------------------------------------------------------------------
+
Release Date Variables
----------------------
@@ -286,6 +292,8 @@ release_year_truncated_reversed
The release year truncated, but reversed using ``100 - {release_year_truncated}``, i.e.
2022 returns ``100 - 22`` = ``78``
+----------------------------------------------------------------------------------------------------
+
Source Variables
----------------
@@ -333,6 +341,8 @@ source_webpage_url
~~~~~~~~~~~~~~~~~~
The source webpage url if it exists, otherwise returns the playlist webpage url.
+----------------------------------------------------------------------------------------------------
+
Upload Date Variables
---------------------
@@ -407,6 +417,8 @@ upload_year_truncated_reversed
The upload year truncated, but reversed using ``100 - {upload_year_truncated}``, i.e.
2022 returns ``100 - 22`` = ``78``
+----------------------------------------------------------------------------------------------------
+
Ytdl-Sub Variables
------------------
diff --git a/docs/source/config_reference/scripting/scripting_functions.rst b/docs/source/config_reference/scripting/scripting_functions.rst
index 5ce92108..d757f07c 100644
--- a/docs/source/config_reference/scripting/scripting_functions.rst
+++ b/docs/source/config_reference/scripting/scripting_functions.rst
@@ -7,473 +7,571 @@ Array Functions
array
~~~~~
-``array(maybe_array: AnyArgument) -> Array``
+:spec: ``array(maybe_array: AnyArgument) -> Array``
-Tries to cast an unknown variable type to an Array.
+:description:
+ Tries to cast an unknown variable type to an Array.
array_apply
~~~~~~~~~~~
-``array_apply(array: Array, lambda_function: Lambda) -> Array``
+:spec: ``array_apply(array: Array, lambda_function: Lambda) -> Array``
-Apply a lambda function on every element in the Array.
+:description:
+ Apply a lambda function on every element in the Array.
+:usage:
+
+.. code-block:: python
+
+ {
+ %array_apply( [1, 2, 3] , %string )
+ }
+
+ # ["1", "2", "3"]
array_apply_fixed
~~~~~~~~~~~~~~~~~
-``array_apply_fixed(array: Array, fixed_argument: AnyArgument, lambda2_function: LambdaTwo, reverse_args: Optional[Boolean]) -> Array``
+:spec: ``array_apply_fixed(array: Array, fixed_argument: AnyArgument, lambda2_function: LambdaTwo, reverse_args: Optional[Boolean]) -> Array``
-Apply a lambda function on every element in the Array, with ``fixed_argument``
-passed as a second argument to every invocation.
+:description:
+ Apply a lambda function on every element in the Array, with ``fixed_argument``
+ passed as a second argument to every invocation.
array_at
~~~~~~~~
-``array_at(array: Array, idx: Integer) -> AnyArgument``
+:spec: ``array_at(array: Array, idx: Integer) -> AnyArgument``
-Return the element in the Array at index ``idx``.
+:description:
+ Return the element in the Array at index ``idx``.
array_contains
~~~~~~~~~~~~~~
-``array_contains(array: Array, value: AnyArgument) -> Boolean``
+:spec: ``array_contains(array: Array, value: AnyArgument) -> Boolean``
-Return True if the value exists in the Array. False otherwise.
+:description:
+ Return True if the value exists in the Array. False otherwise.
array_enumerate
~~~~~~~~~~~~~~~
-``array_enumerate(array: Array, lambda_function: LambdaTwo) -> Array``
+:spec: ``array_enumerate(array: Array, lambda_function: LambdaTwo) -> Array``
-Apply a lambda function on every element in the Array, where each arg
-passed to the lambda function is ``idx, element`` as two separate args.
+:description:
+ Apply a lambda function on every element in the Array, where each arg
+ passed to the lambda function is ``idx, element`` as two separate args.
array_extend
~~~~~~~~~~~~
-``array_extend(arrays: Array, ...) -> Array``
+:spec: ``array_extend(arrays: Array, ...) -> Array``
-Combine multiple Arrays into a single Array.
+:description:
+ Combine multiple Arrays into a single Array.
array_first
~~~~~~~~~~~
-``array_first(array: Array, fallback: AnyArgument) -> AnyArgument``
+:spec: ``array_first(array: Array, fallback: AnyArgument) -> AnyArgument``
-Returns the first element whose boolean conversion is True. Returns fallback
-if all elements evaluate to False.
+:description:
+ Returns the first element whose boolean conversion is True. Returns fallback
+ if all elements evaluate to False.
array_flatten
~~~~~~~~~~~~~
-``array_flatten(array: Array) -> Array``
+:spec: ``array_flatten(array: Array) -> Array``
-Flatten any nested Arrays into a single-dimensional Array.
+:description:
+ Flatten any nested Arrays into a single-dimensional Array.
array_index
~~~~~~~~~~~
-``array_index(array: Array, value: AnyArgument) -> Integer``
+:spec: ``array_index(array: Array, value: AnyArgument) -> Integer``
-Return the index of the value within the Array if it exists. If it does not, it will
-throw an error.
+:description:
+ Return the index of the value within the Array if it exists. If it does not, it will
+ throw an error.
array_overlay
~~~~~~~~~~~~~
-``array_overlay(array: Array, overlap: Array, only_missing: Optional[Boolean]) -> Array``
+:spec: ``array_overlay(array: Array, overlap: Array, only_missing: Optional[Boolean]) -> Array``
-Overlaps ``overlap`` onto ``array``. Can optionally only overlay missing indices.
+:description:
+ Overlaps ``overlap`` onto ``array``. Can optionally only overlay missing indices.
array_product
~~~~~~~~~~~~~
-``array_product(arrays: Array, ...) -> Array``
+:spec: ``array_product(arrays: Array, ...) -> Array``
-Returns the Cartesian product of elements from different arrays
+:description:
+ Returns the Cartesian product of elements from different arrays
array_reduce
~~~~~~~~~~~~
-``array_reduce(array: Array, lambda_reduce_function: LambdaReduce) -> AnyArgument``
+:spec: ``array_reduce(array: Array, lambda_reduce_function: LambdaReduce) -> AnyArgument``
-Apply a reduce function on pairs of elements in the Array, until one element remains.
-Executes using the left-most and reduces in the right direction.
+:description:
+ Apply a reduce function on pairs of elements in the Array, until one element remains.
+ Executes using the left-most and reduces in the right direction.
array_reverse
~~~~~~~~~~~~~
-``array_reverse(array: Array) -> Array``
+:spec: ``array_reverse(array: Array) -> Array``
-Reverse an Array.
+:description:
+ Reverse an Array.
array_size
~~~~~~~~~~
-``array_size(array: Array) -> Integer``
+:spec: ``array_size(array: Array) -> Integer``
-Returns the size of an Array.
+:description:
+ Returns the size of an Array.
array_slice
~~~~~~~~~~~
-``array_slice(array: Array, start: Integer, end: Optional[Integer]) -> Array``
+:spec: ``array_slice(array: Array, start: Integer, end: Optional[Integer]) -> Array``
-Returns the slice of the Array.
+:description:
+ Returns the slice of the Array.
+
+----------------------------------------------------------------------------------------------------
Boolean Functions
-----------------
and
~~~
-``and(values: AnyArgument, ...) -> Boolean``
+:spec: ``and(values: AnyArgument, ...) -> Boolean``
-``and`` operator. Returns True if all values evaluate to True. False otherwise.
+:description:
+ ``and`` operator. Returns True if all values evaluate to True. False otherwise.
bool
~~~~
-``bool(value: AnyArgument) -> Boolean``
+:spec: ``bool(value: AnyArgument) -> Boolean``
-Cast any type to a Boolean.
+:description:
+ Cast any type to a Boolean.
eq
~~
-``eq(left: AnyArgument, right: AnyArgument) -> Boolean``
+:spec: ``eq(left: AnyArgument, right: AnyArgument) -> Boolean``
-``==`` operator. Returns True if left == right. False otherwise.
+:description:
+ ``==`` operator. Returns True if left == right. False otherwise.
gt
~~
-``gt(left: AnyArgument, right: AnyArgument) -> Boolean``
+:spec: ``gt(left: AnyArgument, right: AnyArgument) -> Boolean``
-``>`` operator. Returns True if left > right. False otherwise.
+:description:
+ ``>`` operator. Returns True if left > right. False otherwise.
gte
~~~
-``gte(left: AnyArgument, right: AnyArgument) -> Boolean``
+:spec: ``gte(left: AnyArgument, right: AnyArgument) -> Boolean``
-``>=`` operator. Returns True if left >= right. False otherwise.
+:description:
+ ``>=`` operator. Returns True if left >= right. False otherwise.
is_null
~~~~~~~
-``is_null(value: AnyArgument) -> Boolean``
+:spec: ``is_null(value: AnyArgument) -> Boolean``
-Returns True if a value is null (i.e. an empty string). False otherwise.
+:description:
+ Returns True if a value is null (i.e. an empty string). False otherwise.
lt
~~
-``lt(left: AnyArgument, right: AnyArgument) -> Boolean``
+:spec: ``lt(left: AnyArgument, right: AnyArgument) -> Boolean``
-``<`` operator. Returns True if left < right. False otherwise.
+:description:
+ ``<`` operator. Returns True if left < right. False otherwise.
lte
~~~
-``lte(left: AnyArgument, right: AnyArgument) -> Boolean``
+:spec: ``lte(left: AnyArgument, right: AnyArgument) -> Boolean``
-``<=`` operator. Returns True if left <= right. False otherwise.
+:description:
+ ``<=`` operator. Returns True if left <= right. False otherwise.
ne
~~
-``ne(left: AnyArgument, right: AnyArgument) -> Boolean``
+:spec: ``ne(left: AnyArgument, right: AnyArgument) -> Boolean``
-``!=`` operator. Returns True if left != right. False otherwise.
+:description:
+ ``!=`` operator. Returns True if left != right. False otherwise.
not
~~~
-``not(value: Boolean) -> Boolean``
+:spec: ``not(value: Boolean) -> Boolean``
-``not`` operator. Returns the opposite of value.
+:description:
+ ``not`` operator. Returns the opposite of value.
or
~~
-``or(values: AnyArgument, ...) -> Boolean``
+:spec: ``or(values: AnyArgument, ...) -> Boolean``
-``or`` operator. Returns True if any value evaluates to True. False otherwise.
+:description:
+ ``or`` operator. Returns True if any value evaluates to True. False otherwise.
xor
~~~
-``xor(values: AnyArgument, ...) -> Boolean``
+:spec: ``xor(values: AnyArgument, ...) -> Boolean``
-``^`` operator. Returns True if exactly one value is set to True. False otherwise.
+:description:
+ ``^`` operator. Returns True if exactly one value is set to True. False otherwise.
+
+----------------------------------------------------------------------------------------------------
Conditional Functions
---------------------
if
~~
-``if(condition: Boolean, true: ReturnableArgumentA, false: ReturnableArgumentB) -> Union[ReturnableArgumentA, ReturnableArgumentB]``
+:spec: ``if(condition: Boolean, true: ReturnableArgumentA, false: ReturnableArgumentB) -> Union[ReturnableArgumentA, ReturnableArgumentB]``
-Conditional ``if`` statement that returns the ``true`` or ``false`` parameter
-depending on the ``condition`` value.
+:description:
+ Conditional ``if`` statement that returns the ``true`` or ``false`` parameter
+ depending on the ``condition`` value.
if_passthrough
~~~~~~~~~~~~~~
-``if_passthrough(maybe_true_arg: ReturnableArgumentA, else_arg: ReturnableArgumentB) -> Union[ReturnableArgumentA, ReturnableArgumentB]``
+:spec: ``if_passthrough(maybe_true_arg: ReturnableArgumentA, else_arg: ReturnableArgumentB) -> Union[ReturnableArgumentA, ReturnableArgumentB]``
-Conditional ``if`` statement that returns the ``maybe_true_arg`` if it evaluates to True,
-otherwise returns ``else_arg``.
+:description:
+ Conditional ``if`` statement that returns the ``maybe_true_arg`` if it evaluates to True,
+ otherwise returns ``else_arg``.
+
+----------------------------------------------------------------------------------------------------
Date Functions
--------------
datetime_strftime
~~~~~~~~~~~~~~~~~
-``datetime_strftime(posix_timestamp: Integer, date_format: String) -> String``
+:spec: ``datetime_strftime(posix_timestamp: Integer, date_format: String) -> String``
-Converts a posix timestamp to a date using strftime formatting.
+:description:
+ Converts a posix timestamp to a date using strftime formatting.
+
+----------------------------------------------------------------------------------------------------
Error Functions
---------------
assert
~~~~~~
-``assert(value: ReturnableArgument, assert_message: String) -> ReturnableArgument``
+:spec: ``assert(value: ReturnableArgument, assert_message: String) -> ReturnableArgument``
-Explicitly throw an error with the provided assert message if ``value`` evaluates to False.
-If it evaluates to True, it will return ``value``.
+:description:
+ Explicitly throw an error with the provided assert message if ``value`` evaluates to
+ False. If it evaluates to True, it will return ``value``.
assert_eq
~~~~~~~~~
-``assert_eq(value: ReturnableArgument, equals: AnyArgument, assert_message: String) -> ReturnableArgument``
+:spec: ``assert_eq(value: ReturnableArgument, equals: AnyArgument, assert_message: String) -> ReturnableArgument``
-Explicitly throw an error with the provided assert message if ``value`` does not equal
-``equals``. If they do equal, then return ``value``.
+:description:
+ Explicitly throw an error with the provided assert message if ``value`` does not equal
+ ``equals``. If they do equal, then return ``value``.
assert_ne
~~~~~~~~~
-``assert_ne(value: ReturnableArgument, equals: AnyArgument, assert_message: String) -> ReturnableArgument``
+:spec: ``assert_ne(value: ReturnableArgument, equals: AnyArgument, assert_message: String) -> ReturnableArgument``
-Explicitly throw an error with the provided assert message if ``value`` equals
-``equals``. If they do equal, then return ``value``.
+:description:
+ Explicitly throw an error with the provided assert message if ``value`` equals
+ ``equals``. If they do equal, then return ``value``.
assert_then
~~~~~~~~~~~
-``assert_then(value: AnyArgument, ret: ReturnableArgument, assert_message: String) -> ReturnableArgument``
+:spec: ``assert_then(value: AnyArgument, ret: ReturnableArgument, assert_message: String) -> ReturnableArgument``
-Explicitly throw an error with the provided assert message if ``value`` evaluates to False.
-If it evaluates to True, it will return ``ret``.
+:description:
+ Explicitly throw an error with the provided assert message if ``value`` evaluates to
+ False. If it evaluates to True, it will return ``ret``.
throw
~~~~~
-``throw(error_message: String) -> AnyArgument``
+:spec: ``throw(error_message: String) -> AnyArgument``
-Explicitly throw an error with the provided error message.
+:description:
+ Explicitly throw an error with the provided error message.
+
+----------------------------------------------------------------------------------------------------
Json Functions
--------------
from_json
~~~~~~~~~
-``from_json(argument: String) -> AnyArgument``
+:spec: ``from_json(argument: String) -> AnyArgument``
-Converts a JSON string into an actual type.
+:description:
+ Converts a JSON string into an actual type.
+
+----------------------------------------------------------------------------------------------------
Map Functions
-------------
map
~~~
-``map(maybe_mapping: AnyArgument) -> Map``
+:spec: ``map(maybe_mapping: AnyArgument) -> Map``
-Tries to cast an unknown variable type to a Map.
+:description:
+ Tries to cast an unknown variable type to a Map.
map_apply
~~~~~~~~~
-``map_apply(mapping: Map, lambda_function: LambdaTwo) -> Array``
+:spec: ``map_apply(mapping: Map, lambda_function: LambdaTwo) -> Array``
-Apply a lambda function on the Map, where each arg
-passed to the lambda function is ``key, value`` as two separate args.
+:description:
+ Apply a lambda function on the Map, where each arg
+ passed to the lambda function is ``key, value`` as two separate args.
map_contains
~~~~~~~~~~~~
-``map_contains(mapping: Map, key: AnyArgument) -> Boolean``
+:spec: ``map_contains(mapping: Map, key: AnyArgument) -> Boolean``
-Returns True if the key is in the Map. False otherwise.
+:description:
+ Returns True if the key is in the Map. False otherwise.
map_enumerate
~~~~~~~~~~~~~
-``map_enumerate(mapping: Map, lambda_function: LambdaThree) -> Array``
+:spec: ``map_enumerate(mapping: Map, lambda_function: LambdaThree) -> Array``
-Apply a lambda function on the Map, where each arg
-passed to the lambda function is ``idx, key, value`` as three separate args.
+:description:
+ Apply a lambda function on the Map, where each arg
+ passed to the lambda function is ``idx, key, value`` as three separate args.
map_get
~~~~~~~
-``map_get(mapping: Map, key: AnyArgument, default: Optional[AnyArgument]) -> AnyArgument``
+:spec: ``map_get(mapping: Map, key: AnyArgument, default: Optional[AnyArgument]) -> AnyArgument``
-Return ``key``'s value within the Map. If ``key`` does not exist, and ``default`` is
-provided, it will return ``default``. Otherwise, will error.
+:description:
+ Return ``key``'s value within the Map. If ``key`` does not exist, and ``default`` is
+ provided, it will return ``default``. Otherwise, will error.
map_get_non_empty
~~~~~~~~~~~~~~~~~
-``map_get_non_empty(mapping: Map, key: AnyArgument, default: AnyArgument) -> AnyArgument``
+:spec: ``map_get_non_empty(mapping: Map, key: AnyArgument, default: AnyArgument) -> AnyArgument``
-Return ``key``'s value within the Map. If ``key`` does not exist or is an empty string,
-return ``default``. Otherwise, will error.
+:description:
+ Return ``key``'s value within the Map. If ``key`` does not exist or is an empty string,
+ return ``default``. Otherwise, will error.
map_size
~~~~~~~~
-``map_size(mapping: Map) -> Integer``
+:spec: ``map_size(mapping: Map) -> Integer``
-Returns the size of a Map.
+:description:
+ Returns the size of a Map.
+
+----------------------------------------------------------------------------------------------------
Numeric Functions
-----------------
add
~~~
-``add(values: Numeric, ...) -> Numeric``
+:spec: ``add(values: Numeric, ...) -> Numeric``
-``+`` operator. Returns the sum of all values.
+:description:
+ ``+`` operator. Returns the sum of all values.
div
~~~
-``div(left: Numeric, right: Numeric) -> Numeric``
+:spec: ``div(left: Numeric, right: Numeric) -> Numeric``
-``/`` operator. Returns ``left / right``.
+:description:
+ ``/`` operator. Returns ``left / right``.
float
~~~~~
-``float(value: AnyArgument) -> Float``
+:spec: ``float(value: AnyArgument) -> Float``
-Cast to Float.
+:description:
+ Cast to Float.
int
~~~
-``int(value: AnyArgument) -> Integer``
+:spec: ``int(value: AnyArgument) -> Integer``
-Cast to Integer.
+:description:
+ Cast to Integer.
max
~~~
-``max(values: Numeric, ...) -> Numeric``
+:spec: ``max(values: Numeric, ...) -> Numeric``
-Returns max of all values.
+:description:
+ Returns max of all values.
min
~~~
-``min(values: Numeric, ...) -> Numeric``
+:spec: ``min(values: Numeric, ...) -> Numeric``
-Returns min of all values.
+:description:
+ Returns min of all values.
mod
~~~
-``mod(left: Numeric, right: Numeric) -> Numeric``
+:spec: ``mod(left: Numeric, right: Numeric) -> Numeric``
-``%`` operator. Returns ``left % right``.
+:description:
+ ``%`` operator. Returns ``left % right``.
mul
~~~
-``mul(values: Numeric, ...) -> Numeric``
+:spec: ``mul(values: Numeric, ...) -> Numeric``
-``*`` operator. Returns the product of all values.
+:description:
+ ``*`` operator. Returns the product of all values.
pow
~~~
-``pow(base: Numeric, exponent: Numeric) -> Numeric``
+:spec: ``pow(base: Numeric, exponent: Numeric) -> Numeric``
-``**`` operator. Returns the exponential of the base and exponent value.
+:description:
+ ``**`` operator. Returns the exponential of the base and exponent value.
sub
~~~
-``sub(values: Numeric, ...) -> Numeric``
+:spec: ``sub(values: Numeric, ...) -> Numeric``
-``-`` operator. Subtracts all values from left to right.
+:description:
+ ``-`` operator. Subtracts all values from left to right.
+
+----------------------------------------------------------------------------------------------------
Regex Functions
---------------
regex_capture_groups
~~~~~~~~~~~~~~~~~~~~
-``regex_capture_groups(regex: String) -> Integer``
+:spec: ``regex_capture_groups(regex: String) -> Integer``
-Returns number of capture groups in regex
+:description:
+ Returns number of capture groups in regex
regex_fullmatch
~~~~~~~~~~~~~~~
-``regex_fullmatch(regex: String, string: String) -> Array``
+:spec: ``regex_fullmatch(regex: String, string: String) -> Array``
-Checks for entire string to be a match. If a match exists, returns
-the string as the first element of the Array. If there are capture groups, returns each
-group as a subsequent element in the Array.
+:description:
+ Checks for entire string to be a match. If a match exists, returns
+ the string as the first element of the Array. If there are capture groups, returns each
+ group as a subsequent element in the Array.
regex_match
~~~~~~~~~~~
-``regex_match(regex: String, string: String) -> Array``
+:spec: ``regex_match(regex: String, string: String) -> Array``
-Checks for a match only at the beginning of the string. If a match exists, returns
-the string as the first element of the Array. If there are capture groups, returns each
-group as a subsequent element in the Array.
+:description:
+ Checks for a match only at the beginning of the string. If a match exists, returns
+ the string as the first element of the Array. If there are capture groups, returns each
+ group as a subsequent element in the Array.
regex_search
~~~~~~~~~~~~
-``regex_search(regex: String, string: String) -> Array``
+:spec: ``regex_search(regex: String, string: String) -> Array``
-Checks for a match anywhere in the string. If a match exists, returns
-the string as the first element of the Array. If there are capture groups, returns each
-group as a subsequent element in the Array.
+:description:
+ Checks for a match anywhere in the string. If a match exists, returns
+ the string as the first element of the Array. If there are capture groups, returns each
+ group as a subsequent element in the Array.
+
+----------------------------------------------------------------------------------------------------
String Functions
----------------
capitalize
~~~~~~~~~~
-``capitalize(string: String) -> String``
+:spec: ``capitalize(string: String) -> String``
-Capitalize the first character in the string.
+:description:
+ Capitalize the first character in the string.
concat
~~~~~~
-``concat(values: String, ...) -> String``
+:spec: ``concat(values: String, ...) -> String``
-Concatenate multiple Strings into a single String.
+:description:
+ Concatenate multiple Strings into a single String.
contains
~~~~~~~~
-``contains(string: String, contains: String) -> Boolean``
+:spec: ``contains(string: String, contains: String) -> Boolean``
-Returns True if ``contains`` is in ``string``. False otherwise.
+:description:
+ Returns True if ``contains`` is in ``string``. False otherwise.
lower
~~~~~
-``lower(string: String) -> String``
+:spec: ``lower(string: String) -> String``
-Lower-case the entire String.
+:description:
+ Lower-case the entire String.
pad
~~~
-``pad(string: String, length: Integer, char: String) -> String``
+:spec: ``pad(string: String, length: Integer, char: String) -> String``
-Pads the string to the given length
+:description:
+ Pads the string to the given length
pad_zero
~~~~~~~~
-``pad_zero(numeric: Numeric, length: Integer) -> String``
+:spec: ``pad_zero(numeric: Numeric, length: Integer) -> String``
-Pads a numeric with zeros to the given length
+:description:
+ Pads a numeric with zeros to the given length
replace
~~~~~~~
-``replace(string: String, old: String, new: String, count: Optional[Integer]) -> String``
+:spec: ``replace(string: String, old: String, new: String, count: Optional[Integer]) -> String``
-Replace the ``old`` part of the String with the ``new``. Optionally only replace it
-``count`` number of times.
+:description:
+ Replace the ``old`` part of the String with the ``new``. Optionally only replace it
+ ``count`` number of times.
slice
~~~~~
-``slice(string: String, start: Integer, end: Optional[Integer]) -> String``
+:spec: ``slice(string: String, start: Integer, end: Optional[Integer]) -> String``
-Returns the slice of the Array.
+:description:
+ Returns the slice of the Array.
string
~~~~~~
-``string(value: AnyArgument) -> String``
+:spec: ``string(value: AnyArgument) -> String``
-Cast to String.
+:description:
+ Cast to String.
titlecase
~~~~~~~~~
-``titlecase(string: String) -> String``
+:spec: ``titlecase(string: String) -> String``
-Capitalize each word in the string.
+:description:
+ Capitalize each word in the string.
upper
~~~~~
-``upper(string: String) -> String``
+:spec: ``upper(string: String) -> String``
-Upper-case the entire String.
+:description:
+ Upper-case the entire String.
+
+----------------------------------------------------------------------------------------------------
Ytdl-Sub Functions
------------------
legacy_bracket_safety
~~~~~~~~~~~~~~~~~~~~~
-``legacy_bracket_safety(value: ReturnableArgument) -> ReturnableArgument``
+:spec: ``legacy_bracket_safety(value: ReturnableArgument) -> ReturnableArgument``
ytdl-sub used to replace brackets ('{', '}') with unicode brackets ('{', '}') to not
interfere with its legacy variable scripting system. This function replicates that
@@ -481,14 +579,14 @@ behavior.
sanitize
~~~~~~~~
-``sanitize(value: AnyArgument) -> String``
+:spec: ``sanitize(value: AnyArgument) -> String``
Sanitize a string using yt-dlp's ``sanitize_filename`` method to ensure it's safe to use
for file/directory names on any OS.
sanitize_plex_episode
~~~~~~~~~~~~~~~~~~~~~
-``sanitize_plex_episode(string: String) -> String``
+:spec: ``sanitize_plex_episode(string: String) -> String``
Sanitize a string using ``sanitize`` and replace numerics with their respective fixed-width
numbers. This is used to have Plex avoid scraping numbers like ``4x4`` as the
@@ -496,7 +594,7 @@ season and/or episode.
to_date_metadata
~~~~~~~~~~~~~~~~
-``to_date_metadata(yyyymmdd: String) -> Map``
+:spec: ``to_date_metadata(yyyymmdd: String) -> Map``
Takes a date in the form of YYYYMMDD and returns a Map containing:
@@ -520,14 +618,14 @@ Takes a date in the form of YYYYMMDD and returns a Map containing:
to_native_filepath
~~~~~~~~~~~~~~~~~~
-``to_native_filepath(filepath: String) -> String``
+:spec: ``to_native_filepath(filepath: String) -> String``
Convert any unix-based path separators ('/') with the OS's native
separator.
truncate_filepath_if_too_long
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``truncate_filepath_if_too_long(filepath: String) -> String``
+:spec: ``truncate_filepath_if_too_long(filepath: String) -> String``
If a file-path is too long for the OS, this function will truncate it while preserving
the extension.
diff --git a/src/ytdl_sub/plugins/filter_exclude.py b/src/ytdl_sub/plugins/filter_exclude.py
index cceb4700..55394d16 100644
--- a/src/ytdl_sub/plugins/filter_exclude.py
+++ b/src/ytdl_sub/plugins/filter_exclude.py
@@ -26,8 +26,10 @@ class FilterExcludeOptions(ListFormatterValidator, OptionsValidator):
presets:
my_example_preset:
filter_exclude:
- - { %contains( %lower(title), '#short' ) }
- - { %contains( %lower(description), '#short' ) }
+ - >-
+ { %contains( %lower(title), '#short' ) }
+ - >-
+ { %contains( %lower(description), '#short' ) }
"""
diff --git a/src/ytdl_sub/plugins/filter_include.py b/src/ytdl_sub/plugins/filter_include.py
index 988426fe..ba90407b 100644
--- a/src/ytdl_sub/plugins/filter_include.py
+++ b/src/ytdl_sub/plugins/filter_include.py
@@ -26,7 +26,8 @@ class FilterIncludeOptions(ListFormatterValidator, OptionsValidator):
presets:
my_example_preset:
filter_include:
- - {description}
+ - >-
+ {description}
- >-
{
%regex_search_any(
diff --git a/src/ytdl_sub/script/functions/array_functions.py b/src/ytdl_sub/script/functions/array_functions.py
index 37c21752..4af6f63c 100644
--- a/src/ytdl_sub/script/functions/array_functions.py
+++ b/src/ytdl_sub/script/functions/array_functions.py
@@ -19,7 +19,8 @@ class ArrayFunctions:
@staticmethod
def array(maybe_array: AnyArgument) -> Array:
"""
- Tries to cast an unknown variable type to an Array.
+ :description:
+ Tries to cast an unknown variable type to an Array.
"""
if not isinstance(maybe_array, Array):
raise FunctionRuntimeException(
@@ -30,14 +31,16 @@ class ArrayFunctions:
@staticmethod
def array_size(array: Array) -> Integer:
"""
- Returns the size of an Array.
+ :description:
+ Returns the size of an Array.
"""
return Integer(len(array.value))
@staticmethod
def array_extend(*arrays: Array) -> Array:
"""
- Combine multiple Arrays into a single Array.
+ :description:
+ Combine multiple Arrays into a single Array.
"""
output: List[Resolvable] = []
for array in arrays:
@@ -50,7 +53,8 @@ class ArrayFunctions:
array: Array, overlap: Array, only_missing: Optional[Boolean] = None
) -> Array:
"""
- Overlaps ``overlap`` onto ``array``. Can optionally only overlay missing indices.
+ :description:
+ Overlaps ``overlap`` onto ``array``. Can optionally only overlay missing indices.
"""
output: List[Resolvable] = []
output.extend(array.value)
@@ -71,15 +75,17 @@ class ArrayFunctions:
@staticmethod
def array_at(array: Array, idx: Integer) -> AnyArgument:
"""
- Return the element in the Array at index ``idx``.
+ :description:
+ Return the element in the Array at index ``idx``.
"""
return array.value[idx.value]
@staticmethod
def array_first(array: Array, fallback: AnyArgument) -> AnyArgument:
"""
- Returns the first element whose boolean conversion is True. Returns fallback
- if all elements evaluate to False.
+ :description:
+ Returns the first element whose boolean conversion is True. Returns fallback
+ if all elements evaluate to False.
"""
for val in array.value:
if bool(val.value):
@@ -90,15 +96,17 @@ class ArrayFunctions:
@staticmethod
def array_contains(array: Array, value: AnyArgument) -> Boolean:
"""
- Return True if the value exists in the Array. False otherwise.
+ :description:
+ Return True if the value exists in the Array. False otherwise.
"""
return Boolean(value in array.value)
@staticmethod
def array_index(array: Array, value: AnyArgument) -> Integer:
"""
- Return the index of the value within the Array if it exists. If it does not, it will
- throw an error.
+ :description:
+ Return the index of the value within the Array if it exists. If it does not, it will
+ throw an error.
"""
if not ArrayFunctions.array_contains(array=array, value=value):
raise ArrayValueDoesNotExist(
@@ -113,7 +121,8 @@ class ArrayFunctions:
@staticmethod
def array_slice(array: Array, start: Integer, end: Optional[Integer] = None) -> Array:
"""
- Returns the slice of the Array.
+ :description:
+ Returns the slice of the Array.
"""
if end is not None:
return Array(array.value[start.value : end.value])
@@ -122,7 +131,8 @@ class ArrayFunctions:
@staticmethod
def array_flatten(array: Array) -> Array:
"""
- Flatten any nested Arrays into a single-dimensional Array.
+ :description:
+ Flatten any nested Arrays into a single-dimensional Array.
"""
output: List[Resolvable] = []
for elem in array.value:
@@ -136,14 +146,16 @@ class ArrayFunctions:
@staticmethod
def array_reverse(array: Array) -> Array:
"""
- Reverse an Array.
+ :description:
+ Reverse an Array.
"""
return Array(list(reversed(array.value)))
@staticmethod
def array_product(*arrays: Array) -> Array:
"""
- Returns the Cartesian product of elements from different arrays
+ :description:
+ Returns the Cartesian product of elements from different arrays
"""
out: List[Resolvable] = []
for combo in itertools.product(*[arr.value for arr in arrays]):
@@ -156,7 +168,17 @@ class ArrayFunctions:
@staticmethod
def array_apply(array: Array, lambda_function: Lambda) -> Array:
"""
- Apply a lambda function on every element in the Array.
+ :description:
+ Apply a lambda function on every element in the Array.
+ :usage:
+
+ .. code-block:: python
+
+ {
+ %array_apply( [1, 2, 3] , %string )
+ }
+
+ # ["1", "2", "3"]
"""
return Array([Array([val]) for val in array.value])
@@ -168,8 +190,9 @@ class ArrayFunctions:
reverse_args: Optional[Boolean] = None,
) -> Array:
"""
- Apply a lambda function on every element in the Array, with ``fixed_argument``
- passed as a second argument to every invocation.
+ :description:
+ Apply a lambda function on every element in the Array, with ``fixed_argument``
+ passed as a second argument to every invocation.
"""
if reverse_args and reverse_args.value:
return Array([Array([fixed_argument, val]) for val in array.value])
@@ -179,15 +202,17 @@ class ArrayFunctions:
@staticmethod
def array_enumerate(array: Array, lambda_function: LambdaTwo) -> Array:
"""
- Apply a lambda function on every element in the Array, where each arg
- passed to the lambda function is ``idx, element`` as two separate args.
+ :description:
+ Apply a lambda function on every element in the Array, where each arg
+ passed to the lambda function is ``idx, element`` as two separate args.
"""
return Array([Array([Integer(idx), val]) for idx, val in enumerate(array.value)])
@staticmethod
def array_reduce(array: Array, lambda_reduce_function: LambdaReduce) -> AnyArgument:
"""
- Apply a reduce function on pairs of elements in the Array, until one element remains.
- Executes using the left-most and reduces in the right direction.
+ :description:
+ Apply a reduce function on pairs of elements in the Array, until one element remains.
+ Executes using the left-most and reduces in the right direction.
"""
return array
diff --git a/src/ytdl_sub/script/functions/boolean_functions.py b/src/ytdl_sub/script/functions/boolean_functions.py
index f1bb9a35..bfb7416f 100644
--- a/src/ytdl_sub/script/functions/boolean_functions.py
+++ b/src/ytdl_sub/script/functions/boolean_functions.py
@@ -13,70 +13,80 @@ class BooleanFunctions:
@staticmethod
def bool(value: AnyArgument) -> Boolean:
"""
- Cast any type to a Boolean.
+ :description:
+ Cast any type to a Boolean.
"""
return Boolean(bool(value.value))
@staticmethod
def eq(left: AnyArgument, right: AnyArgument) -> Boolean:
"""
- ``==`` operator. Returns True if left == right. False otherwise.
+ :description:
+ ``==`` operator. Returns True if left == right. False otherwise.
"""
return Boolean(left.value == right.value)
@staticmethod
def ne(left: AnyArgument, right: AnyArgument) -> Boolean:
"""
- ``!=`` operator. Returns True if left != right. False otherwise.
+ :description:
+ ``!=`` operator. Returns True if left != right. False otherwise.
"""
return Boolean(left.value != right.value)
@staticmethod
def lt(left: AnyArgument, right: AnyArgument) -> Boolean:
"""
- ``<`` operator. Returns True if left < right. False otherwise.
+ :description:
+ ``<`` operator. Returns True if left < right. False otherwise.
"""
return Boolean(left.value < right.value)
@staticmethod
def lte(left: AnyArgument, right: AnyArgument) -> Boolean:
"""
- ``<=`` operator. Returns True if left <= right. False otherwise.
+ :description:
+ ``<=`` operator. Returns True if left <= right. False otherwise.
"""
return Boolean(left.value <= right.value)
@staticmethod
def gt(left: AnyArgument, right: AnyArgument) -> Boolean:
"""
- ``>`` operator. Returns True if left > right. False otherwise.
+ :description:
+ ``>`` operator. Returns True if left > right. False otherwise.
"""
return Boolean(left.value > right.value)
@staticmethod
def gte(left: AnyArgument, right: AnyArgument) -> Boolean:
"""
- ``>=`` operator. Returns True if left >= right. False otherwise.
+ :description:
+ ``>=`` operator. Returns True if left >= right. False otherwise.
"""
return Boolean(left.value >= right.value)
@staticmethod
def and_(*values: AnyArgument) -> Boolean:
"""
- ``and`` operator. Returns True if all values evaluate to True. False otherwise.
+ :description:
+ ``and`` operator. Returns True if all values evaluate to True. False otherwise.
"""
return Boolean(all(bool(val.value) for val in values))
@staticmethod
def or_(*values: AnyArgument) -> Boolean:
"""
- ``or`` operator. Returns True if any value evaluates to True. False otherwise.
+ :description:
+ ``or`` operator. Returns True if any value evaluates to True. False otherwise.
"""
return Boolean(any(bool(val.value) for val in values))
@staticmethod
def xor(*values: AnyArgument) -> Boolean:
"""
- ``^`` operator. Returns True if exactly one value is set to True. False otherwise.
+ :description:
+ ``^`` operator. Returns True if exactly one value is set to True. False otherwise.
"""
bit_array = [bool(val.value) for val in values]
@@ -85,13 +95,15 @@ class BooleanFunctions:
@staticmethod
def not_(value: Boolean) -> Boolean:
"""
- ``not`` operator. Returns the opposite of value.
+ :description:
+ ``not`` operator. Returns the opposite of value.
"""
return Boolean(not value.value)
@staticmethod
def is_null(value: AnyArgument) -> Boolean:
"""
- Returns True if a value is null (i.e. an empty string). False otherwise.
+ :description:
+ Returns True if a value is null (i.e. an empty string). False otherwise.
"""
return Boolean(isinstance(value, String) and value.value == "")
diff --git a/src/ytdl_sub/script/functions/conditional_functions.py b/src/ytdl_sub/script/functions/conditional_functions.py
index 8caaae02..e532031b 100644
--- a/src/ytdl_sub/script/functions/conditional_functions.py
+++ b/src/ytdl_sub/script/functions/conditional_functions.py
@@ -11,8 +11,9 @@ class ConditionalFunctions:
condition: Boolean, true: ReturnableArgumentA, false: ReturnableArgumentB
) -> Union[ReturnableArgumentA, ReturnableArgumentB]:
"""
- Conditional ``if`` statement that returns the ``true`` or ``false`` parameter
- depending on the ``condition`` value.
+ :description:
+ Conditional ``if`` statement that returns the ``true`` or ``false`` parameter
+ depending on the ``condition`` value.
"""
if condition.value:
return true
@@ -23,8 +24,9 @@ class ConditionalFunctions:
maybe_true_arg: ReturnableArgumentA, else_arg: ReturnableArgumentB
) -> Union[ReturnableArgumentA, ReturnableArgumentB]:
"""
- Conditional ``if`` statement that returns the ``maybe_true_arg`` if it evaluates to True,
- otherwise returns ``else_arg``.
+ :description:
+ Conditional ``if`` statement that returns the ``maybe_true_arg`` if it evaluates to True,
+ otherwise returns ``else_arg``.
"""
if bool(maybe_true_arg.value):
return maybe_true_arg
diff --git a/src/ytdl_sub/script/functions/date_functions.py b/src/ytdl_sub/script/functions/date_functions.py
index 8d68f052..fea1095c 100644
--- a/src/ytdl_sub/script/functions/date_functions.py
+++ b/src/ytdl_sub/script/functions/date_functions.py
@@ -8,6 +8,7 @@ class DateFunctions:
@staticmethod
def datetime_strftime(posix_timestamp: Integer, date_format: String) -> String:
"""
- Converts a posix timestamp to a date using strftime formatting.
+ :description:
+ Converts a posix timestamp to a date using strftime formatting.
"""
return String(datetime.utcfromtimestamp(posix_timestamp.value).strftime(date_format.value))
diff --git a/src/ytdl_sub/script/functions/error_functions.py b/src/ytdl_sub/script/functions/error_functions.py
index 517c6141..3a1be9f5 100644
--- a/src/ytdl_sub/script/functions/error_functions.py
+++ b/src/ytdl_sub/script/functions/error_functions.py
@@ -8,15 +8,17 @@ class ErrorFunctions:
@staticmethod
def throw(error_message: String) -> AnyArgument:
"""
- Explicitly throw an error with the provided error message.
+ :description:
+ Explicitly throw an error with the provided error message.
"""
raise UserThrownRuntimeError(error_message)
@staticmethod
def assert_(value: ReturnableArgument, assert_message: String) -> ReturnableArgument:
"""
- Explicitly throw an error with the provided assert message if ``value`` evaluates to False.
- If it evaluates to True, it will return ``value``.
+ :description:
+ Explicitly throw an error with the provided assert message if ``value`` evaluates to
+ False. If it evaluates to True, it will return ``value``.
"""
if not bool(value.value):
raise UserThrownRuntimeError(assert_message)
@@ -27,8 +29,9 @@ class ErrorFunctions:
value: AnyArgument, ret: ReturnableArgument, assert_message: String
) -> ReturnableArgument:
"""
- Explicitly throw an error with the provided assert message if ``value`` evaluates to False.
- If it evaluates to True, it will return ``ret``.
+ :description:
+ Explicitly throw an error with the provided assert message if ``value`` evaluates to
+ False. If it evaluates to True, it will return ``ret``.
"""
if not bool(value.value):
raise UserThrownRuntimeError(assert_message)
@@ -39,8 +42,9 @@ class ErrorFunctions:
value: ReturnableArgument, equals: AnyArgument, assert_message: String
) -> ReturnableArgument:
"""
- Explicitly throw an error with the provided assert message if ``value`` does not equal
- ``equals``. If they do equal, then return ``value``.
+ :description:
+ Explicitly throw an error with the provided assert message if ``value`` does not equal
+ ``equals``. If they do equal, then return ``value``.
"""
if not value.value == equals.value:
raise UserThrownRuntimeError(assert_message)
@@ -51,8 +55,9 @@ class ErrorFunctions:
value: ReturnableArgument, equals: AnyArgument, assert_message: String
) -> ReturnableArgument:
"""
- Explicitly throw an error with the provided assert message if ``value`` equals
- ``equals``. If they do equal, then return ``value``.
+ :description:
+ Explicitly throw an error with the provided assert message if ``value`` equals
+ ``equals``. If they do equal, then return ``value``.
"""
if value.value == equals.value:
raise UserThrownRuntimeError(assert_message)
diff --git a/src/ytdl_sub/script/functions/json_functions.py b/src/ytdl_sub/script/functions/json_functions.py
index 915fedf1..c706a86f 100644
--- a/src/ytdl_sub/script/functions/json_functions.py
+++ b/src/ytdl_sub/script/functions/json_functions.py
@@ -35,6 +35,7 @@ class JsonFunctions:
@staticmethod
def from_json(argument: String) -> AnyArgument:
"""
- Converts a JSON string into an actual type.
+ :description:
+ Converts a JSON string into an actual type.
"""
return _from_json(json.loads(argument.value))
diff --git a/src/ytdl_sub/script/functions/map_functions.py b/src/ytdl_sub/script/functions/map_functions.py
index ab81b575..b34fa611 100644
--- a/src/ytdl_sub/script/functions/map_functions.py
+++ b/src/ytdl_sub/script/functions/map_functions.py
@@ -18,7 +18,8 @@ class MapFunctions:
@staticmethod
def map(maybe_mapping: AnyArgument) -> Map:
"""
- Tries to cast an unknown variable type to a Map.
+ :description:
+ Tries to cast an unknown variable type to a Map.
"""
if not isinstance(maybe_mapping, Map):
raise FunctionRuntimeException(
@@ -29,14 +30,16 @@ class MapFunctions:
@staticmethod
def map_size(mapping: Map) -> Integer:
"""
- Returns the size of a Map.
+ :description:
+ Returns the size of a Map.
"""
return Integer(len(mapping.value))
@staticmethod
def map_contains(mapping: Map, key: AnyArgument) -> Boolean:
"""
- Returns True if the key is in the Map. False otherwise.
+ :description:
+ Returns True if the key is in the Map. False otherwise.
"""
if not isinstance(key, Hashable):
raise KeyNotHashableRuntimeException(
@@ -50,8 +53,9 @@ class MapFunctions:
mapping: Map, key: AnyArgument, default: Optional[AnyArgument] = None
) -> AnyArgument:
"""
- Return ``key``'s value within the Map. If ``key`` does not exist, and ``default`` is
- provided, it will return ``default``. Otherwise, will error.
+ :description:
+ Return ``key``'s value within the Map. If ``key`` does not exist, and ``default`` is
+ provided, it will return ``default``. Otherwise, will error.
"""
if not MapFunctions.map_contains(mapping=mapping, key=key).value:
if default is not None:
@@ -65,8 +69,9 @@ class MapFunctions:
@staticmethod
def map_get_non_empty(mapping: Map, key: AnyArgument, default: AnyArgument) -> AnyArgument:
"""
- Return ``key``'s value within the Map. If ``key`` does not exist or is an empty string,
- return ``default``. Otherwise, will error.
+ :description:
+ Return ``key``'s value within the Map. If ``key`` does not exist or is an empty string,
+ return ``default``. Otherwise, will error.
"""
output = MapFunctions.map_get(mapping, key, default)
if isinstance(output, String) and output.value == "":
@@ -78,16 +83,18 @@ class MapFunctions:
@staticmethod
def map_apply(mapping: Map, lambda_function: LambdaTwo) -> Array:
"""
- Apply a lambda function on the Map, where each arg
- passed to the lambda function is ``key, value`` as two separate args.
+ :description:
+ Apply a lambda function on the Map, where each arg
+ passed to the lambda function is ``key, value`` as two separate args.
"""
return Array([Array([key, value]) for key, value in mapping.value.items()])
@staticmethod
def map_enumerate(mapping: Map, lambda_function: LambdaThree) -> Array:
"""
- Apply a lambda function on the Map, where each arg
- passed to the lambda function is ``idx, key, value`` as three separate args.
+ :description:
+ Apply a lambda function on the Map, where each arg
+ passed to the lambda function is ``idx, key, value`` as three separate args.
"""
return Array(
[
diff --git a/src/ytdl_sub/script/functions/numeric_functions.py b/src/ytdl_sub/script/functions/numeric_functions.py
index 5211c690..b25374f9 100644
--- a/src/ytdl_sub/script/functions/numeric_functions.py
+++ b/src/ytdl_sub/script/functions/numeric_functions.py
@@ -16,28 +16,32 @@ class NumericFunctions:
@staticmethod
def float(value: AnyArgument) -> Float:
"""
- Cast to Float.
+ :description:
+ Cast to Float.
"""
return Float(value=float(value.value))
@staticmethod
def int(value: AnyArgument) -> Integer:
"""
- Cast to Integer.
+ :description:
+ Cast to Integer.
"""
return Integer(value=int(value.value))
@staticmethod
def add(*values: Numeric) -> Numeric:
"""
- ``+`` operator. Returns the sum of all values.
+ :description:
+ ``+`` operator. Returns the sum of all values.
"""
return _to_numeric(sum(val.value for val in values))
@staticmethod
def sub(*values: Numeric) -> Numeric:
"""
- ``-`` operator. Subtracts all values from left to right.
+ :description:
+ ``-`` operator. Subtracts all values from left to right.
"""
output = values[0].value
for val in values[1:]:
@@ -48,41 +52,47 @@ class NumericFunctions:
@staticmethod
def mul(*values: Numeric) -> Numeric:
"""
- ``*`` operator. Returns the product of all values.
+ :description:
+ ``*`` operator. Returns the product of all values.
"""
return _to_numeric(math.prod([val.value for val in values]))
@staticmethod
def pow(base: Numeric, exponent: Numeric) -> Numeric:
"""
- ``**`` operator. Returns the exponential of the base and exponent value.
+ :description:
+ ``**`` operator. Returns the exponential of the base and exponent value.
"""
return _to_numeric(math.pow(base.value, exponent.value))
@staticmethod
def div(left: Numeric, right: Numeric) -> Numeric:
"""
- ``/`` operator. Returns ``left / right``.
+ :description:
+ ``/`` operator. Returns ``left / right``.
"""
return _to_numeric(left.value / right.value)
@staticmethod
def mod(left: Numeric, right: Numeric) -> Numeric:
"""
- ``%`` operator. Returns ``left % right``.
+ :description:
+ ``%`` operator. Returns ``left % right``.
"""
return _to_numeric(value=left.value % right.value)
@staticmethod
def max(*values: Numeric) -> Numeric:
"""
- Returns max of all values.
+ :description:
+ Returns max of all values.
"""
return _to_numeric(max(val.value for val in values))
@staticmethod
def min(*values: Numeric) -> Numeric:
"""
- Returns min of all values.
+ :description:
+ Returns min of all values.
"""
return _to_numeric(min(val.value for val in values))
diff --git a/src/ytdl_sub/script/functions/regex_functions.py b/src/ytdl_sub/script/functions/regex_functions.py
index e38b3139..f837be32 100644
--- a/src/ytdl_sub/script/functions/regex_functions.py
+++ b/src/ytdl_sub/script/functions/regex_functions.py
@@ -18,33 +18,37 @@ class RegexFunctions:
@staticmethod
def regex_match(regex: String, string: String) -> Array:
"""
- Checks for a match only at the beginning of the string. If a match exists, returns
- the string as the first element of the Array. If there are capture groups, returns each
- group as a subsequent element in the Array.
+ :description:
+ Checks for a match only at the beginning of the string. If a match exists, returns
+ the string as the first element of the Array. If there are capture groups, returns each
+ group as a subsequent element in the Array.
"""
return _re_output_to_array(re.match(regex.value, string.value))
@staticmethod
def regex_search(regex: String, string: String) -> Array:
"""
- Checks for a match anywhere in the string. If a match exists, returns
- the string as the first element of the Array. If there are capture groups, returns each
- group as a subsequent element in the Array.
+ :description:
+ Checks for a match anywhere in the string. If a match exists, returns
+ the string as the first element of the Array. If there are capture groups, returns each
+ group as a subsequent element in the Array.
"""
return _re_output_to_array(re.search(regex.value, string.value))
@staticmethod
def regex_fullmatch(regex: String, string: String) -> Array:
"""
- Checks for entire string to be a match. If a match exists, returns
- the string as the first element of the Array. If there are capture groups, returns each
- group as a subsequent element in the Array.
+ :description:
+ Checks for entire string to be a match. If a match exists, returns
+ the string as the first element of the Array. If there are capture groups, returns each
+ group as a subsequent element in the Array.
"""
return _re_output_to_array(re.fullmatch(regex.value, string.value))
@staticmethod
def regex_capture_groups(regex: String) -> Integer:
"""
- Returns number of capture groups in regex
+ :description:
+ Returns number of capture groups in regex
"""
return Integer(re.compile(regex.value).groups)
diff --git a/src/ytdl_sub/script/functions/string_functions.py b/src/ytdl_sub/script/functions/string_functions.py
index 807a5dd4..1f0280b5 100644
--- a/src/ytdl_sub/script/functions/string_functions.py
+++ b/src/ytdl_sub/script/functions/string_functions.py
@@ -11,21 +11,24 @@ class StringFunctions:
@staticmethod
def string(value: AnyArgument) -> String:
"""
- Cast to String.
+ :description:
+ Cast to String.
"""
return String(value=str(value.value))
@staticmethod
def contains(string: String, contains: String) -> Boolean:
"""
- Returns True if ``contains`` is in ``string``. False otherwise.
+ :description:
+ Returns True if ``contains`` is in ``string``. False otherwise.
"""
return Boolean(contains.value in string.value)
@staticmethod
def slice(string: String, start: Integer, end: Optional[Integer] = None) -> String:
"""
- Returns the slice of the Array.
+ :description:
+ Returns the slice of the Array.
"""
if end is not None:
return String(string.value[start.value : end.value])
@@ -34,28 +37,32 @@ class StringFunctions:
@staticmethod
def lower(string: String) -> String:
"""
- Lower-case the entire String.
+ :description:
+ Lower-case the entire String.
"""
return String(string.value.lower())
@staticmethod
def upper(string: String) -> String:
"""
- Upper-case the entire String.
+ :description:
+ Upper-case the entire String.
"""
return String(string.value.upper())
@staticmethod
def capitalize(string: String) -> String:
"""
- Capitalize the first character in the string.
+ :description:
+ Capitalize the first character in the string.
"""
return String(string.value.capitalize())
@staticmethod
def titlecase(string: String) -> String:
"""
- Capitalize each word in the string.
+ :description:
+ Capitalize each word in the string.
"""
return String(string.value.title())
@@ -64,8 +71,9 @@ class StringFunctions:
string: String, old: String, new: String, count: Optional[Integer] = None
) -> String:
"""
- Replace the ``old`` part of the String with the ``new``. Optionally only replace it
- ``count`` number of times.
+ :description:
+ Replace the ``old`` part of the String with the ``new``. Optionally only replace it
+ ``count`` number of times.
"""
if count:
return String(string.value.replace(old.value, new.value, count.value))
@@ -75,14 +83,16 @@ class StringFunctions:
@staticmethod
def concat(*values: String) -> String:
"""
- Concatenate multiple Strings into a single String.
+ :description:
+ Concatenate multiple Strings into a single String.
"""
return String("".join(val.value for val in values))
@staticmethod
def pad(string: String, length: Integer, char: String) -> String:
"""
- Pads the string to the given length
+ :description:
+ Pads the string to the given length
"""
output = string.value
while len(output) < length.value:
@@ -93,7 +103,8 @@ class StringFunctions:
@staticmethod
def pad_zero(numeric: Numeric, length: Integer) -> String:
"""
- Pads a numeric with zeros to the given length
+ :description:
+ Pads a numeric with zeros to the given length
"""
return StringFunctions.pad(
string=String(str(numeric.value)),
diff --git a/tests/unit/docgen/test_docgen_regenerate_disabled.py b/tests/unit/docgen/test_docgen_regenerate_disabled.py
new file mode 100644
index 00000000..696b3418
--- /dev/null
+++ b/tests/unit/docgen/test_docgen_regenerate_disabled.py
@@ -0,0 +1,5 @@
+from tools.docgen.docgen import REGENERATE_DOCS
+
+
+def test_docgen_regenerate_disabled():
+ assert REGENERATE_DOCS is False
\ No newline at end of file
diff --git a/tools/docgen/entry_variables.py b/tools/docgen/entry_variables.py
index 9f3728d7..a0c9d2f2 100644
--- a/tools/docgen/entry_variables.py
+++ b/tools/docgen/entry_variables.py
@@ -4,7 +4,7 @@ from typing import Dict
from typing import Type
from tools.docgen.docgen import DocGen
-from tools.docgen.utils import camel_case_to_human
+from tools.docgen.utils import camel_case_to_human, line_section
from tools.docgen.utils import get_function_docs
from tools.docgen.utils import properties
from tools.docgen.utils import section
@@ -32,7 +32,8 @@ class EntryVariablesDocGen(DocGen):
_variable_class_to_name(obj): obj for obj in VariableDefinitions.__bases__
}
- for name in sorted(parent_objs.keys()):
+ for idx, name in enumerate(sorted(parent_objs.keys())):
+ docs += line_section(section_idx=idx)
docs += section(name, level=1)
for variable_function_name in properties(parent_objs[name]):
diff --git a/tools/docgen/plugins.py b/tools/docgen/plugins.py
index b71218b3..476e015c 100644
--- a/tools/docgen/plugins.py
+++ b/tools/docgen/plugins.py
@@ -4,7 +4,7 @@ from typing import Dict
from typing import Type
from tools.docgen.docgen import DocGen
-from tools.docgen.utils import get_function_docs
+from tools.docgen.utils import get_function_docs, line_section
from tools.docgen.utils import properties
from tools.docgen.utils import section
from ytdl_sub.config.overrides import Overrides
@@ -57,7 +57,8 @@ class PluginsDocGen(DocGen):
options_dict[plugin_name] = plugin_type.plugin_options_type
docs = section("Plugins", level=0)
- for name in sorted(options_dict.keys()):
+ for idx, name in enumerate(sorted(options_dict.keys())):
+ docs += line_section(section_idx=idx)
docs += generate_plugin_docs(name, options_dict[name], offset=1)
return docs
diff --git a/tools/docgen/scripting_functions.py b/tools/docgen/scripting_functions.py
index 751085f4..1ece6b9b 100644
--- a/tools/docgen/scripting_functions.py
+++ b/tools/docgen/scripting_functions.py
@@ -6,7 +6,7 @@ from typing import Optional
from typing import Type
from tools.docgen.docgen import DocGen
-from tools.docgen.utils import camel_case_to_human
+from tools.docgen.utils import camel_case_to_human, line_section
from tools.docgen.utils import section
from tools.docgen.utils import static_methods
from ytdl_sub.entries.script.custom_functions import CustomFunctions
@@ -30,7 +30,7 @@ def function_class_to_name(obj: Type[Any]) -> str:
def function_type_hinting(display_function_name: str, function: Any) -> str:
spec = FunctionSpec.from_callable(function)
- out = "``"
+ out = ":spec: ``"
out += display_function_name
out += spec.human_readable_input_args()
out += " -> "
@@ -65,7 +65,8 @@ class ScriptingFunctionsDocGen(DocGen):
}
parent_objs["Ytdl-Sub Functions"] = CustomFunctions
- for name in sorted(parent_objs.keys()):
+ for idx, name in enumerate(sorted(parent_objs.keys())):
+ docs += line_section(section_idx=idx)
docs += section(name, level=1)
for function_name in static_methods(parent_objs[name]):
diff --git a/tools/docgen/utils.py b/tools/docgen/utils.py
index d236bb5f..94cab101 100644
--- a/tools/docgen/utils.py
+++ b/tools/docgen/utils.py
@@ -8,7 +8,9 @@ from typing import Type
LEVEL_CHARS: Dict[int, str] = {0: "=", 1: "-", 2: "~", 3: "^"}
-def section(name: str, level: int) -> str:
+def section(name: str, level: int, as_code: bool = False) -> str:
+ if as_code:
+ name = f"``{name}``"
return f"\n{name}\n{len(name) * LEVEL_CHARS[level]}\n"
@@ -42,3 +44,13 @@ def get_function_docs(
docs += inspect.cleandoc(getattr(obj, function_name).__doc__)
docs += "\n"
return docs
+
+
+def line() -> str:
+ return "\n" + ("-" * 100) + "\n"
+
+
+def line_section(section_idx: int) -> str:
+ if section_idx > 0:
+ return line()
+ return ""