[DOCS] Advanced scripting usage, rename Overrides to Static (#866)

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 <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_types.html#map>`_
+variable
+`entry_metadata <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/entry_variables.html#entry-metadata>`_.
+
+Any field can be accessed by using the
+`map_get <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#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
+.. code-block:: yaml
-~~~~~~~~~~~~~~~~~~~~~~~
+
-WIP
+   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") }

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

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(

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]:

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"
 

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
         )
 

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):
+    def test_static_variables_generated(self):
-        _test_doc_gen(OverrideVariablesDocGen)
+        _test_doc_gen(StaticVariablesDocGen)
 
     def test_scripting_functions_generated(self):
         _test_doc_gen(ScriptingFunctionsDocGen)

tools/docgen/override_variables.py

@@ -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

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