ytdl-sub 2025.12.8__tar.gz → 2026.1.11__tar.gz

{ytdl_sub-2025.12.8 → ytdl_sub-2026.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ytdl-sub
-Version: 2025.12.8
+Version: 2026.1.11
 Summary: Automate downloading metadata generation with YoutubeDL
 Author: Jesse Bannon
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -703,7 +703,7 @@ Requires-Dist: black==24.10.0; extra == "lint"
 Requires-Dist: isort==7.0.0; extra == "lint"
 Requires-Dist: pylint==4.0.1; extra == "lint"
 Provides-Extra: docs
-Requires-Dist: sphinx<9,>=7; extra == "docs"
+Requires-Dist: sphinx<10,>=7; extra == "docs"
 Requires-Dist: sphinx-rtd-theme<4,>=2; extra == "docs"
 Requires-Dist: sphinx-book-theme~=1.0; extra == "docs"
 Requires-Dist: sphinx-copybutton~=0.5; extra == "docs"

{ytdl_sub-2025.12.8 → ytdl_sub-2026.1.11}/pyproject.toml

@@ -52,7 +52,7 @@ lint = [
     "pylint==4.0.1",
 ]
 docs = [
-    "sphinx>=7,<9",
+    "sphinx>=7,<10",
     "sphinx-rtd-theme>=2,<4",
     "sphinx-book-theme~=1.0",
     "sphinx-copybutton~=0.5",

ytdl_sub-2026.1.11/src/ytdl_sub/__init__.py

@@ -0,0 +1 @@
+__pypi_version__ = "2026.01.11";__local_version__ = "2026.01.11+41a5bf6"

{ytdl_sub-2025.12.8 → ytdl_sub-2026.1.11}/src/ytdl_sub/config/overrides.py

@@ -1,17 +1,19 @@
 from typing import Any
 from typing import Dict
+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
@@ -88,6 +90,24 @@ class Overrides(UnstructuredDictFormatterValidator, Scriptable):
 
         return True
 
+    def ensure_variable_names_not_a_plugin(self, plugin_names: Iterable[str]) -> None:
+        """
+        Throws an error if an override variable or function has the same name as a
+        preset key. This is to avoid confusion when accidentally defining things in
+        overrides that are meant to be in the preset.
+        """
+        for name in self.keys:
+            if name.startswith("%"):
+                name = name[1:]
+
+            if name in plugin_names:
+                raise self._validation_exception(
+                    f"Override variable with name {name} cannot be used since it is"
+                    " the name of a plugin. Perhaps you meant to define it as a plugin? If so,"
+                    " indent it left to make it at the same level as overrides.",
+                    exception_class=InvalidVariableNameException,
+                )
+
     def ensure_variable_name_valid(self, name: str) -> None:
         """
         Ensures the variable name does not collide with any entry variables or built-in functions.
@@ -115,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
                 }
             )
@@ -212,20 +238,25 @@ class Overrides(UnstructuredDictFormatterValidator, Scriptable):
     def apply_overrides_formatter_to_native(
         self,
         formatter: OverridesStringFormatterValidator,
+        function_overrides: Optional[Dict[str, str]] = None,
     ) -> Any:
         """
         Parameters
         ----------
         formatter
             Overrides formatter to apply
+        function_overrides
+            Optional. Explicit values to override the overrides themselves and source variables
 
         Returns
         -------
         The native python form of the resolved variable
         """
-        return self._apply_to_resolvable(
-            formatter=formatter, entry=None, function_overrides=None
-        ).native
+        return formatter.post_process_native(
+            self._apply_to_resolvable(
+                formatter=formatter, entry=None, function_overrides=function_overrides
+            ).native
+        )
 
     def evaluate_boolean(
         self, formatter: StringFormatterValidator, entry: Optional[Entry] = None

{ytdl_sub-2025.12.8 → ytdl_sub-2026.1.11}/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.8 → ytdl_sub-2026.1.11}/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,13 +223,10 @@ class Preset(_PresetShell):
         )
 
         self.plugins: PresetPlugins = self._validate_and_get_plugins()
-        self.overrides = self._validate_key(key="overrides", validator=Overrides, default={})
-
-        VariableValidation(
-            downloader_options=self.downloader_options,
-            output_options=self.output_options,
-            plugins=self.plugins,
-        ).initialize_preset_overrides(overrides=self.overrides).ensure_proper_usage()
+        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)
 
     @property
     def name(self) -> str:

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

@@ -0,0 +1,94 @@
+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 isinstance(url_output["url"], list):
+                url_output["url"] = [url for url in url_output["url"] if bool(url)]
+
+            if url_output["url"]:
+                resolved_subscription["download"].append(url_output)
+
+        assert not self.unresolved_variables
+        return resolved_subscription

{ytdl_sub-2025.12.8 → ytdl_sub-2026.1.11}/src/ytdl_sub/downloaders/url/downloader.py

@@ -52,12 +52,12 @@ class UrlDownloaderBasePluginExtension(SourcePluginExtension[MultiUrlValidator])
 
         if 0 <= input_url_idx < len(self.plugin_options.urls.list):
             validator = self.plugin_options.urls.list[input_url_idx]
-            if self.overrides.apply_formatter(validator.url) == entry_input_url:
+            if entry_input_url in self.overrides.apply_overrides_formatter_to_native(validator.url):
                 return validator
 
         # Match the first validator based on the URL, if one exists
         for validator in self.plugin_options.urls.list:
-            if self.overrides.apply_formatter(validator.url) == entry_input_url:
+            if entry_input_url in self.overrides.apply_overrides_formatter_to_native(validator.url):
                 return validator
 
         # Return the first validator if none exist
@@ -487,19 +487,27 @@ class MultiUrlDownloader(SourcePlugin[MultiUrlValidator]):
         # download the bottom-most urls first since they are top-priority
         for idx, url_validator in reversed(list(enumerate(self.collection.urls.list))):
             # URLs can be empty. If they are, then skip
-            if not (url := self.overrides.apply_formatter(url_validator.url)):
+            if not (urls := self.overrides.apply_overrides_formatter_to_native(url_validator.url)):
                 continue
 
-            for entry in self._download_metadata(url=url, validator=url_validator):
-                entry.initialize_script(self.overrides).add(
-                    {
-                        v.ytdl_sub_input_url: url,
-                        v.ytdl_sub_input_url_index: idx,
-                        v.ytdl_sub_input_url_count: len(self.collection.urls.list),
-                    }
-                )
+            assert isinstance(urls, list)
+
+            for url in reversed(urls):
+                assert isinstance(url, str)
+
+                if not url:
+                    continue
+
+                for entry in self._download_metadata(url=url, validator=url_validator):
+                    entry.initialize_script(self.overrides).add(
+                        {
+                            v.ytdl_sub_input_url: url,
+                            v.ytdl_sub_input_url_index: idx,
+                            v.ytdl_sub_input_url_count: len(self.collection.urls.list),
+                        }
+                    )
 
-                yield entry
+                    yield entry
 
     def download(self, entry: Entry) -> Optional[Entry]:
         """

{ytdl_sub-2025.12.8 → ytdl_sub-2026.1.11}/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:
@@ -43,6 +43,19 @@ class UrlThumbnailListValidator(ListValidator[UrlThumbnailValidator]):
     _inner_list_type = UrlThumbnailValidator
 
 
+class OverridesOneOrManyUrlValidator(OverridesStringFormatterValidator):
+    def post_process_native(self, resolved: Any) -> Any:
+        if isinstance(resolved, str):
+            return [resolved]
+        if isinstance(resolved, list):
+            for value in resolved:
+                if not isinstance(value, str):
+                    raise self._validation_exception("Must be a string or an array of strings.")
+            return resolved
+
+        raise self._validation_exception("Must be a string or an array of strings.")
+
+
 class UrlValidator(StrictDictValidator):
     _required_keys = {"url"}
     _optional_keys = {
@@ -68,7 +81,7 @@ class UrlValidator(StrictDictValidator):
         super().__init__(name, value)
 
         # TODO: url validate using yt-dlp IE
-        self._url = self._validate_key(key="url", validator=OverridesStringFormatterValidator)
+        self._url = self._validate_key(key="url", validator=OverridesOneOrManyUrlValidator)
         self._variables = self._validate_key_if_present(
             key="variables", validator=DictFormatterValidator, default={}
         )

{ytdl_sub-2025.12.8 → ytdl_sub-2026.1.11}/src/ytdl_sub/entries/script/variable_types.py

@@ -22,7 +22,6 @@ VariableT = TypeVar("VariableT", bound="Variable")
 
 
 def _get(
-    cast: str,
     metadata_variable_name: str,
     metadata_key: str,
     variable_name: Optional[str],
@@ -47,7 +46,7 @@ def _get(
     return as_type(
         variable_name=variable_name or metadata_key,
         metadata_key=metadata_key,
-        definition=f"{{ %legacy_bracket_safety(%{cast}({out})) }}",
+        definition=f"{{ {out} }}",
     )
 
 
@@ -182,7 +181,6 @@ class MapMetadataVariable(MetadataVariable, MapVariable):
         Creates a map variable from entry metadata
         """
         return _get(
-            "map",
             metadata_variable_name=ENTRY_METADATA_VARIABLE_NAME,
             metadata_key=metadata_key,
             variable_name=variable_name,
@@ -204,7 +202,6 @@ class ArrayMetadataVariable(MetadataVariable, ArrayVariable):
         Creates an array variable from entry metadata
         """
         return _get(
-            "array",
             metadata_variable_name=ENTRY_METADATA_VARIABLE_NAME,
             metadata_key=metadata_key,
             variable_name=variable_name,
@@ -226,7 +223,6 @@ class StringMetadataVariable(MetadataVariable, StringVariable):
         Creates a string variable from entry metadata
         """
         return _get(
-            "string",
             metadata_variable_name=ENTRY_METADATA_VARIABLE_NAME,
             metadata_key=metadata_key,
             variable_name=variable_name,
@@ -245,7 +241,6 @@ class StringMetadataVariable(MetadataVariable, StringVariable):
         Creates a string variable from playlist metadata
         """
         return _get(
-            "string",
             metadata_variable_name=PLAYLIST_METADATA_VARIABLE_NAME,
             metadata_key=metadata_key,
             variable_name=variable_name,
@@ -264,7 +259,6 @@ class StringMetadataVariable(MetadataVariable, StringVariable):
         Creates a string variable from source metadata
         """
         return _get(
-            "string",
             metadata_variable_name=SOURCE_METADATA_VARIABLE_NAME,
             metadata_key=metadata_key,
             variable_name=variable_name,
@@ -301,7 +295,6 @@ class IntegerMetadataVariable(MetadataVariable, IntegerVariable):
         Creates an int variable from entry metadata
         """
         return _get(
-            "int",
             metadata_variable_name=ENTRY_METADATA_VARIABLE_NAME,
             metadata_key=metadata_key,
             variable_name=variable_name,
@@ -320,7 +313,6 @@ class IntegerMetadataVariable(MetadataVariable, IntegerVariable):
         Creates an int variable from playlist metadata
         """
         return _get(
-            "int",
             metadata_variable_name=PLAYLIST_METADATA_VARIABLE_NAME,
             metadata_key=metadata_key,
             variable_name=variable_name,

{ytdl_sub-2025.12.8 → ytdl_sub-2026.1.11}/src/ytdl_sub/entries/variables/override_variables.py

@@ -11,9 +11,6 @@ from ytdl_sub.entries.script.variable_types import Variable
 from ytdl_sub.script.functions import Functions
 from ytdl_sub.script.utils.name_validation import is_valid_name
 
-# TODO: use this
-SUBSCRIPTION_ARRAY = "subscription_array"
-
 
 class SubscriptionVariables:
     @staticmethod
@@ -163,7 +160,7 @@ class OverrideHelpers:
         True if the override name itself is valid. False otherwise.
         """
         if name.startswith("%"):
-            return is_valid_name(name=name[1:])
+            name = name[1:]
 
         return is_valid_name(name=name)
 

{ytdl_sub-2025.12.8 → ytdl_sub-2026.1.11}/src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml

@@ -11,8 +11,7 @@ presets:
 
     # Set the default date_range to 2 months
     overrides:
-      date_range: "2months"  # keep for legacy-reasons
-      only_recent_date_range: "{date_range}"
+      only_recent_date_range: "2months"
 
   #############################################################################
   # Only Recent