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

ytdl_sub/__init__.py

@@ -1 +1 @@
-__pypi_version__ = "2025.11.08";__local_version__ = "2025.11.08+2c33c3b"
+__pypi_version__ = "2025.12.31";__local_version__ = "2025.12.31+1abe2a4"

ytdl_sub/config/config_validator.py

@@ -12,6 +12,8 @@ from ytdl_sub.config.defaults import DEFAULT_FFPROBE_PATH
 from ytdl_sub.config.defaults import DEFAULT_LOCK_DIRECTORY
 from ytdl_sub.config.defaults import MAX_FILE_NAME_BYTES
 from ytdl_sub.prebuilt_presets import PREBUILT_PRESETS
+from ytdl_sub.utils.exceptions import SubscriptionPermissionError
+from ytdl_sub.utils.file_handler import FileHandler
 from ytdl_sub.validators.file_path_validators import FFmpegFileValidator
 from ytdl_sub.validators.file_path_validators import FFprobeFileValidator
 from ytdl_sub.validators.strict_dict_validator import StrictDictValidator
@@ -147,6 +149,12 @@ class ConfigOptions(StrictDictValidator):
             key="file_name_max_bytes", validator=IntValidator, default=MAX_FILE_NAME_BYTES
         )
 
+        if not FileHandler.is_path_writable(self.working_directory):
+            raise SubscriptionPermissionError(
+                "ytdl-sub does not have permissions to the working directory: "
+                f"{self.working_directory}"
+            )
+
     @property
     def working_directory(self) -> str:
         """

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
                 }
             )
@@ -158,10 +184,15 @@ class Overrides(UnstructuredDictFormatterValidator, Scriptable):
             script = entry.script
             unresolvable = entry.unresolvable
 
+        # Update the script internally so long as we are not supplying overrides
+        # that could alter the script with one-off state
+        update = function_overrides is None
+
         try:
             return script.resolve_once(
                 dict({"tmp_var": formatter.format_string}, **(function_overrides or {})),
                 unresolvable=unresolvable,
+                update=update,
             )["tmp_var"]
         except ScriptVariableNotResolved as exc:
             raise StringFormattingException(

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/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/config/preset_options.py

@@ -8,6 +8,9 @@ from ytdl_sub.config.overrides import Overrides
 from ytdl_sub.config.plugin.plugin_operation import PluginOperation
 from ytdl_sub.config.validators.options import OptionsDictValidator
 from ytdl_sub.entries.script.variable_definitions import VARIABLES as v
+from ytdl_sub.utils.exceptions import SubscriptionPermissionError
+from ytdl_sub.utils.exceptions import ValidationException
+from ytdl_sub.utils.file_handler import FileHandler
 from ytdl_sub.validators.file_path_validators import OverridesStringFormatterFilePathValidator
 from ytdl_sub.validators.file_path_validators import StringFormatterFileNameValidator
 from ytdl_sub.validators.string_datetime import StringDatetimeValidator
@@ -57,12 +60,24 @@ class YTDLOptions(UnstructuredOverridesDictFormatterValidator):
     def to_native_dict(self, overrides: Overrides) -> Dict:
         """
         Materializes the entire ytdl-options dict from OverrideStringFormatters into
-        native python
+        native python.
         """
-        return {
+        out = {
             key: overrides.apply_overrides_formatter_to_native(val)
             for key, val in self.dict.items()
         }
+        if "cookiefile" in out:
+            if not FileHandler.is_file_existent(out["cookiefile"]):
+                raise ValidationException(
+                    f"Specified cookiefile {out['cookiefile']} but it does not exist as a file."
+                )
+
+            if not FileHandler.is_file_readable(out["cookiefile"]):
+                raise SubscriptionPermissionError(
+                    f"Cannot read cookiefile {out['cookiefile']} due to permissions issue."
+                )
+
+        return out
 
 
 # Disable for proper docstring formatting
@@ -107,6 +122,7 @@ class OutputOptions(OptionsDictValidator):
         "keep_max_files",
         "download_archive_standardized_date",
         "keep_files_date_eval",
+        "preserve_mtime",
     }
 
     @classmethod
@@ -170,6 +186,10 @@ class OutputOptions(OptionsDictValidator):
             default=f"{{{v.upload_date_standardized.variable_name}}}",
         )
 
+        self._preserve_mtime = self._validate_key_if_present(
+            key="preserve_mtime", validator=BoolValidator, default=False
+        )
+
         if (
             self._keep_files_before or self._keep_files_after or self._keep_max_files
         ) and not self.maintain_download_archive:
@@ -309,6 +329,17 @@ class OutputOptions(OptionsDictValidator):
         """
         return self._keep_max_files
 
+    @property
+    def preserve_mtime(self) -> bool:
+        """
+        :expected type: Optional[Boolean]
+        :description:
+          Preserve the video's original upload time as the file modification time.
+          When True, sets the file's mtime to match the video's upload_date from
+          yt-dlp metadata. Defaults to False.
+        """
+        return self._preserve_mtime.value
+
     def added_variables(self, unresolved_variables: Set[str]) -> Dict[PluginOperation, Set[str]]:
         return {
             # PluginOperation.MODIFY_ENTRY_METADATA: {

ytdl_sub/config/validators/variable_validation.py

@@ -1,10 +1,4 @@
-import copy
 from typing import Dict
-from typing import Iterable
-from typing import List
-from typing import Optional
-from typing import Set
-from typing import Tuple
 
 from ytdl_sub.config.overrides import Overrides
 from ytdl_sub.config.plugin.plugin_mapping import PluginMapping
@@ -13,155 +7,27 @@ 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.variables.override_variables import REQUIRED_OVERRIDE_VARIABLE_NAMES
-from ytdl_sub.script.script import Script
-from ytdl_sub.script.script import _is_function
-from ytdl_sub.utils.scriptable import BASE_SCRIPT
-from ytdl_sub.validators.string_formatter_validators import to_variable_dependency_format_string
 from ytdl_sub.validators.string_formatter_validators import validate_formatters
 
-# Entry variables to mock during validation
-_DUMMY_ENTRY_VARIABLES: Dict[str, str] = {
-    name: to_variable_dependency_format_string(
-        # pylint: disable=protected-access
-        script=BASE_SCRIPT,
-        parsed_format_string=BASE_SCRIPT._variables[name],
-        # pylint: enable=protected-access
-    )
-    for name in BASE_SCRIPT.variable_names
-}
-
-
-def _add_dummy_variables(variables: Iterable[str]) -> Dict[str, str]:
-    dummy_variables: Dict[str, str] = {}
-    for var in variables:
-        dummy_variables[var] = ""
-        dummy_variables[f"{var}_sanitized"] = ""
-
-    return dummy_variables
-
-
-def _add_dummy_overrides(overrides: Overrides) -> Dict[str, str]:
-    # Have the dummy override variable contain all variable deps that it uses in the string
-    dummy_overrides: Dict[str, str] = {}
-    for override_name in _override_variables(overrides):
-        if _is_function(override_name):
-            continue
-
-        # pylint: disable=protected-access
-        dummy_overrides[override_name] = to_variable_dependency_format_string(
-            script=overrides.script, parsed_format_string=overrides.script._variables[override_name]
-        )
-        # pylint: enable=protected-access
-    return dummy_overrides
-
-
-def _get_added_and_modified_variables(
-    plugins: PresetPlugins, downloader_options: MultiUrlValidator, output_options: OutputOptions
-) -> Iterable[Tuple[OptionsValidator, Set[str], Set[str]]]:
-    """
-    Iterates and returns the plugin options, added variables, modified variables
-    """
-    options: List[OptionsValidator] = plugins.plugin_options
-    options.append(downloader_options)
-    options.append(output_options)
-
-    for plugin_options in 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 _override_variables(overrides: Overrides) -> Set[str]:
-    return set(list(overrides.initial_variables().keys()))
-
 
 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: Optional[Script] = None
-        self.resolved_variables: Set[str] = set()
-        self.unresolved_variables: Set[str] = set()
-
-    def initialize_preset_overrides(self, overrides: Overrides) -> "VariableValidation":
-        """
-        Do some gymnastics to initialize the Overrides script.
-        """
-        override_variables = set(list(overrides.initial_variables().keys()))
-
-        # Set resolved variables as all entry + override variables
-        # at this point to generate every possible added/modified variable
-        self.resolved_variables = set(_DUMMY_ENTRY_VARIABLES.keys()) | override_variables
-        plugin_variables: Set[str] = set()
-
-        for (
-            plugin_options,
-            added_variables,
-            modified_variables,
-        ) in _get_added_and_modified_variables(
-            plugins=self.plugins,
-            downloader_options=self.downloader_options,
-            output_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
-            self.unresolved_variables |= added_variables | modified_variables
-            plugin_variables |= added_variables | modified_variables
-
-        # Then update resolved variables to reflect that
-        self.resolved_variables -= self.unresolved_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
-        overrides = overrides.initialize_script(unresolved_variables=self.unresolved_variables)
-
-        # copy the script and mock entry variables
-        self.script = copy.deepcopy(overrides.script)
-        self.script.add(
-            variables=_add_dummy_overrides(overrides=overrides)
-            | _add_dummy_variables(variables=plugin_variables)
-            | _DUMMY_ENTRY_VARIABLES
+        self.script = self.overrides.script
+        self.unresolved_variables = self.plugins.get_all_variables(
+            additional_options=[self.output_options, self.downloader_options]
         )
 
-        return self
-
-    def _update_script(self) -> None:
-        _ = self.script.resolve(unresolvable=self.unresolved_variables, update=True)
-
-    def _add_subscription_override_variables(self) -> None:
-        """
-        Add dummy subscription variables for script validation
-        """
-        self.resolved_variables |= REQUIRED_OVERRIDE_VARIABLE_NAMES
-
     def _add_variables(self, plugin_op: PluginOperation, options: OptionsValidator) -> None:
         """
         Add dummy variables for script validation
@@ -171,19 +37,17 @@ class VariableValidation:
         ).get(plugin_op, set())
         modified_variables = options.modified_variables().get(plugin_op, set())
 
-        resolved_variables = added_variables | modified_variables
+        self.unresolved_variables -= added_variables | modified_variables
 
-        self.resolved_variables |= resolved_variables
-        self.unresolved_variables -= resolved_variables
-
-    def ensure_proper_usage(self) -> None:
+    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)
-        self._add_subscription_override_variables()
 
         # Always add output options first
         self._add_variables(PluginOperation.MODIFY_ENTRY_METADATA, options=self.output_options)
@@ -200,16 +64,28 @@ class VariableValidation:
             self._add_variables(PluginOperation.MODIFY_ENTRY, options=plugin_options)
 
             # Validate that any formatter in the plugin options can resolve
-            validate_formatters(
+            resolved_subscription |= validate_formatters(
                 script=self.script,
                 unresolved_variables=self.unresolved_variables,
                 validator=plugin_options,
             )
 
-        validate_formatters(
+        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/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/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/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