ytdl-sub 2025.12.30__tar.gz → 2025.12.31__tar.gz

{ytdl_sub-2025.12.30 → ytdl_sub-2025.12.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ytdl-sub
-Version: 2025.12.30
+Version: 2025.12.31
 Summary: Automate downloading metadata generation with YoutubeDL
 Author: Jesse Bannon
 License:                     GNU GENERAL PUBLIC LICENSE

ytdl_sub-2025.12.31/src/ytdl_sub/__init__.py

@@ -0,0 +1 @@
+__pypi_version__ = "2025.12.31";__local_version__ = "2025.12.31+1abe2a4"

{ytdl_sub-2025.12.30 → ytdl_sub-2025.12.31}/src/ytdl_sub/config/overrides.py

@@ -4,15 +4,16 @@ from typing import Iterable
 from typing import Optional
 from typing import Set
 
-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 REQUIRED_OVERRIDE_VARIABLE_NAMES
 from ytdl_sub.entries.variables.override_variables import OverrideHelpers
 from ytdl_sub.script.parser import parse
 from ytdl_sub.script.script import Script
+from ytdl_sub.script.types.function import BuiltInFunction
 from ytdl_sub.script.types.resolvable import Resolvable
+from ytdl_sub.script.types.resolvable import String
+from ytdl_sub.script.types.syntax_tree import SyntaxTree
 from ytdl_sub.script.utils.exceptions import ScriptVariableNotResolved
 from ytdl_sub.utils.exceptions import InvalidVariableNameException
 from ytdl_sub.utils.exceptions import StringFormattingException
@@ -134,29 +135,35 @@ class Overrides(UnstructuredDictFormatterValidator, Scriptable):
             )
 
     def initial_variables(
-        self, unresolved_variables: Optional[Dict[str, str]] = None
-    ) -> Dict[str, str]:
+        self, unresolved_variables: Optional[Dict[str, SyntaxTree]] = None
+    ) -> Dict[str, SyntaxTree]:
         """
         Returns
         -------
         Variables and format strings for all Override variables + additional variables (Optional)
         """
-        initial_variables: Dict[str, str] = {}
-        mergedeep.merge(
-            initial_variables,
-            self.dict_with_format_strings,
-            unresolved_variables if unresolved_variables else {},
-        )
-        return ScriptUtils.add_sanitized_variables(initial_variables)
+        initial_variables: Dict[str, SyntaxTree] = self.dict_with_parsed_format_strings
+        if unresolved_variables:
+            initial_variables |= unresolved_variables
+        return ScriptUtils.add_sanitized_parsed_variables(initial_variables)
 
     def initialize_script(self, unresolved_variables: Set[str]) -> "Overrides":
         """
         Initialize the override script with any unresolved variables
         """
-        self.script.add(
+        self.script.add_parsed(
             self.initial_variables(
                 unresolved_variables={
-                    var_name: f"{{%throw('Plugin variable {var_name} has not been created yet')}}"
+                    var_name: SyntaxTree(
+                        ast=[
+                            BuiltInFunction(
+                                name="throw",
+                                args=[
+                                    String(f"Plugin variable {var_name} has not been created yet")
+                                ],
+                            )
+                        ]
+                    )
                     for var_name in unresolved_variables
                 }
             )

{ytdl_sub-2025.12.30 → ytdl_sub-2025.12.31}/src/ytdl_sub/config/plugin/preset_plugins.py

@@ -1,5 +1,7 @@
+from typing import Iterable
 from typing import List
 from typing import Optional
+from typing import Set
 from typing import Tuple
 from typing import Type
 
@@ -44,3 +46,34 @@ class PresetPlugins:
         if plugin_type in plugin_option_types:
             return self.plugin_options[plugin_option_types.index(plugin_type)]
         return None
+
+    def get_added_and_modified_variables(
+        self, additional_options: List[OptionsValidator]
+    ) -> Iterable[Tuple[OptionsValidator, Set[str], Set[str]]]:
+        """
+        Iterates and returns the plugin options, added variables, modified variables
+        """
+        for plugin_options in self.plugin_options + additional_options:
+            added_variables: Set[str] = set()
+            modified_variables: Set[str] = set()
+
+            for plugin_added_variables in plugin_options.added_variables(
+                unresolved_variables=set(),
+            ).values():
+                added_variables |= set(plugin_added_variables)
+
+            for plugin_modified_variables in plugin_options.modified_variables().values():
+                modified_variables = plugin_modified_variables
+
+            yield plugin_options, added_variables, modified_variables
+
+    def get_all_variables(self, additional_options: List[OptionsValidator]) -> Set[str]:
+        """
+        Returns set of all added and modified variables' names.
+        """
+        all_variables: Set[str] = set()
+        for _, added, modified in self.get_added_and_modified_variables(additional_options):
+            all_variables.update(added)
+            all_variables.update(modified)
+
+        return all_variables

{ytdl_sub-2025.12.30 → ytdl_sub-2025.12.31}/src/ytdl_sub/config/preset.py

@@ -2,6 +2,7 @@ import copy
 from typing import Any
 from typing import Dict
 from typing import List
+from typing import Set
 
 from mergedeep import mergedeep
 
@@ -11,7 +12,6 @@ from ytdl_sub.config.plugin.plugin_mapping import PluginMapping
 from ytdl_sub.config.plugin.preset_plugins import PresetPlugins
 from ytdl_sub.config.preset_options import OutputOptions
 from ytdl_sub.config.preset_options import YTDLOptions
-from ytdl_sub.config.validators.variable_validation import VariableValidation
 from ytdl_sub.downloaders.url.validators import MultiUrlValidator
 from ytdl_sub.prebuilt_presets import PREBUILT_PRESET_NAMES
 from ytdl_sub.prebuilt_presets import PUBLISHED_PRESET_NAMES
@@ -172,6 +172,37 @@ class Preset(_PresetShell):
             mergedeep.merge({}, *reversed(presets_to_merge), strategy=mergedeep.Strategy.ADDITIVE)
         )
 
+    def _initialize_overrides_script(self, overrides: Overrides) -> Overrides:
+        """
+        Do some gymnastics to initialize the Overrides script.
+        """
+        unresolved_variables: Set[str] = set()
+
+        for (
+            plugin_options,
+            added_variables,
+            modified_variables,
+        ) in self.plugins.get_added_and_modified_variables(
+            additional_options=[self.downloader_options, self.output_options]
+        ):
+            for added_variable in added_variables:
+                if not overrides.ensure_added_plugin_variable_valid(added_variable=added_variable):
+                    # pylint: disable=protected-access
+                    raise plugin_options._validation_exception(
+                        f"Cannot use the variable name {added_variable} because it exists as a"
+                        " built-in ytdl-sub variable name."
+                    )
+                    # pylint: enable=protected-access
+
+            # Set unresolved as variables that are added but do not exist as
+            # entry/override variables since they are created at run-time
+            unresolved_variables |= added_variables | modified_variables
+
+        # Initialize overrides with unresolved variables + modified variables to throw an error.
+        # For modified variables, this is to prevent a resolve(update=True) to setting any
+        # dependencies until it has been explicitly added
+        return overrides.initialize_script(unresolved_variables=unresolved_variables)
+
     def __init__(self, config: ConfigValidator, name: str, value: Any):
         super().__init__(name=name, value=value)
 
@@ -192,16 +223,11 @@ class Preset(_PresetShell):
         )
 
         self.plugins: PresetPlugins = self._validate_and_get_plugins()
-        self.overrides = self._validate_key(key="overrides", validator=Overrides, default={})
-
+        self.overrides = self._initialize_overrides_script(
+            overrides=self._validate_key(key="overrides", validator=Overrides, default={})
+        )
         self.overrides.ensure_variable_names_not_a_plugin(plugin_names=PRESET_KEYS)
 
-        VariableValidation(
-            downloader_options=self.downloader_options,
-            output_options=self.output_options,
-            plugins=self.plugins,
-        ).initialize_preset_overrides(overrides=self.overrides).ensure_proper_usage()
-
     @property
     def name(self) -> str:
         """

ytdl_sub-2025.12.31/src/ytdl_sub/config/validators/variable_validation.py

@@ -0,0 +1,91 @@
+from typing import Dict
+
+from ytdl_sub.config.overrides import Overrides
+from ytdl_sub.config.plugin.plugin_mapping import PluginMapping
+from ytdl_sub.config.plugin.plugin_operation import PluginOperation
+from ytdl_sub.config.plugin.preset_plugins import PresetPlugins
+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.validators.string_formatter_validators import validate_formatters
+
+
+class VariableValidation:
+    def __init__(
+        self,
+        overrides: Overrides,
+        downloader_options: MultiUrlValidator,
+        output_options: OutputOptions,
+        plugins: PresetPlugins,
+    ):
+        self.overrides = overrides
+        self.downloader_options = downloader_options
+        self.output_options = output_options
+        self.plugins = plugins
+
+        self.script = self.overrides.script
+        self.unresolved_variables = self.plugins.get_all_variables(
+            additional_options=[self.output_options, self.downloader_options]
+        )
+
+    def _add_variables(self, plugin_op: PluginOperation, options: OptionsValidator) -> None:
+        """
+        Add dummy variables for script validation
+        """
+        added_variables = options.added_variables(
+            unresolved_variables=self.unresolved_variables,
+        ).get(plugin_op, set())
+        modified_variables = options.modified_variables().get(plugin_op, set())
+
+        self.unresolved_variables -= added_variables | modified_variables
+
+    def ensure_proper_usage(self) -> Dict:
+        """
+        Validate variables resolve as plugins are executed, and return
+        a mock script which contains actualized added variables from the plugins
+        """
+
+        resolved_subscription: Dict = {}
+
+        self._add_variables(PluginOperation.DOWNLOADER, options=self.downloader_options)
+
+        # Always add output options first
+        self._add_variables(PluginOperation.MODIFY_ENTRY_METADATA, options=self.output_options)
+
+        # Metadata variables to be added
+        for plugin_options in PluginMapping.order_options_by(
+            self.plugins.zipped(), PluginOperation.MODIFY_ENTRY_METADATA
+        ):
+            self._add_variables(PluginOperation.MODIFY_ENTRY_METADATA, options=plugin_options)
+
+        for plugin_options in PluginMapping.order_options_by(
+            self.plugins.zipped(), PluginOperation.MODIFY_ENTRY
+        ):
+            self._add_variables(PluginOperation.MODIFY_ENTRY, options=plugin_options)
+
+            # Validate that any formatter in the plugin options can resolve
+            resolved_subscription |= validate_formatters(
+                script=self.script,
+                unresolved_variables=self.unresolved_variables,
+                validator=plugin_options,
+            )
+
+        resolved_subscription |= validate_formatters(
+            script=self.script,
+            unresolved_variables=self.unresolved_variables,
+            validator=self.output_options,
+        )
+
+        # TODO: make this a function
+        raw_download_output = validate_formatters(
+            script=self.script,
+            unresolved_variables=self.unresolved_variables,
+            validator=self.downloader_options.urls,
+        )
+        resolved_subscription["download"] = []
+        for url_output in raw_download_output["download"]:
+            if url_output["url"]:
+                resolved_subscription["download"].append(url_output)
+
+        assert not self.unresolved_variables
+        return resolved_subscription

{ytdl_sub-2025.12.30 → ytdl_sub-2025.12.31}/src/ytdl_sub/downloaders/url/validators.py

@@ -21,7 +21,7 @@ class UrlThumbnailValidator(StrictDictValidator):
     def __init__(self, name, value):
         super().__init__(name, value)
 
-        self._name = self._validate_key(key="name", validator=StringFormatterValidator)
+        self._thumb_name = self._validate_key(key="name", validator=StringFormatterValidator)
         self._uid = self._validate_key(key="uid", validator=OverridesStringFormatterValidator)
 
     @property
@@ -29,7 +29,7 @@ class UrlThumbnailValidator(StrictDictValidator):
         """
         File name for the thumbnail
         """
-        return self._name
+        return self._thumb_name
 
     @property
     def uid(self) -> OverridesStringFormatterValidator:

{ytdl_sub-2025.12.30 → ytdl_sub-2025.12.31}/src/ytdl_sub/script/parser.py

@@ -31,6 +31,8 @@ from ytdl_sub.script.utils.exceptions import InvalidSyntaxException
 from ytdl_sub.script.utils.exceptions import InvalidVariableName
 from ytdl_sub.script.utils.exceptions import UserException
 from ytdl_sub.script.utils.exceptions import VariableDoesNotExist
+from ytdl_sub.script.utils.name_validation import is_function
+from ytdl_sub.script.utils.name_validation import to_function_name
 from ytdl_sub.script.utils.name_validation import validate_variable_name
 
 # pylint: disable=invalid-name
@@ -144,6 +146,9 @@ class _Parser:
     ):
         self._text = text
         self._name = name
+        if name and is_function(name):
+            self._name = to_function_name(name)
+
         self._custom_function_names = custom_function_names
         self._variable_names = variable_names
         self._pos = 0

{ytdl_sub-2025.12.30 → ytdl_sub-2025.12.31}/src/ytdl_sub/script/script.py

@@ -20,28 +20,13 @@ from ytdl_sub.script.utils.exceptions import IncompatibleFunctionArguments
 from ytdl_sub.script.utils.exceptions import InvalidCustomFunctionArguments
 from ytdl_sub.script.utils.exceptions import RuntimeException
 from ytdl_sub.script.utils.exceptions import ScriptVariableNotResolved
+from ytdl_sub.script.utils.name_validation import is_function
+from ytdl_sub.script.utils.name_validation import to_function_definition_name
+from ytdl_sub.script.utils.name_validation import to_function_name
 from ytdl_sub.script.utils.name_validation import validate_variable_name
 from ytdl_sub.script.utils.type_checking import FunctionSpec
 
 
-def _is_function(override_name: str):
-    return override_name.startswith("%")
-
-
-def _function_name(function_key: str) -> str:
-    """
-    Drop the % in %custom_function
-    """
-    return function_key[1:]
-
-
-def _to_function_definition_name(function_key: str) -> str:
-    """
-    Add % in %custom_function
-    """
-    return f"%{function_key}"
-
-
 class Script:
     """
     Takes a dictionary of both
@@ -241,23 +226,23 @@ class Script:
 
     def __init__(self, script: Dict[str, str]):
         function_names: Set[str] = {
-            _function_name(name) for name in script.keys() if _is_function(name)
+            to_function_name(name) for name in script.keys() if is_function(name)
         }
         variable_names: Set[str] = {
-            validate_variable_name(name) for name in script.keys() if not _is_function(name)
+            validate_variable_name(name) for name in script.keys() if not is_function(name)
         }
 
         self._functions: Dict[str, SyntaxTree] = {
             # custom_function_name must be passed to properly type custom function
             # arguments uniquely if they're nested (i.e. $0 to $custom_func___0)
-            _function_name(function_key): parse(
+            to_function_name(function_key): parse(
                 text=function_value,
-                name=_function_name(function_key),
+                name=to_function_name(function_key),
                 custom_function_names=function_names,
                 variable_names=variable_names,
             )
             for function_key, function_value in script.items()
-            if _is_function(function_key)
+            if is_function(function_key)
         }
 
         self._variables: Dict[str, SyntaxTree] = {
@@ -268,7 +253,7 @@ class Script:
                 variable_names=variable_names,
             )
             for variable_key, variable_value in script.items()
-            if not _is_function(variable_key)
+            if not is_function(variable_key)
         }
         self._validate()
 
@@ -485,12 +470,12 @@ class Script:
         added_variables_to_validate: Set[str] = set()
 
         functions_to_add = {
-            _function_name(name): definition
+            to_function_name(name): definition
             for name, definition in variables.items()
-            if _is_function(name)
+            if is_function(name)
         }
         variables_to_add = {
-            name: definition for name, definition in variables.items() if not _is_function(name)
+            name: definition for name, definition in variables.items() if not is_function(name)
         }
 
         custom_function_names = set(self._functions.keys()) | functions_to_add.keys()
@@ -520,6 +505,46 @@ class Script:
 
         return self
 
+    def add_parsed(self, variables: Dict[str, SyntaxTree]) -> "Script":
+        """
+        Adds already parsed, new variables to the script.
+
+        Parameters
+        ----------
+        variables
+            Mapping containing variable name to definition.
+
+        Returns
+        -------
+        Script
+            self
+        """
+        added_variables_to_validate: Set[str] = set()
+
+        functions_to_add = {
+            to_function_name(name): definition
+            for name, definition in variables.items()
+            if is_function(name)
+        }
+        variables_to_add = {
+            name: definition for name, definition in variables.items() if not is_function(name)
+        }
+
+        for definitions in [functions_to_add, variables_to_add]:
+            for name, parsed in definitions.items():
+                if parsed.maybe_resolvable is None:
+                    added_variables_to_validate.add(name)
+
+                if name in functions_to_add:
+                    self._functions[name] = parsed
+                else:
+                    self._variables[name] = parsed
+
+        if added_variables_to_validate:
+            self._validate(added_variables=added_variables_to_validate)
+
+        return self
+
     def resolve_once(
         self,
         variable_definitions: Dict[str, str],
@@ -560,6 +585,46 @@ class Script:
             for name in variable_definitions.keys():
                 self._variables.pop(name, None)
 
+    def resolve_once_parsed(
+        self,
+        variable_definitions: Dict[str, SyntaxTree],
+        resolved: Optional[Dict[str, Resolvable]] = None,
+        unresolvable: Optional[Set[str]] = None,
+        update: bool = False,
+    ) -> Dict[str, Resolvable]:
+        """
+        Given a new set of variable definitions, resolve them using the Script, but do not
+        add them to the Script itself.
+
+        Parameters
+        ----------
+        variable_definitions
+            Variables to resolve, but not store in the Script
+        resolved
+            Optional. Pre-resolved variables that should be used instead of what is in the script.
+        unresolvable
+            Optional. Unresolvable variables that will be ignored in resolution, including all
+            variables with a dependency to them.
+        update
+            Whether to update the script's state with resolved variables. Defaults to False.
+
+        Returns
+        -------
+        Dict[str, Resolvable]
+            Dict containing the variable names to their resolved values.
+        """
+        try:
+            self.add_parsed(variable_definitions)
+            return self._resolve(
+                pre_resolved=resolved,
+                unresolvable=unresolvable,
+                output_filter=set(list(variable_definitions.keys())),
+                update=update,
+            ).output
+        finally:
+            for name in variable_definitions.keys():
+                self._variables.pop(name, None)
+
     def get(self, variable_name: str) -> Resolvable:
         """
         Parameters
@@ -605,4 +670,4 @@ class Script:
         Set[str]
             Names of all functions within the Script.
         """
-        return set(_to_function_definition_name(name) for name in self._functions.keys())
+        return set(to_function_definition_name(name) for name in self._functions.keys())

{ytdl_sub-2025.12.30 → ytdl_sub-2025.12.31}/src/ytdl_sub/script/utils/name_validation.py

@@ -58,3 +58,24 @@ def validate_custom_function_name(custom_function_name: str) -> None:
             f"Custom function name '%{custom_function_name}' is invalid:"
             " The name is used by a built-in function and cannot be overwritten."
         )
+
+
+def is_function(override_name: str):
+    """
+    Whether the definition is a function or not.
+    """
+    return override_name.startswith("%")
+
+
+def to_function_name(function_key: str) -> str:
+    """
+    Drop the % in %custom_function
+    """
+    return function_key[1:]
+
+
+def to_function_definition_name(function_key: str) -> str:
+    """
+    Add % in %custom_function
+    """
+    return f"%{function_key}"

{ytdl_sub-2025.12.30 → ytdl_sub-2025.12.31}/src/ytdl_sub/subscriptions/base_subscription.py

@@ -8,12 +8,14 @@ from ytdl_sub.config.plugin.preset_plugins import PresetPlugins
 from ytdl_sub.config.preset import Preset
 from ytdl_sub.config.preset_options import OutputOptions
 from ytdl_sub.config.preset_options import YTDLOptions
+from ytdl_sub.config.validators.variable_validation import VariableValidation
 from ytdl_sub.downloaders.url.validators import MultiUrlValidator
 from ytdl_sub.entries.variables.override_variables import SubscriptionVariables
 from ytdl_sub.utils.exceptions import SubscriptionPermissionError
 from ytdl_sub.utils.file_handler import FileHandler
 from ytdl_sub.utils.file_handler import FileHandlerTransactionLog
 from ytdl_sub.utils.logger import Logger
+from ytdl_sub.utils.yaml import dump_yaml
 from ytdl_sub.ytdl_additions.enhanced_download_archive import EnhancedDownloadArchive
 
 logger = Logger.get("subscription")
@@ -76,6 +78,14 @@ class BaseSubscription(ABC):
             }
         )
 
+        # Validate after adding the subscription name
+        self._validated_dict = VariableValidation(
+            overrides=self.overrides,
+            downloader_options=self.downloader_options,
+            output_options=self.output_options,
+            plugins=self.plugins,
+        ).ensure_proper_usage()
+
         self._enhanced_download_archive: Optional[EnhancedDownloadArchive] = (
             _initialize_download_archive(
                 output_options=self.output_options,
@@ -88,9 +98,9 @@ class BaseSubscription(ABC):
         # Add post-archive variables
         self.overrides.add(
             {
-                SubscriptionVariables.subscription_has_download_archive(): f"""{{
-                        %bool({self.download_archive.num_entries > 0})
-                    }}""",
+                SubscriptionVariables.subscription_has_download_archive(): (
+                    f"{{%bool({self.download_archive.num_entries > 0})}}"
+                ),
             }
         )
 
@@ -245,3 +255,11 @@ class BaseSubscription(ABC):
         Subscription in yaml format
         """
         return self._preset_options.yaml
+
+    def resolved_yaml(self) -> str:
+        """
+        Returns
+        -------
+        Human-readable, condensed YAML definition of the subscription.
+        """
+        return dump_yaml(self._validated_dict)

{ytdl_sub-2025.12.30 → ytdl_sub-2025.12.31}/src/ytdl_sub/utils/script.py

@@ -4,7 +4,6 @@ from typing import Any
 from typing import Dict
 
 from ytdl_sub.script.parser import parse
-from ytdl_sub.script.script import _is_function
 from ytdl_sub.script.types.array import UnresolvedArray
 from ytdl_sub.script.types.function import BuiltInFunction
 from ytdl_sub.script.types.function import Function
@@ -15,8 +14,10 @@ from ytdl_sub.script.types.resolvable import Float
 from ytdl_sub.script.types.resolvable import Integer
 from ytdl_sub.script.types.resolvable import Lambda
 from ytdl_sub.script.types.resolvable import String
+from ytdl_sub.script.types.syntax_tree import SyntaxTree
 from ytdl_sub.script.types.variable import Variable
 from ytdl_sub.script.utils.exceptions import UNREACHABLE
+from ytdl_sub.script.utils.name_validation import is_function
 
 # pylint: disable=too-many-return-statements
 
@@ -30,10 +31,26 @@ class ScriptUtils:
         sanitized_variables = {
             f"{name}_sanitized": f"{{%sanitize({name})}}"
             for name in variables.keys()
-            if not _is_function(name)
+            if not is_function(name)
         }
         return dict(variables, **sanitized_variables)
 
+    @classmethod
+    def add_sanitized_parsed_variables(
+        cls, variables: Dict[str, SyntaxTree]
+    ) -> Dict[str, SyntaxTree]:
+        """
+        Helper to add sanitized variables to a Script
+        """
+        sanitized_variables = {
+            f"{name}_sanitized": SyntaxTree(
+                ast=[BuiltInFunction(name="sanitize", args=[Variable(name)])]
+            )
+            for name in variables.keys()
+            if not is_function(name)
+        }
+        return variables | sanitized_variables
+
     @classmethod
     def to_script(cls, value: Any, sort_keys: bool = True) -> str:
         """