ytdl-sub 2025.12.31__py3-none-any.whl → 2026.1.27__py3-none-any.whl

ytdl_sub/__init__.py

@@ -1 +1 @@
-__pypi_version__ = "2025.12.31";__local_version__ = "2025.12.31+1abe2a4"
+__pypi_version__ = "2026.01.27";__local_version__ = "2026.01.27+d37945d"

ytdl_sub/config/overrides.py

@@ -3,6 +3,8 @@ from typing import Dict
 from typing import Iterable
 from typing import Optional
 from typing import Set
+from typing import Type
+from typing import TypeVar
 
 from ytdl_sub.entries.entry import Entry
 from ytdl_sub.entries.script.variable_definitions import VARIABLES
@@ -20,10 +22,11 @@ from ytdl_sub.utils.exceptions import StringFormattingException
 from ytdl_sub.utils.exceptions import ValidationException
 from ytdl_sub.utils.script import ScriptUtils
 from ytdl_sub.utils.scriptable import Scriptable
-from ytdl_sub.validators.string_formatter_validators import OverridesStringFormatterValidator
 from ytdl_sub.validators.string_formatter_validators import StringFormatterValidator
 from ytdl_sub.validators.string_formatter_validators import UnstructuredDictFormatterValidator
 
+ExpectedT = TypeVar("ExpectedT")
+
 
 class Overrides(UnstructuredDictFormatterValidator, Scriptable):
     """
@@ -207,7 +210,8 @@ class Overrides(UnstructuredDictFormatterValidator, Scriptable):
         formatter: StringFormatterValidator,
         entry: Optional[Entry] = None,
         function_overrides: Optional[Dict[str, str]] = None,
-    ) -> str:
+        expected_type: Type[ExpectedT] = str,
+    ) -> ExpectedT:
         """
         Parameters
         ----------
@@ -217,6 +221,8 @@ class Overrides(UnstructuredDictFormatterValidator, Scriptable):
             Optional. Entry to add source variables to the formatter
         function_overrides
             Optional. Explicit values to override the overrides themselves and source variables
+        expected_type
+            The expected type that should return. Defaults to string.
 
         Returns
         -------
@@ -227,37 +233,15 @@ class Overrides(UnstructuredDictFormatterValidator, Scriptable):
         StringFormattingException
             If the formatter that is trying to be resolved cannot
         """
-        return formatter.post_process(
-            str(
-                self._apply_to_resolvable(
-                    formatter=formatter, entry=entry, function_overrides=function_overrides
-                )
-            )
+        out = formatter.post_process(
+            self._apply_to_resolvable(
+                formatter=formatter, entry=entry, function_overrides=function_overrides
+            ).native
         )
 
-    def apply_overrides_formatter_to_native(
-        self,
-        formatter: OverridesStringFormatterValidator,
-    ) -> Any:
-        """
-        Parameters
-        ----------
-        formatter
-            Overrides formatter to apply
-
-        Returns
-        -------
-        The native python form of the resolved variable
-        """
-        return self._apply_to_resolvable(
-            formatter=formatter, entry=None, function_overrides=None
-        ).native
+        if not isinstance(out, expected_type):
+            raise StringFormattingException(
+                f"Expected type {expected_type.__name__}, but received '{out.__class__.__name__}'"
+            )
 
-    def evaluate_boolean(
-        self, formatter: StringFormatterValidator, entry: Optional[Entry] = None
-    ) -> bool:
-        """
-        Apply a formatter, and evaluate it to a boolean
-        """
-        output = self.apply_formatter(formatter=formatter, entry=entry)
-        return ScriptUtils.bool_formatter_output(output)
+        return out

ytdl_sub/config/plugin/plugin.py

@@ -48,7 +48,7 @@ class Plugin(BasePlugin[OptionsValidatorT], Generic[OptionsValidatorT], ABC):
         Returns True if enabled, False if disabled.
         """
         if isinstance(self.plugin_options, ToggleableOptionsDictValidator):
-            return self.overrides.evaluate_boolean(self.plugin_options.enable)
+            return self.overrides.apply_formatter(self.plugin_options.enable, expected_type=bool)
         return True
 
     def ytdl_options_match_filters(self) -> Tuple[List[str], List[str]]:

ytdl_sub/config/preset_options.py

@@ -63,7 +63,7 @@ class YTDLOptions(UnstructuredOverridesDictFormatterValidator):
         native python.
         """
         out = {
-            key: overrides.apply_overrides_formatter_to_native(val)
+            key: overrides.apply_formatter(val, expected_type=object)
             for key, val in self.dict.items()
         }
         if "cookiefile" in out:

ytdl_sub/config/validators/variable_validation.py

@@ -84,6 +84,9 @@ class VariableValidation:
         )
         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)
 

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_formatter(validator.url, expected_type=list):
                 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_formatter(validator.url, expected_type=list):
                 return validator
 
         # Return the first validator if none exist
@@ -382,7 +382,7 @@ class MultiUrlDownloader(SourcePlugin[MultiUrlValidator]):
         entries_to_iter: List[Optional[Entry]] = entries
 
         indices = list(range(len(entries_to_iter)))
-        if self.overrides.evaluate_boolean(validator.download_reverse):
+        if self.overrides.apply_formatter(validator.download_reverse, expected_type=bool):
             indices = reversed(indices)
 
         for idx in indices:
@@ -461,8 +461,8 @@ class MultiUrlDownloader(SourcePlugin[MultiUrlValidator]):
             ytdl_option_overrides=validator.ytdl_options.to_native_dict(self.overrides)
         )
 
-        include_sibling_metadata = self.overrides.evaluate_boolean(
-            validator.include_sibling_metadata
+        include_sibling_metadata = self.overrides.apply_formatter(
+            validator.include_sibling_metadata, expected_type=bool
         )
 
         parents, orphan_entries = self._download_url_metadata(
@@ -487,19 +487,25 @@ 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_formatter(url_validator.url, expected_type=list)):
                 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),
-                    }
-                )
+            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/downloaders/url/validators.py

@@ -1,5 +1,6 @@
 from typing import Any
 from typing import Dict
+from typing import List
 from typing import Optional
 from typing import Set
 
@@ -43,6 +44,19 @@ class UrlThumbnailListValidator(ListValidator[UrlThumbnailValidator]):
     _inner_list_type = UrlThumbnailValidator
 
 
+class OverridesOneOrManyUrlValidator(OverridesStringFormatterValidator):
+    def post_process(self, resolved: Any) -> List[str]:
+        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 +82,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/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/plugins/date_range.py

@@ -116,7 +116,7 @@ class DateRangePlugin(Plugin[DateRangeOptions]):
                 date_validator=self.plugin_options.after, overrides=self.overrides
             )
             after_filter = f"{date_type} >= {after_str}"
-            if self.overrides.evaluate_boolean(self.plugin_options.breaks):
+            if self.overrides.apply_formatter(self.plugin_options.breaks, expected_type=bool):
                 breaking_match_filters.append(after_filter)
             else:
                 match_filters.append(after_filter)

ytdl_sub/plugins/embed_thumbnail.py

@@ -33,7 +33,7 @@ class EmbedThumbnailPlugin(Plugin[EmbedThumbnailOptions]):
 
     @property
     def _embed_thumbnail(self) -> bool:
-        return self.overrides.evaluate_boolean(self.plugin_options)
+        return self.overrides.apply_formatter(self.plugin_options, expected_type=bool)
 
     @classmethod
     def _embed_video_thumbnail(cls, entry: Entry) -> None:

ytdl_sub/plugins/filter_exclude.py

@@ -7,13 +7,14 @@ from ytdl_sub.config.validators.options import OptionsValidator
 from ytdl_sub.entries.entry import Entry
 from ytdl_sub.utils.exceptions import StringFormattingException
 from ytdl_sub.utils.logger import Logger
-from ytdl_sub.validators.string_formatter_validators import ListFormatterValidator
+from ytdl_sub.validators.string_formatter_validators import BooleanFormatterValidator
+from ytdl_sub.validators.validators import ListValidator
 from ytdl_sub.ytdl_additions.enhanced_download_archive import EnhancedDownloadArchive
 
 logger = Logger.get("filter-exclude")
 
 
-class FilterExcludeOptions(ListFormatterValidator, OptionsValidator):
+class FilterExcludeOptions(ListValidator[BooleanFormatterValidator], OptionsValidator):
     """
     Applies a conditional OR on any number of filters comprised of either variables or scripts.
     If any filter evaluates to True, the entry will be excluded.
@@ -29,6 +30,8 @@ class FilterExcludeOptions(ListFormatterValidator, OptionsValidator):
            { %contains( %lower(description), '#short' ) }
     """
 
+    _inner_list_type = BooleanFormatterValidator
+
 
 class FilterExcludePlugin(Plugin[FilterExcludeOptions]):
     plugin_options_type = FilterExcludeOptions
@@ -52,7 +55,9 @@ class FilterExcludePlugin(Plugin[FilterExcludeOptions]):
             return entry
 
         for formatter in self.plugin_options.list:
-            should_exclude = self.overrides.evaluate_boolean(formatter=formatter, entry=entry)
+            should_exclude = self.overrides.apply_formatter(
+                formatter=formatter, entry=entry, expected_type=bool
+            )
 
             if should_exclude:
                 logger.info(

ytdl_sub/plugins/filter_include.py

@@ -7,14 +7,14 @@ from ytdl_sub.config.validators.options import OptionsValidator
 from ytdl_sub.entries.entry import Entry
 from ytdl_sub.utils.exceptions import StringFormattingException
 from ytdl_sub.utils.logger import Logger
-from ytdl_sub.utils.script import ScriptUtils
-from ytdl_sub.validators.string_formatter_validators import ListFormatterValidator
+from ytdl_sub.validators.string_formatter_validators import BooleanFormatterValidator
+from ytdl_sub.validators.validators import ListValidator
 from ytdl_sub.ytdl_additions.enhanced_download_archive import EnhancedDownloadArchive
 
 logger = Logger.get("filter-include")
 
 
-class FilterIncludeOptions(ListFormatterValidator, OptionsValidator):
+class FilterIncludeOptions(ListValidator[BooleanFormatterValidator], OptionsValidator):
     """
     Applies a conditional AND on any number of filters comprised of either variables or scripts.
     If all filters evaluate to True, the entry will be included.
@@ -38,6 +38,8 @@ class FilterIncludeOptions(ListFormatterValidator, OptionsValidator):
            }
     """
 
+    _inner_list_type = BooleanFormatterValidator
+
 
 class FilterIncludePlugin(Plugin[FilterIncludeOptions]):
     plugin_options_type = FilterIncludeOptions
@@ -61,8 +63,8 @@ class FilterIncludePlugin(Plugin[FilterIncludeOptions]):
             return entry
 
         for formatter in self.plugin_options.list:
-            should_exclude = ScriptUtils.bool_formatter_output(
-                self.overrides.apply_formatter(formatter=formatter, entry=entry)
+            should_exclude = self.overrides.apply_formatter(
+                formatter=formatter, entry=entry, expected_type=bool
             )
             if not should_exclude:
                 logger.info(

ytdl_sub/plugins/nfo_tags.py

@@ -140,7 +140,7 @@ class SharedNfoTagsPlugin(Plugin[SharedNfoTagsOptions], ABC):
         if not nfo_tags:
             return
 
-        if self.overrides.evaluate_boolean(self.plugin_options.kodi_safe):
+        if self.overrides.apply_formatter(self.plugin_options.kodi_safe, expected_type=bool):
             nfo_root = to_max_3_byte_utf8_string(nfo_root)
             nfo_tags = {
                 to_max_3_byte_utf8_string(key): [

ytdl_sub/plugins/square_thumbnail.py

@@ -31,7 +31,7 @@ class SquareThumbnailPlugin(Plugin[SquareThumbnailOptions]):
 
     @property
     def _square_thumbnail(self) -> bool:
-        return self.overrides.evaluate_boolean(self.plugin_options)
+        return self.overrides.apply_formatter(self.plugin_options, expected_type=bool)
 
     @classmethod
     def _convert_to_square_thumbnail(cls, entry: Entry) -> None:

ytdl_sub/plugins/throttle_protection.py

@@ -42,8 +42,8 @@ class _RandomizedRangeValidator(StrictDictValidator, ABC):
         )
 
     def _randomized_float(self, overrides: Overrides, entry: Optional[Entry] = None) -> float:
-        actualized_min = float(overrides.apply_formatter(self._min, entry=entry))
-        actualized_max = float(overrides.apply_formatter(self._max, entry=entry))
+        actualized_min = overrides.apply_formatter(self._min, entry=entry, expected_type=float)
+        actualized_max = overrides.apply_formatter(self._max, entry=entry, expected_type=float)
 
         if actualized_min < 0:
             raise self._validation_exception(
@@ -70,7 +70,7 @@ class _RandomizedRangeValidator(StrictDictValidator, ABC):
         -------
         Max possible value
         """
-        actualized_max = float(overrides.apply_formatter(self._max, entry=entry))
+        actualized_max = overrides.apply_formatter(self._max, entry=entry, expected_type=float)
         if actualized_max < 0:
             raise self._validation_exception(
                 f"max must be greater than zero, received {actualized_max}"

ytdl_sub/plugins/video_tags.py

@@ -34,7 +34,7 @@ class VideoTagsPlugin(Plugin[VideoTagsOptions]):
         Tags the entry's audio file using values defined in the metadata options
         """
         tags_to_write: Dict[str, str] = {}
-        for tag_name, tag_formatter in self.plugin_options.dict.items():
+        for tag_name, tag_formatter in sorted(self.plugin_options.dict.items()):
             tag_value = self.overrides.apply_formatter(formatter=tag_formatter, entry=entry)
             tags_to_write[tag_name] = tag_value