ytdl-sub 2026.1.30__tar.gz → 2026.2.2.post1__tar.gz

{ytdl_sub-2026.1.30 → ytdl_sub-2026.2.2.post1}/PKG-INFO

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

ytdl_sub-2026.2.2.post1/src/ytdl_sub/__init__.py

@@ -0,0 +1 @@
+__pypi_version__ = "2026.02.02.post1";__local_version__ = "2026.02.02+ced547b"

{ytdl_sub-2026.1.30 → ytdl_sub-2026.2.2.post1}/src/ytdl_sub/cli/entrypoint.py

@@ -1,5 +1,6 @@
 import gc
 import os
+import random
 import sys
 from datetime import datetime
 from pathlib import Path
@@ -75,6 +76,7 @@ def _download_subscriptions_from_yaml_files(
     subscription_override_dict: Dict,
     update_with_info_json: bool,
     dry_run: bool,
+    shuffle: bool,
 ) -> List[Subscription]:
     """
     Downloads all subscriptions from one or many subscription yaml files.
@@ -91,6 +93,8 @@ def _download_subscriptions_from_yaml_files(
         Whether to actually download or update using existing info json
     dry_run
         Whether to dry run or not
+    shuffle
+        Whether to shuffle the subscription download order
 
     Returns
     -------
@@ -112,6 +116,10 @@ def _download_subscriptions_from_yaml_files(
             subscription_override_dict=subscription_override_dict,
         )
 
+    if shuffle:
+        logger.info("Shuffling subscriptions")
+        random.shuffle(subscriptions)
+
     for subscription in subscriptions:
         with subscription.exception_handling():
             logger.info(
@@ -253,6 +261,7 @@ def main() -> List[Subscription]:
                 subscription_override_dict=subscription_override_dict,
                 update_with_info_json=args.update_with_info_json,
                 dry_run=args.dry_run,
+                shuffle=args.shuffle,
             )
 
         # One-off download

{ytdl_sub-2026.1.30 → ytdl_sub-2026.2.2.post1}/src/ytdl_sub/cli/parsers/main.py

@@ -172,6 +172,10 @@ class SubArguments:
         short="-o",
         long="--dl-override",
     )
+    SHUFFLE = CLIArgument(
+        short="-sh",
+        long="--shuffle",
+    )
 
 
 subscription_parser = subparsers.add_parser("sub")
@@ -197,6 +201,13 @@ subscription_parser.add_argument(
     help="override all subscription config values using `dl` syntax, "
     "i.e. --dl-override='--ytdl_options.max_downloads 3'",
 )
+subscription_parser.add_argument(
+    SubArguments.SHUFFLE.short,
+    SubArguments.SHUFFLE.long,
+    action="store_true",
+    help="shuffle subscription order when downloading",
+    default=False,
+)
 
 ###################################################################################################
 # DOWNLOAD PARSER

{ytdl_sub-2026.1.30 → ytdl_sub-2026.2.2.post1}/src/ytdl_sub/config/preset.py

@@ -255,11 +255,18 @@ class Preset(_PresetShell):
         """
         return cls(config=config, name=preset_name, value=preset_dict)
 
-    @property
-    def yaml(self) -> str:
+    def yaml(self, subscription_only: bool) -> str:
         """
+        Parameters
+        ----------
+        subscription_only:
+            Only include the subscription contents, not the surrounding boiler-plate.
+
         Returns
         -------
         Preset in YAML format
         """
+        if subscription_only:
+            return dump_yaml(self._value)
+
         return dump_yaml({"presets": {self._name: self._value}})

ytdl_sub-2026.2.2.post1/src/ytdl_sub/config/validators/variable_validation.py

@@ -0,0 +1,196 @@
+from typing import Dict
+from typing import List
+from typing import Set
+
+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.entries.script.variable_definitions import UNRESOLVED_VARIABLES
+from ytdl_sub.entries.script.variable_definitions import VARIABLES
+from ytdl_sub.script.script import Script
+from ytdl_sub.script.utils.name_validation import is_function
+from ytdl_sub.utils.script import ScriptUtils
+from ytdl_sub.validators.string_formatter_validators import validate_formatters
+
+
+class ResolutionLevel:
+    ORIGINAL = 0
+    FILL = 1
+    RESOLVE = 2
+    INTERNAL = 3
+
+    @classmethod
+    def name_of(cls, resolution_level: int) -> str:
+        """
+        Name of the resolution level.
+        """
+        if resolution_level == cls.ORIGINAL:
+            return "original"
+        if resolution_level == cls.FILL:
+            return "fill"
+        if resolution_level == cls.RESOLVE:
+            return "resolve"
+        if resolution_level == cls.INTERNAL:
+            return "internal"
+        raise ValueError("Invalid resolution level")
+
+    @classmethod
+    def all(cls) -> List[int]:
+        """
+        All possible resolution levels.
+        """
+        return [cls.ORIGINAL, cls.FILL, cls.RESOLVE, cls.INTERNAL]
+
+
+class VariableValidation:
+
+    def _get_resolve_partial_filter(self) -> Set[str]:
+        # Exclude sanitized variables from partial validation. This lessens the work
+        # and prevents double-evaluation, which can lead to bad behavior like double-prints.
+        return {
+            name
+            for name in self.script.variable_names
+            if name not in self.unresolved_variables and not name.endswith("_sanitized")
+        }
+
+    def _apply_resolution_level(self) -> None:
+        if self._resolution_level == ResolutionLevel.FILL:
+            self.unresolved_variables |= VARIABLES.variable_names(include_sanitized=True)
+            # Only partial resolve definitions that are already resolved
+            self.unresolved_variables |= {
+                name
+                for name in self.overrides.keys
+                if not is_function(name) and not self.script.definition_of(name).maybe_resolvable
+            }
+        elif self._resolution_level == ResolutionLevel.RESOLVE:
+            # Partial resolve everything, but not including internal variables
+            self.unresolved_variables |= VARIABLES.variable_names(include_sanitized=True)
+        elif self._resolution_level == ResolutionLevel.INTERNAL:
+            # Partial resolve everything including internal variables
+            pass
+        else:
+            raise ValueError("Invalid resolution level for validation")
+
+        self.script = self.script.resolve_partial(
+            unresolvable=self.unresolved_variables,
+            output_filter=self._get_resolve_partial_filter(),
+        )
+
+    def __init__(
+        self,
+        overrides: Overrides,
+        downloader_options: MultiUrlValidator,
+        output_options: OutputOptions,
+        plugins: PresetPlugins,
+        resolution_level: int = ResolutionLevel.RESOLVE,
+    ):
+        self.overrides = overrides
+        self.downloader_options = downloader_options
+        self.output_options = output_options
+        self.plugins = plugins
+
+        self.script: Script = self.overrides.script
+        self.unresolved_variables = (
+            self.plugins.get_all_variables(
+                additional_options=[self.output_options, self.downloader_options]
+            )
+            | UNRESOLVED_VARIABLES
+        )
+        self.unresolved_runtime_variables = self.plugins.get_all_variables(
+            additional_options=[self.output_options, self.downloader_options]
+        )
+        self._resolution_level = resolution_level
+
+        self._apply_resolution_level()
+
+    def _add_runtime_variables(self, plugin_op: PluginOperation, options: OptionsValidator) -> None:
+        """
+        Add dummy variables for script validation
+        """
+        added_variables = options.added_variables(
+            unresolved_variables=self.unresolved_runtime_variables,
+        ).get(plugin_op, set())
+        modified_variables = options.modified_variables().get(plugin_op, set())
+
+        self.unresolved_runtime_variables -= added_variables | modified_variables
+
+    def ensure_proper_usage(self, partial_resolve_formatters: bool = False) -> 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_runtime_variables(PluginOperation.DOWNLOADER, options=self.downloader_options)
+
+        # Always add output options first
+        self._add_runtime_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_runtime_variables(
+                PluginOperation.MODIFY_ENTRY_METADATA, options=plugin_options
+            )
+
+        for plugin_options in PluginMapping.order_options_by(
+            self.plugins.zipped(), PluginOperation.MODIFY_ENTRY
+        ):
+            self._add_runtime_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,
+                unresolved_runtime_variables=self.unresolved_runtime_variables,
+                validator=plugin_options,
+                partial_resolve_formatters=partial_resolve_formatters,
+            )
+
+        resolved_subscription |= validate_formatters(
+            script=self.script,
+            unresolved_variables=self.unresolved_variables,
+            unresolved_runtime_variables=self.unresolved_runtime_variables,
+            validator=self.output_options,
+            partial_resolve_formatters=partial_resolve_formatters,
+        )
+
+        # TODO: make this a function
+        raw_download_output = validate_formatters(
+            script=self.script,
+            unresolved_variables=self.unresolved_variables,
+            unresolved_runtime_variables=self.unresolved_runtime_variables,
+            validator=self.downloader_options.urls,
+            partial_resolve_formatters=partial_resolve_formatters,
+        )
+        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)
+
+        # TODO: make function
+        resolved_subscription["overrides"] = {}
+        for name in self.overrides.keys:
+            value = self.script.definition_of(name)
+            if name in self.script.function_names:
+                # Keep custom functions as-is
+                resolved_subscription["overrides"][name] = self.overrides.dict_with_format_strings[
+                    name
+                ]
+            elif resolved := value.maybe_resolvable:
+                resolved_subscription["overrides"][name] = resolved.native
+            else:
+                resolved_subscription["overrides"][name] = ScriptUtils.to_native_script(value)
+
+        assert not self.unresolved_runtime_variables
+        return resolved_subscription

{ytdl_sub-2026.1.30 → ytdl_sub-2026.2.2.post1}/src/ytdl_sub/entries/script/variable_definitions.py

@@ -1135,6 +1135,16 @@ class VariableDefinitions(
             ]
         }
 
+    @cache
+    def variable_names(self, include_sanitized: bool):
+        """
+        Returns all variable names, and can include sanitized.
+        """
+        var_names: Set[str] = self.scripts().keys()
+        if include_sanitized:
+            var_names |= {f"{name}_sanitized" for name in var_names}
+        return var_names
+
     @cache
     def injected_variables(self) -> Set[MetadataVariable]:
         """

{ytdl_sub-2026.1.30 → ytdl_sub-2026.2.2.post1}/src/ytdl_sub/script/script.py

@@ -1,5 +1,4 @@
 # pylint: disable=missing-raises-doc
-import copy
 from collections import defaultdict
 from typing import Dict
 from typing import List
@@ -693,6 +692,18 @@ class Script:
 
         raise RuntimeException(f"Tried to get unresolved variable {variable_name}")
 
+    def definition_of(self, name: str) -> SyntaxTree:
+        """
+        Returns
+        -------
+        The definition of the variable or function.
+        """
+        if name.startswith("%") and name[1:] in self._functions:
+            return self._functions[name[1:]]
+        if name in self._variables:
+            return self._variables[name]
+        raise RuntimeException(f"Tried to get non-existent definition with name {name}")
+
     @property
     def variable_names(self) -> Set[str]:
         """
@@ -713,35 +724,33 @@ class Script:
         """
         return set(to_function_definition_name(name) for name in self._functions.keys())
 
-    def resolve_partial(
+    def _resolve_partial_loop(
         self,
-        unresolvable: Optional[Set[str]] = None,
-    ) -> "Script":
-        """
-        Returns
-        -------
-        New (deep-copied) script that resolves inner variables as much
-        as possible.
-        """
-        unresolvable: Set[str] = unresolvable or {}
-        resolved: Dict[Variable, Resolvable] = {}
-        unresolved: Dict[Variable, Argument] = {
-            Variable(name): definition
-            for name, definition in self._variables.items()
-            if name not in unresolvable
-        }
+        output_filter: Optional[Set[str]],
+        resolved: Dict[Variable, Resolvable],
+        unresolved: Dict[Variable, Argument],
+        unresolvable: Optional[Set[str]],
+    ):
+        to_partially_resolve: Set[Variable] = (
+            {Variable(name) for name in output_filter} if output_filter else set(unresolved.keys())
+        )
 
         partially_resolved = True
         while partially_resolved:
 
             partially_resolved = False
 
-            for variable in list(unresolved.keys()):
+            for variable in list(to_partially_resolve):
                 definition = unresolved[variable]
-
                 maybe_resolved = definition
+
                 if isinstance(definition, Variable) and definition.name not in unresolvable:
-                    maybe_resolved = resolved.get(definition, unresolved[definition])
+                    if definition in resolved:
+                        maybe_resolved = resolved[definition]
+                    elif definition in unresolved:
+                        maybe_resolved = unresolved[definition]
+                    else:
+                        raise UNREACHABLE
                 elif isinstance(definition, VariableDependency):
                     maybe_resolved = definition.partial_resolve(
                         resolved_variables=resolved,
@@ -752,6 +761,7 @@ class Script:
                 if isinstance(maybe_resolved, Resolvable):
                     resolved[variable] = maybe_resolved
                     del unresolved[variable]
+                    to_partially_resolve.remove(variable)
                     partially_resolved = True
                 else:
                     unresolved[variable] = maybe_resolved
@@ -760,11 +770,73 @@ class Script:
                 # which means we can iterate again
                 partially_resolved |= definition != maybe_resolved
 
-        return copy.deepcopy(self).add_parsed(
-            {var_name: self._variables[var_name] for var_name in unresolvable}
-            | {
-                var.name: ResolvedSyntaxTree(ast=[definition])
-                for var, definition in resolved.items()
-            }
-            | {var.name: SyntaxTree(ast=[definition]) for var, definition in unresolved.items()}
+    def _resolve_partial(
+        self,
+        unresolvable: Optional[Set[str]] = None,
+        output_filter: Optional[Set[str]] = None,
+    ) -> Dict[str, SyntaxTree]:
+        """
+        Returns
+        -------
+        New (deep-copied) script that resolves inner variables as much
+        as possible.
+        """
+        unresolvable: Set[str] = unresolvable or {}
+        resolved: Dict[Variable, Resolvable] = {}
+        unresolved: Dict[Variable, Argument] = {
+            Variable(name): definition
+            for name, definition in self._variables.items()
+            if name not in unresolvable
+        }
+
+        self._resolve_partial_loop(
+            output_filter=output_filter,
+            resolved=resolved,
+            unresolved=unresolved,
+            unresolvable=unresolvable,
         )
+
+        if output_filter:
+            out: Dict[str, SyntaxTree] = {}
+            for name in output_filter:
+                variable_name = Variable(name)
+                if variable_name in resolved:
+                    out[name] = ResolvedSyntaxTree(ast=[resolved[variable_name]])
+                else:
+                    out[name] = SyntaxTree(ast=[unresolved[variable_name]])
+
+            return out
+
+        return {
+            var.name: ResolvedSyntaxTree(ast=[definition]) for var, definition in resolved.items()
+        } | {var.name: SyntaxTree(ast=[definition]) for var, definition in unresolved.items()}
+
+    def resolve_partial(
+        self,
+        unresolvable: Optional[Set[str]] = None,
+        output_filter: Optional[Set[str]] = None,
+    ) -> "Script":
+        """
+        Updates the internal script to resolve as much as possible.
+        """
+        out = self._resolve_partial(unresolvable=unresolvable, output_filter=output_filter)
+        for var_name, definition in out.items():
+            self._variables[var_name] = definition
+
+        return self
+
+    def resolve_partial_once(
+        self, variable_definitions: Dict[str, SyntaxTree], unresolvable: Optional[Set[str]] = None
+    ) -> Dict[str, SyntaxTree]:
+        """
+        Partially resolves the input variable definitions as much as possible.
+        """
+        try:
+            self.add_parsed(variable_definitions)
+            return self._resolve_partial(
+                unresolvable=unresolvable,
+                output_filter=set(list(variable_definitions.keys())),
+            )
+        finally:
+            for name in variable_definitions.keys():
+                self._variables.pop(name, None)

{ytdl_sub-2026.1.30 → ytdl_sub-2026.2.2.post1}/src/ytdl_sub/script/types/function.py

@@ -371,13 +371,6 @@ class BuiltInFunction(Function, BuiltInFunctionType):
         If the conditional partially resolvable enough to warrant evaluation,
         perform it here.
         """
-        if self.is_subset_of(
-            variables=resolved_variables, custom_function_definitions=custom_functions
-        ):
-            return self.resolve(
-                resolved_variables=resolved_variables,
-                custom_functions=custom_functions,
-            )
 
         if self.name == "if":
             maybe_resolvable_arg, is_resolvable = VariableDependency.try_partial_resolve(

{ytdl_sub-2026.1.30 → ytdl_sub-2026.2.2.post1}/src/ytdl_sub/script/types/syntax_tree.py

@@ -55,6 +55,10 @@ class SyntaxTree(VariableDependency):
             custom_functions=custom_functions,
         )
 
+        # If no arguments, must be empty string
+        if len(maybe_resolvable_values) == 0:
+            return String(value="")
+
         # Mimic the above resolve behavior
         if len(maybe_resolvable_values) > 1:
             return BuiltInFunction(name="concat", args=maybe_resolvable_values)

{ytdl_sub-2026.1.30 → ytdl_sub-2026.2.2.post1}/src/ytdl_sub/script/types/variable_dependency.py

@@ -279,8 +279,11 @@ class VariableDependency(ABC):
                 if not isinstance(maybe_resolvable_args[-1], Resolvable):
                     is_resolvable = False
             elif isinstance(arg, Variable):
-                if arg not in resolved_variables:
+                if arg in resolved_variables:
+                    maybe_resolvable_args[-1] = resolved_variables[arg]
+                else:
                     is_resolvable = False
+                    # Could be un unresolvable
                     if arg in unresolved_variables:
                         maybe_resolvable_args[-1] = unresolved_variables[arg]
 

{ytdl_sub-2026.1.30 → ytdl_sub-2026.2.2.post1}/src/ytdl_sub/subscriptions/base_subscription.py

@@ -8,6 +8,7 @@ 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 ResolutionLevel
 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
@@ -79,7 +80,7 @@ class BaseSubscription(ABC):
         )
 
         # Validate after adding the subscription name
-        self._validated_dict = VariableValidation(
+        _ = VariableValidation(
             overrides=self.overrides,
             downloader_options=self.downloader_options,
             output_options=self.output_options,
@@ -254,12 +255,22 @@ class BaseSubscription(ABC):
         -------
         Subscription in yaml format
         """
-        return self._preset_options.yaml
+        return self._preset_options.yaml(subscription_only=False)
 
-    def resolved_yaml(self) -> str:
+    def resolved_yaml(self, resolution_level: int = ResolutionLevel.RESOLVE) -> str:
         """
         Returns
         -------
         Human-readable, condensed YAML definition of the subscription.
         """
-        return dump_yaml(self._validated_dict)
+        if resolution_level == ResolutionLevel.ORIGINAL:
+            return self._preset_options.yaml(subscription_only=True)
+
+        out = VariableValidation(
+            overrides=self.overrides,
+            downloader_options=self.downloader_options,
+            output_options=self.output_options,
+            plugins=self.plugins,
+            resolution_level=resolution_level,
+        ).ensure_proper_usage(partial_resolve_formatters=True)
+        return dump_yaml(out)