ytdl-sub 2024.9.30__py3-none-any.whl → 2026.1.24__py3-none-any.whl

ytdl_sub/__init__.py

@@ -1 +1 @@
-__pypi_version__ = "2024.09.30";__local_version__ = "2024.09.30+f2ec26d"
+__pypi_version__ = "2026.01.24";__local_version__ = "2026.01.24+60cdbad"

ytdl_sub/cli/entrypoint.py

@@ -12,6 +12,7 @@ from yt_dlp.utils import sanitize_filename
 from ytdl_sub.cli.output_summary import output_summary
 from ytdl_sub.cli.output_transaction_log import _maybe_validate_transaction_log_file
 from ytdl_sub.cli.output_transaction_log import output_transaction_log
+from ytdl_sub.cli.parsers.cli_to_sub import print_cli_to_sub
 from ytdl_sub.cli.parsers.dl import DownloadArgsParser
 from ytdl_sub.cli.parsers.main import DEFAULT_CONFIG_FILE_NAME
 from ytdl_sub.cli.parsers.main import parser
@@ -161,7 +162,7 @@ def _download_subscription_from_cli(
         extra_arguments=extra_args, config_options=config.config_options
     )
     subscription_args_dict = dl_args_parser.to_subscription_dict()
-    subscription_name = f"cli-dl-{dl_args_parser.get_args_hash()}"
+    subscription_name = dl_args_parser.get_dl_subscription_name()
 
     subscription = Subscription.from_dict(
         config=config, preset_name=subscription_name, preset_dict=subscription_args_dict
@@ -206,6 +207,10 @@ def main() -> List[Subscription]:
 
     args, extra_args = parser.parse_known_args()
 
+    if args.subparser == "cli-to-sub":
+        print_cli_to_sub(args=extra_args)
+        return []
+
     # Load the config
     if args.config:
         config = ConfigFile.from_file_path(args.config)
@@ -263,7 +268,7 @@ def main() -> List[Subscription]:
                 _view_url_from_cli(config=config, url=args.url, split_chapters=args.split_chapters)
             )
         else:
-            raise ValidationException("Must provide one of the commands: sub, dl, view")
+            raise ValidationException("Must provide one of the commands: sub, dl, view, cli-to-sub")
 
     if not args.suppress_transaction_log:
         output_transaction_log(
@@ -271,6 +276,6 @@ def main() -> List[Subscription]:
             transaction_log_file_path=args.transaction_log,
         )
 
-    output_summary(subscriptions)
+    output_summary(subscriptions, suppress_colors=args.suppress_colors)
 
     return subscriptions

ytdl_sub/cli/output_summary.py

@@ -8,16 +8,16 @@ from ytdl_sub.utils.logger import Logger
 logger = Logger.get()
 
 
-def _green(value: str) -> str:
-    return Fore.GREEN + value + Fore.RESET
+def _green(value: str, suppress_colors: bool = False) -> str:
+    return value if suppress_colors else Fore.GREEN + value + Fore.RESET
 
 
-def _red(value: str) -> str:
-    return Fore.RED + value + Fore.RESET
+def _red(value: str, suppress_colors: bool = False) -> str:
+    return value if suppress_colors else Fore.RED + value + Fore.RESET
 
 
-def _no_color(value: str) -> str:
-    return Fore.RESET + value + Fore.RESET
+def _no_color(value: str, suppress_colors: bool = False) -> str:
+    return value if suppress_colors else Fore.RESET + value + Fore.RESET
 
 
 def _str_int(value: int) -> str:
@@ -26,21 +26,23 @@ def _str_int(value: int) -> str:
     return str(value)
 
 
-def _color_int(value: int) -> str:
+def _color_int(value: int, suppress_colors: bool = False) -> str:
     str_int = _str_int(value)
     if value > 0:
-        return _green(str_int)
+        return _green(str_int, suppress_colors)
     if value < 0:
-        return _red(str_int)
-    return _no_color(str_int)
+        return _red(str_int, suppress_colors)
+    return _no_color(str_int, suppress_colors)
 
 
-def output_summary(subscriptions: List[Subscription]) -> None:
+def output_summary(subscriptions: List[Subscription], suppress_colors: bool) -> None:
     """
     Parameters
     ----------
     subscriptions
         Processed subscriptions
+    suppress_colors
+        Whether to have color or not
 
     Returns
     -------
@@ -65,21 +67,21 @@ def output_summary(subscriptions: List[Subscription]) -> None:
 
     # Initialize widths to 0
     width_sub_name: int = max(len(sub.name) for sub in subscriptions) + 4  # aesthetics
-    width_num_entries_added: int = len(_color_int(total_added))
-    width_num_entries_modified: int = len(_color_int(total_modified))
-    width_num_entries_removed: int = len(_color_int(total_removed))
+    width_num_entries_added: int = len(_color_int(total_added, suppress_colors))
+    width_num_entries_modified: int = len(_color_int(total_modified, suppress_colors))
+    width_num_entries_removed: int = len(_color_int(total_removed, suppress_colors))
     width_num_entries: int = len(str(total_entries)) + 4  # aesthetics
 
     # Build the summary
     for subscription in subscriptions:
-        num_entries_added = _color_int(subscription.num_entries_added)
-        num_entries_modified = _color_int(subscription.num_entries_modified)
-        num_entries_removed = _color_int(subscription.num_entries_removed * -1)
+        num_entries_added = _color_int(subscription.num_entries_added, suppress_colors)
+        num_entries_modified = _color_int(subscription.num_entries_modified, suppress_colors)
+        num_entries_removed = _color_int(subscription.num_entries_removed * -1, suppress_colors)
         num_entries = str(subscription.num_entries)
         status = (
-            _red(subscription.exception.__class__.__name__)
+            _red(subscription.exception.__class__.__name__, suppress_colors)
             if subscription.exception
-            else _green("✔")
+            else _green("✔", suppress_colors)
         )
 
         summary.append(
@@ -92,14 +94,16 @@ def output_summary(subscriptions: List[Subscription]) -> None:
         )
 
     total_errors_str = (
-        _green("Success") if total_errors == 0 else _red(f"Error{'s' if total_errors > 1 else ''}")
+        _green("Success", suppress_colors)
+        if total_errors == 0
+        else _red(f"Error{'s' if total_errors > 1 else ''}", suppress_colors)
     )
 
     summary.append(
         f"{total_subs_str:<{width_sub_name}} "
-        f"{_color_int(total_added):>{width_num_entries_added}} "
-        f"{_color_int(total_modified):>{width_num_entries_modified}} "
-        f"{_color_int(total_removed):>{width_num_entries_removed}} "
+        f"{_color_int(total_added, suppress_colors):>{width_num_entries_added}} "
+        f"{_color_int(total_modified, suppress_colors):>{width_num_entries_modified}} "
+        f"{_color_int(total_removed * -1, suppress_colors):>{width_num_entries_removed}} "
         f"{total_entries:>{width_num_entries}} "
         f"{total_errors_str}"
     )

ytdl_sub/cli/parsers/cli_to_sub.py

@@ -0,0 +1,64 @@
+from typing import List
+
+import yt_dlp
+import yt_dlp.options
+
+from ytdl_sub.utils.logger import Logger
+from ytdl_sub.utils.yaml import dump_yaml
+
+logger = Logger.get()
+
+# pylint: disable=missing-function-docstring
+
+##############################################################
+# --- BEGIN ----
+# Copy of https://github.com/yt-dlp/yt-dlp/blob/master/devscripts/cli_to_api.py
+
+create_parser = yt_dlp.options.create_parser
+
+
+def parse_patched_options(opts):
+
+    patched_parser = create_parser()
+    patched_parser.defaults.update(
+        {
+            "ignoreerrors": False,
+            "retries": 0,
+            "fragment_retries": 0,
+            "extract_flat": False,
+            "concat_playlist": "never",
+            "update_self": False,
+        }
+    )
+    yt_dlp.options.create_parser = lambda: patched_parser
+    try:
+        return yt_dlp.parse_options(opts)
+    finally:
+        yt_dlp.options.create_parser = create_parser
+
+
+default_opts = parse_patched_options([]).ydl_opts
+
+
+def cli_to_api(opts, cli_defaults=False):
+    opts = (yt_dlp.parse_options if cli_defaults else parse_patched_options)(opts).ydl_opts
+
+    diff = {k: v for k, v in opts.items() if default_opts[k] != v}
+    if "postprocessors" in diff:
+        diff["postprocessors"] = [
+            pp for pp in diff["postprocessors"] if pp not in default_opts["postprocessors"]
+        ]
+    return diff
+
+
+# --- END ----
+##############################################################
+
+
+def print_cli_to_sub(args: List[str]) -> None:
+    api_args = cli_to_api(args)
+    if not api_args:
+        logger.info("Does not resolve to any yt-dlp args")
+        return
+
+    print(dump_yaml({"ytdl_options": api_args}))

ytdl_sub/cli/parsers/dl.py

@@ -242,12 +242,13 @@ class DownloadArgsParser:
 
         return subscription_dict
 
-    def get_args_hash(self) -> str:
+    def get_dl_subscription_name(self) -> str:
         """
-        :return: Hash of the arguments provided
+        Returns a deterministic name based on input args
         """
-        hash_string = str(sorted(self._unknown_arguments))
-        return hashlib.sha256(hash_string.encode()).hexdigest()[-8:]
+        to_hash = str(sorted(self._unknown_arguments))
+        hash_str = hashlib.sha256(to_hash.encode()).hexdigest()[-8:]
+        return f"cli-dl-{hash_str}"
 
     @classmethod
     def from_dl_override(cls, override: str, config: ConfigFile) -> "DownloadArgsParser":

ytdl_sub/cli/parsers/main.py

@@ -44,6 +44,7 @@ class MainArguments:
         short="-m",
         long="--match",
     )
+    SUPPRESS_COLORS = CLIArgument(short="-nc", long="--suppress-colors")
 
     @classmethod
     def all(cls) -> List[CLIArgument]:
@@ -59,6 +60,7 @@ class MainArguments:
             cls.TRANSACTION_LOG,
             cls.SUPPRESS_TRANSACTION_LOG,
             cls.MATCH,
+            cls.SUPPRESS_COLORS,
         ]
 
     @classmethod
@@ -109,8 +111,8 @@ def _add_shared_arguments(arg_parser: argparse.ArgumentParser, suppress_defaults
         MainArguments.LOG_LEVEL.long,
         metavar="|".join(LoggerLevels.names()),
         type=str,
-        help="level of logs to print to console, defaults to info",
-        default=argparse.SUPPRESS if suppress_defaults else LoggerLevels.INFO.name,
+        help="level of logs to print to console, defaults to verbose",
+        default=argparse.SUPPRESS if suppress_defaults else LoggerLevels.VERBOSE.name,
         choices=LoggerLevels.names(),
         dest="ytdl_sub_log_level",
     )
@@ -129,6 +131,13 @@ def _add_shared_arguments(arg_parser: argparse.ArgumentParser, suppress_defaults
         help="do not output transaction logs to console or file",
         default=argparse.SUPPRESS if suppress_defaults else False,
     )
+    arg_parser.add_argument(
+        MainArguments.SUPPRESS_COLORS.short,
+        MainArguments.SUPPRESS_COLORS.long,
+        action="store_true",
+        help="do not use colors in ytdl-sub output",
+        default=argparse.SUPPRESS if suppress_defaults else False,
+    )
     arg_parser.add_argument(
         MainArguments.MATCH.short,
         MainArguments.MATCH.long,
@@ -212,3 +221,7 @@ view_parser.add_argument(
     help="View source variables after splitting by chapters",
 )
 view_parser.add_argument("url", help="URL to view source variables for")
+
+###################################################################################################
+# CLI-TO-SUB PARSER
+cli_to_sub_parser = subparsers.add_parser("cli-to-sub")

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
@@ -67,7 +69,8 @@ class PersistLogsValidator(StrictDictValidator):
     @property
     def logs_directory(self) -> str:
         """
-        Required. The directory to store the logs in.
+        Write log files to this directory with names like
+        ``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``. (required)
         """
         return self._logs_directory.value
 
@@ -92,7 +95,10 @@ class PersistLogsValidator(StrictDictValidator):
     @property
     def keep_successful_logs(self) -> bool:
         """
-        Optional. Whether to store logs when downloading is successful. Defaults to True.
+        If the ``persist_logs:`` key is in the configuration, then ``ytdl-sub`` *always*
+        writes log files for the subscription both for successful downloads and when it
+        encounters an error while downloading. When this key is ``False``, only write
+        log files for errors. (default ``True``)
         """
         return self._keep_successful_logs.value
 
@@ -143,11 +149,17 @@ 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:
         """
         The directory to temporarily store downloaded files before moving them into their final
-        directory. Defaults to .ytdl-sub-working-directory
+        directory. (default ``./.ytdl-sub-working-directory``)
         """
         # Expands tildas to actual paths, use native os sep
         return os.path.expanduser(self._working_directory.value.replace(posixpath.sep, os.sep))
@@ -155,7 +167,7 @@ class ConfigOptions(StrictDictValidator):
     @property
     def umask(self) -> Optional[str]:
         """
-        Umask (octal format) to apply to every created file. Defaults to "022".
+        Umask in octal format to apply to every created file. (default ``022``)
         """
         return self._umask.value
 
@@ -214,24 +226,25 @@ class ConfigOptions(StrictDictValidator):
     def lock_directory(self) -> str:
         """
         The directory to temporarily store file locks, which prevents multiple instances
-        of ``ytdl-sub`` from running. Note that file locks do not work on network-mounted
-        directories. Ensure that this directory resides on the host machine. Defaults to ``/tmp``.
+        of ``ytdl-sub`` from running. Note that file locks do not work on
+        network-mounted directories. Ensure that this directory resides on the host
+        machine. (default ``/tmp``)
         """
         return self._lock_directory.value
 
     @property
     def ffmpeg_path(self) -> str:
         """
-        Path to ffmpeg executable. Defaults to ``/usr/bin/ffmpeg`` for Linux, and
-        ``ffmpeg.exe`` for Windows (in the same directory as ytdl-sub).
+        Path to ffmpeg executable. (default ``/usr/bin/ffmpeg`` for Linux,
+        ``./ffmpeg.exe`` in the same directory as ytdl-sub for Windows)
         """
         return self._ffmpeg_path.value
 
     @property
     def ffprobe_path(self) -> str:
         """
-        Path to ffprobe executable. Defaults to ``/usr/bin/ffprobe`` for Linux, and
-        ``ffprobe.exe`` for Windows (in the same directory as ytdl-sub).
+        Path to ffprobe executable. (default ``/usr/bin/ffprobe`` for Linux,
+        ``./ffprobe.exe`` in the same directory as ytdl-sub for Windows)
         """
         return self._ffprobe_path.value
 

ytdl_sub/config/defaults.py

@@ -2,6 +2,8 @@ import os
 
 from ytdl_sub.utils.system import IS_WINDOWS
 
+# pylint: disable=invalid-name
+
 
 def _existing_path(*paths: str) -> str:
     """
@@ -22,7 +24,7 @@ if IS_WINDOWS:
 
     MAX_FILE_NAME_BYTES = 255
 else:
-    DEFAULT_LOCK_DIRECTORY = "/tmp"
+    DEFAULT_LOCK_DIRECTORY = ".ytdl-sub-lock"
     DEFAULT_FFMPEG_PATH = os.getenv(
         "YTDL_SUB_FFMPEG_PATH", _existing_path("/usr/bin/ffmpeg", "/usr/local/bin/ffmpeg")
     )

ytdl_sub/config/overrides.py

@@ -1,9 +1,10 @@
 from typing import Any
 from typing import Dict
+from typing import Iterable
 from typing import Optional
 from typing import Set
-
-import mergedeep
+from typing import Type
+from typing import TypeVar
 
 from ytdl_sub.entries.entry import Entry
 from ytdl_sub.entries.script.variable_definitions import VARIABLES
@@ -11,6 +12,10 @@ from ytdl_sub.entries.variables.override_variables import REQUIRED_OVERRIDE_VARI
 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
@@ -20,6 +25,8 @@ from ytdl_sub.utils.scriptable import Scriptable
 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):
     """
@@ -86,6 +93,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.
@@ -113,29 +138,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
                 }
             )
@@ -144,12 +175,43 @@ class Overrides(UnstructuredDictFormatterValidator, Scriptable):
         self.update_script()
         return self
 
+    def _apply_to_resolvable(
+        self,
+        formatter: StringFormatterValidator,
+        entry: Optional[Entry],
+        function_overrides: Optional[Dict[str, str]],
+    ) -> Resolvable:
+        script: Script = self.script
+        unresolvable: Set[str] = self.unresolvable
+        if entry:
+            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(
+                "Tried to resolve the following script, but could not due to unresolved "
+                f"variables:\n {formatter.format_string}\n"
+                "This is most likely due to circular dependencies in variables. "
+                "If you think otherwise, please file a bug on GitHub and post your config. Thanks!"
+            ) from exc
+
     def apply_formatter(
         self,
         formatter: StringFormatterValidator,
         entry: Optional[Entry] = None,
-        function_overrides: Dict[str, str] = None,
-    ) -> str:
+        function_overrides: Optional[Dict[str, str]] = None,
+        expected_type: Type[ExpectedT] = str,
+    ) -> ExpectedT:
         """
         Parameters
         ----------
@@ -159,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
         -------
@@ -169,25 +233,15 @@ class Overrides(UnstructuredDictFormatterValidator, Scriptable):
         StringFormattingException
             If the formatter that is trying to be resolved cannot
         """
-        script: Script = self.script
-        unresolvable: Set[str] = self.unresolvable
-        if entry:
-            script = entry.script
-            unresolvable = entry.unresolvable
+        out = formatter.post_process(
+            self._apply_to_resolvable(
+                formatter=formatter, entry=entry, function_overrides=function_overrides
+            ).native
+        )
 
-        try:
-            return formatter.post_process(
-                str(
-                    script.resolve_once(
-                        dict({"tmp_var": formatter.format_string}, **(function_overrides or {})),
-                        unresolvable=unresolvable,
-                    )["tmp_var"]
-                )
-            )
-        except ScriptVariableNotResolved as exc:
+        if not isinstance(out, expected_type):
             raise StringFormattingException(
-                "Tried to resolve the following script, but could not due to unresolved "
-                f"variables:\n {formatter.format_string}\n"
-                "This is most likely due to circular dependencies in variables. "
-                "If you think otherwise, please file a bug on GitHub and post your config. Thanks!"
-            ) from exc
+                f"Expected type {expected_type.__name__}, but received '{out.__class__.__name__}'"
+            )
+
+        return out

ytdl_sub/config/plugin/plugin.py

@@ -13,7 +13,6 @@ from ytdl_sub.config.validators.options import OptionsValidatorT
 from ytdl_sub.config.validators.options import ToggleableOptionsDictValidator
 from ytdl_sub.entries.entry import Entry
 from ytdl_sub.utils.file_handler import FileMetadata
-from ytdl_sub.utils.script import ScriptUtils
 from ytdl_sub.ytdl_additions.enhanced_download_archive import DownloadArchiver
 from ytdl_sub.ytdl_additions.enhanced_download_archive import EnhancedDownloadArchive
 
@@ -49,9 +48,7 @@ class Plugin(BasePlugin[OptionsValidatorT], Generic[OptionsValidatorT], ABC):
         Returns True if enabled, False if disabled.
         """
         if isinstance(self.plugin_options, ToggleableOptionsDictValidator):
-            return ScriptUtils.bool_formatter_output(
-                self.overrides.apply_formatter(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]]:
@@ -69,6 +66,13 @@ class Plugin(BasePlugin[OptionsValidatorT], Generic[OptionsValidatorT], ABC):
         ytdl options to enable/disable when downloading entries for this specific plugin
         """
 
+    def initialize_subscription(self) -> bool:
+        """
+        Before any downloading begins, perform initialization before the subscription runs.
+        Returns true if this subscription should run, false otherwise.
+        """
+        return True
+
     def modify_entry_metadata(self, entry: Entry) -> Optional[Entry]:
         """
         After entry metadata has been gathered, perform preprocessing on the metadata
@@ -115,6 +119,17 @@ class Plugin(BasePlugin[OptionsValidatorT], Generic[OptionsValidatorT], ABC):
         """
         return None
 
+    def post_completion_entry(self, file_metadata: FileMetadata) -> None:
+        """
+        After the entry file is moved to its final location, run this hook.
+
+        Parameters
+        ----------
+        file_metadata
+            Metadata about the completed entry's file download
+        """
+        return None
+
     def post_process_subscription(self):
         """
         After all downloaded files have been post-processed, apply a subscription-wide post process