From b3d298b6644faa2b4023acfb74e5b8547f5098f4 Mon Sep 17 00:00:00 2001 From: Jesse Bannon Date: Mon, 1 Jan 2024 00:01:46 -0800 Subject: [PATCH] [DOCS] Advanced scripting usage, rename Overrides to Static (#866) --- .../config_reference/scripting/index.rst | 41 ++++++++++++++++--- ...ide_variables.rst => static_variables.rst} | 20 +++++---- src/ytdl_sub/config/overrides.py | 4 +- .../config/validators/variable_validation.py | 6 ++- .../entries/variables/override_variables.py | 5 ++- .../subscriptions/subscription_validators.py | 14 ++++--- tests/unit/docgen/test_docgen.py | 6 +-- tools/docgen/override_variables.py | 25 ----------- tools/docgen/static_variables.py | 26 ++++++++++++ 9 files changed, 93 insertions(+), 54 deletions(-) rename docs/source/config_reference/scripting/{override_variables.rst => static_variables.rst} (79%) delete mode 100644 tools/docgen/override_variables.py create mode 100644 tools/docgen/static_variables.py diff --git a/docs/source/config_reference/scripting/index.rst b/docs/source/config_reference/scripting/index.rst index 9b05ad68..4366914b 100644 --- a/docs/source/config_reference/scripting/index.rst +++ b/docs/source/config_reference/scripting/index.rst @@ -9,7 +9,7 @@ contain reference documentation for each built-in variable and scripting functio :maxdepth: 1 entry_variables - override_variables + static_variables scripting_functions scripting_types @@ -162,12 +162,41 @@ Advanced Scripting Accessing ``info.json`` Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -WIP +The entirety of an entry's ``info.json`` file resides in the +`Map `_ +variable +`entry_metadata `_. + +Any field can be accessed by using the +`map_get `_ +function like so: + +.. code-block:: yaml + :caption: Fetches the 'artist' value from the .info.json, returns null if it does not exist. + + artist: >- + { %map_get( entry_metadata, "artist", null ) } Creating Custom Functions ~~~~~~~~~~~~~~~~~~~~~~~~~ -WIP +Custom functions can be created in the overrides section using the following syntax: -Parsing Maps and Arrays -~~~~~~~~~~~~~~~~~~~~~~~ -WIP +.. code-block:: yaml + + overrides: + "%get_entry_metadata_field": >- + { %map_get( entry_metadata, $0, null ) } + +Custom function definitions must have ``%`` as a prefix to the function name, be surrounded by +quotes to make YAML parsing happy, and can support arguments using ``$0``, ``$1``, ... to indicate +their first argument, second argument, etc. + +Using our new custom function, we can simply the ``artist`` variable definition above to: + +.. code-block:: yaml + + overrides: + "%get_entry_metadata_field": >- + { %map_get( entry_metadata, $0, null ) } + artist: >- + { get_entry_metadata_field("artist") } diff --git a/docs/source/config_reference/scripting/override_variables.rst b/docs/source/config_reference/scripting/static_variables.rst similarity index 79% rename from docs/source/config_reference/scripting/override_variables.rst rename to docs/source/config_reference/scripting/static_variables.rst index c7a9991b..e6e41527 100644 --- a/docs/source/config_reference/scripting/override_variables.rst +++ b/docs/source/config_reference/scripting/static_variables.rst @@ -1,9 +1,12 @@ -Override Variables -================== +Static Variables +================ + +Subscription Variables +---------------------- subscription_indent_i ---------------------- +~~~~~~~~~~~~~~~~~~~~~ For subscriptions in the form of .. code-block:: yaml @@ -16,7 +19,7 @@ For subscriptions in the form of ``Indent Value 1`` and ``Indent Value 2``. subscription_map ----------------- +~~~~~~~~~~~~~~~~ For subscriptions in the form of .. code-block:: yaml @@ -42,11 +45,12 @@ Stores all the contents under the subscription name into the override variable } subscription_name ------------------ -Name of the subscription +~~~~~~~~~~~~~~~~~ +Name of the subscription. For subscriptions types that use a prefix (``~``, ``+``), +the prefix and all whitespace afterwards is stripped from the subscription name. subscription_value ------------------- +~~~~~~~~~~~~~~~~~~ For subscriptions in the form of .. code-block:: yaml @@ -56,7 +60,7 @@ For subscriptions in the form of ``subscription_value`` gets set to ``https://...``. subscription_value_i --------------------- +~~~~~~~~~~~~~~~~~~~~ For subscriptions in the form of .. code-block:: yaml diff --git a/src/ytdl_sub/config/overrides.py b/src/ytdl_sub/config/overrides.py index 59b787b7..f68ce727 100644 --- a/src/ytdl_sub/config/overrides.py +++ b/src/ytdl_sub/config/overrides.py @@ -8,7 +8,7 @@ import mergedeep from ytdl_sub.entries.entry import Entry from ytdl_sub.entries.script.variable_definitions import VARIABLES from ytdl_sub.entries.variables.override_variables import OverrideHelpers -from ytdl_sub.entries.variables.override_variables import OverrideVariables +from ytdl_sub.entries.variables.override_variables import SubscriptionVariables from ytdl_sub.script.parser import parse from ytdl_sub.script.script import Script from ytdl_sub.script.utils.exceptions import ScriptVariableNotResolved @@ -135,7 +135,7 @@ class Overrides(DictFormatterValidator, Scriptable): """ self.script.add( ScriptUtils.add_sanitized_variables( - {OverrideVariables.subscription_name(): subscription_name} + {SubscriptionVariables.subscription_name(): subscription_name} ) ) self.script.add( diff --git a/src/ytdl_sub/config/validators/variable_validation.py b/src/ytdl_sub/config/validators/variable_validation.py index 1b2ea1e4..cc554a70 100644 --- a/src/ytdl_sub/config/validators/variable_validation.py +++ b/src/ytdl_sub/config/validators/variable_validation.py @@ -14,7 +14,7 @@ from ytdl_sub.config.preset_options import OutputOptions from ytdl_sub.config.validators.options import OptionsValidator from ytdl_sub.downloaders.url.validators import MultiUrlValidator from ytdl_sub.entries.script.variable_definitions import VARIABLE_SCRIPTS -from ytdl_sub.entries.variables.override_variables import OverrideVariables +from ytdl_sub.entries.variables.override_variables import SubscriptionVariables from ytdl_sub.script.script import Script from ytdl_sub.validators.string_formatter_validators import validate_formatters @@ -67,7 +67,9 @@ def _get_added_and_modified_variables( def _override_variables(overrides: Overrides) -> Set[str]: - return set(list(overrides.initial_variables().keys())) | {OverrideVariables.subscription_name()} + return set(list(overrides.initial_variables().keys())) | { + SubscriptionVariables.subscription_name() + } def _entry_variables() -> Set[str]: diff --git a/src/ytdl_sub/entries/variables/override_variables.py b/src/ytdl_sub/entries/variables/override_variables.py index 38f7160c..007aaf2b 100644 --- a/src/ytdl_sub/entries/variables/override_variables.py +++ b/src/ytdl_sub/entries/variables/override_variables.py @@ -7,11 +7,12 @@ from ytdl_sub.script.utils.name_validation import is_valid_name SUBSCRIPTION_ARRAY = "subscription_array" -class OverrideVariables: +class SubscriptionVariables: @staticmethod def subscription_name() -> str: """ - Name of the subscription + Name of the subscription. For subscriptions types that use a prefix (``~``, ``+``), + the prefix and all whitespace afterwards is stripped from the subscription name. """ return "subscription_name" diff --git a/src/ytdl_sub/subscriptions/subscription_validators.py b/src/ytdl_sub/subscriptions/subscription_validators.py index 62445552..c247779a 100644 --- a/src/ytdl_sub/subscriptions/subscription_validators.py +++ b/src/ytdl_sub/subscriptions/subscription_validators.py @@ -9,7 +9,7 @@ from typing import final from ytdl_sub.config.config_file import ConfigFile from ytdl_sub.config.overrides import Overrides -from ytdl_sub.entries.variables.override_variables import OverrideVariables +from ytdl_sub.entries.variables.override_variables import SubscriptionVariables from ytdl_sub.utils.script import ScriptUtils from ytdl_sub.validators.string_formatter_validators import DictFormatterValidator from ytdl_sub.validators.validators import DictValidator @@ -32,7 +32,7 @@ class SubscriptionOutput(Validator, ABC): indent overrides to merge with the preset dict's overrides """ return { - OverrideVariables.subscription_indent_i(i): self._indent_overrides[i] + SubscriptionVariables.subscription_indent_i(i): self._indent_overrides[i] for i in range(len(self._indent_overrides)) } @@ -143,7 +143,7 @@ class SubscriptionValueValidator(SubscriptionLeafValidator, StringValidator): presets=presets, indent_overrides=indent_overrides, ) - self._overrides_to_add[OverrideVariables.subscription_value()] = self.value + self._overrides_to_add[SubscriptionVariables.subscription_value()] = self.value class SubscriptionListValuesValidator(SubscriptionLeafValidator, StringListValidator): @@ -168,10 +168,12 @@ class SubscriptionListValuesValidator(SubscriptionLeafValidator, StringListValid for idx, list_value in enumerate(self.list): # Write the first list value into subscription_value as well if idx == 0: - self._overrides_to_add[OverrideVariables.subscription_value()] = list_value.value + self._overrides_to_add[ + SubscriptionVariables.subscription_value() + ] = list_value.value self._overrides_to_add[ - OverrideVariables.subscription_value_i(index=idx) + SubscriptionVariables.subscription_value_i(index=idx) ] = list_value.value @@ -215,7 +217,7 @@ class SubscriptionMapValidator(SubscriptionLeafValidator, LiteralDictValidator): presets=presets, indent_overrides=indent_overrides, ) - self._overrides_to_add[OverrideVariables.subscription_map()] = ScriptUtils.to_script( + self._overrides_to_add[SubscriptionVariables.subscription_map()] = ScriptUtils.to_script( self.dict ) diff --git a/tests/unit/docgen/test_docgen.py b/tests/unit/docgen/test_docgen.py index 82768347..5d326839 100644 --- a/tests/unit/docgen/test_docgen.py +++ b/tests/unit/docgen/test_docgen.py @@ -2,9 +2,9 @@ from typing import Type from tools.docgen.docgen import DocGen from tools.docgen.entry_variables import EntryVariablesDocGen -from tools.docgen.override_variables import OverrideVariablesDocGen from tools.docgen.plugins import PluginsDocGen from tools.docgen.scripting_functions import ScriptingFunctionsDocGen +from tools.docgen.static_variables import StaticVariablesDocGen from ytdl_sub.utils.file_handler import get_md5_hash @@ -20,8 +20,8 @@ class TestDocGen: def test_entry_variables_generated(self): _test_doc_gen(EntryVariablesDocGen) - def test_override_variables_generated(self): - _test_doc_gen(OverrideVariablesDocGen) + def test_static_variables_generated(self): + _test_doc_gen(StaticVariablesDocGen) def test_scripting_functions_generated(self): _test_doc_gen(ScriptingFunctionsDocGen) diff --git a/tools/docgen/override_variables.py b/tools/docgen/override_variables.py deleted file mode 100644 index e919877c..00000000 --- a/tools/docgen/override_variables.py +++ /dev/null @@ -1,25 +0,0 @@ -from pathlib import Path - -from tools.docgen.docgen import DocGen -from tools.docgen.utils import get_function_docs -from tools.docgen.utils import section -from tools.docgen.utils import static_methods -from ytdl_sub.entries.variables.override_variables import OverrideVariables - - -class OverrideVariablesDocGen(DocGen): - - LOCATION = Path("docs/source/config_reference/scripting/override_variables.rst") - - @classmethod - def generate(cls) -> str: - docs = section("Override Variables", level=0) - - for name in static_methods(OverrideVariables): - docs += get_function_docs( - function_name=name, - obj=OverrideVariables, - level=1, - ) - - return docs diff --git a/tools/docgen/static_variables.py b/tools/docgen/static_variables.py new file mode 100644 index 00000000..254179cc --- /dev/null +++ b/tools/docgen/static_variables.py @@ -0,0 +1,26 @@ +from pathlib import Path + +from tools.docgen.docgen import DocGen +from tools.docgen.utils import get_function_docs +from tools.docgen.utils import section +from tools.docgen.utils import static_methods +from ytdl_sub.entries.variables.override_variables import SubscriptionVariables + + +class StaticVariablesDocGen(DocGen): + + LOCATION = Path("docs/source/config_reference/scripting/static_variables.rst") + + @classmethod + def generate(cls) -> str: + docs = section("Static Variables", level=0) + + docs += section("Subscription Variables", level=1) + for name in static_methods(SubscriptionVariables): + docs += get_function_docs( + function_name=name, + obj=SubscriptionVariables, + level=2, + ) + + return docs