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

ytdl_sub/__init__.py

@@ -1 +1 @@
-__pypi_version__ = "2025.08.28";__local_version__ = "2025.08.28+283ccc8"
+__pypi_version__ = "2025.11.08";__local_version__ = "2025.11.08+2c33c3b"

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
@@ -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(

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/main.py

@@ -221,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/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/plugin/plugin.py

@@ -119,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

ytdl_sub/config/plugin/plugin_mapping.py

@@ -92,6 +92,12 @@ class PluginMapping:
         EmbedThumbnailPlugin,
     ]
 
+    _ORDER_POST_COMPLETION: List[Type[Plugin]] = [
+        # Throttle protection should always be last
+        # to not sleep over other logic
+        ThrottleProtectionPlugin
+    ]
+
     @classmethod
     def _order_by(
         cls, plugin_types: List[Type[Plugin]], operation: PluginOperation
@@ -102,6 +108,8 @@ class PluginMapping:
             ordering = cls._ORDER_MODIFY_ENTRY
         elif operation == PluginOperation.POST_PROCESS:
             ordering = cls._ORDER_POST_PROCESS
+        elif operation == PluginOperation.POST_COMPLETION:
+            ordering = cls._ORDER_POST_COMPLETION
         else:
             raise ValueError("PluginOperation does not support ordering")
 

ytdl_sub/config/plugin/plugin_operation.py

@@ -6,3 +6,4 @@ class PluginOperation(Enum):
     MODIFY_ENTRY_METADATA = 0
     MODIFY_ENTRY = 1
     POST_PROCESS = 2
+    POST_COMPLETION = 3

ytdl_sub/downloaders/url/downloader.py

@@ -257,6 +257,16 @@ class MultiUrlDownloader(SourcePlugin[MultiUrlValidator]):
             .to_dict()
         )
 
+    def webpage_url(self, entry: Entry) -> str:
+        """
+        Returns
+        -------
+        The webpage_url to use for the actual download
+        """
+        url_idx = entry.get(v.ytdl_sub_input_url_index, int)
+        webpage_url_formatter = self.plugin_options.urls.list[url_idx].webpage_url
+        return self.overrides.apply_formatter(webpage_url_formatter, entry=entry)
+
     def metadata_ytdl_options(self, ytdl_option_overrides: Dict) -> Dict:
         """
         Returns
@@ -358,7 +368,7 @@ class MultiUrlDownloader(SourcePlugin[MultiUrlValidator]):
                 if (self.is_dry_run or not self.is_entry_thumbnails_enabled)
                 else entry.is_thumbnail_downloaded_via_ytdlp
             ),
-            url=entry.webpage_url,
+            url=self.webpage_url(entry=entry),
         )
         return Entry(
             download_entry_dict,
@@ -366,13 +376,13 @@ class MultiUrlDownloader(SourcePlugin[MultiUrlValidator]):
         )
 
     def _iterate_child_entries(
-        self, entries: List[Entry], download_reversed: bool
+        self, entries: List[Entry], validator: UrlValidator
     ) -> Iterator[Entry]:
         # Iterate a list of entries, and delete the entries after yielding
         entries_to_iter: List[Optional[Entry]] = entries
 
         indices = list(range(len(entries_to_iter)))
-        if download_reversed:
+        if self.overrides.evaluate_boolean(validator.download_reverse):
             indices = reversed(indices)
 
         for idx in indices:
@@ -394,17 +404,13 @@ class MultiUrlDownloader(SourcePlugin[MultiUrlValidator]):
             entries_to_iter[idx] = None
 
     def _iterate_parent_entry(
-        self, parent: EntryParent, download_reversed: bool
+        self, parent: EntryParent, validator: UrlValidator
     ) -> Iterator[Entry]:
-        yield from self._iterate_child_entries(
-            entries=parent.entry_children(), download_reversed=download_reversed
-        )
+        yield from self._iterate_child_entries(entries=parent.entry_children(), validator=validator)
 
         # Recursion the parent's parent entries
         for parent_child in reversed(parent.parent_children()):
-            yield from self._iterate_parent_entry(
-                parent=parent_child, download_reversed=download_reversed
-            )
+            yield from self._iterate_parent_entry(parent=parent_child, validator=validator)
 
     def _download_url_metadata(
         self, url: str, include_sibling_metadata: bool, ytdl_options_overrides: Dict
@@ -438,7 +444,7 @@ class MultiUrlDownloader(SourcePlugin[MultiUrlValidator]):
         self,
         parents: List[EntryParent],
         orphans: List[Entry],
-        download_reversed: bool,
+        validator: UrlValidator,
     ) -> Iterator[Entry]:
         """
         Downloads the leaf entries from EntryParent trees
@@ -446,19 +452,15 @@ class MultiUrlDownloader(SourcePlugin[MultiUrlValidator]):
         # Delete info json files afterwards so other collection URLs do not use them
         with self._separate_download_archives(clear_info_json_files=True):
             for parent in parents:
-                yield from self._iterate_parent_entry(
-                    parent=parent, download_reversed=download_reversed
-                )
+                yield from self._iterate_parent_entry(parent=parent, validator=validator)
 
-            yield from self._iterate_child_entries(
-                entries=orphans, download_reversed=download_reversed
-            )
+            yield from self._iterate_child_entries(entries=orphans, validator=validator)
 
     def _download_metadata(self, url: str, validator: UrlValidator) -> Iterable[Entry]:
         metadata_ytdl_options = self.metadata_ytdl_options(
             ytdl_option_overrides=validator.ytdl_options.to_native_dict(self.overrides)
         )
-        download_reversed = self.overrides.evaluate_boolean(validator.download_reverse)
+
         include_sibling_metadata = self.overrides.evaluate_boolean(
             validator.include_sibling_metadata
         )
@@ -469,16 +471,15 @@ class MultiUrlDownloader(SourcePlugin[MultiUrlValidator]):
             ytdl_options_overrides=metadata_ytdl_options,
         )
 
-        # TODO: Encapsulate this logic into its own class
         self._url_state = URLDownloadState(
-            entries_total=sum(parent.num_children() for parent in parents) + len(orphan_entries)
+            entries_total=sum(parent.num_children() for parent in parents) + len(orphan_entries),
         )
 
         download_logger.info("Beginning downloads for %s", url)
         yield from self._iterate_entries(
             parents=parents,
             orphans=orphan_entries,
-            download_reversed=download_reversed,
+            validator=validator,
         )
 
     def download_metadata(self) -> Iterable[Entry]:

ytdl_sub/downloaders/url/validators.py

@@ -52,6 +52,7 @@ class UrlValidator(StrictDictValidator):
         "download_reverse",
         "ytdl_options",
         "include_sibling_metadata",
+        "webpage_url",
     }
 
     @classmethod
@@ -89,6 +90,9 @@ class UrlValidator(StrictDictValidator):
             validator=OverridesBooleanFormatterValidator,
             default="False",
         )
+        self._webpage_url = self._validate_key(
+            key="webpage_url", validator=StringFormatterValidator, default="{webpage_url}"
+        )
 
     @property
     def url(self) -> OverridesStringFormatterValidator:
@@ -180,6 +184,19 @@ class UrlValidator(StrictDictValidator):
         """
         return self._include_sibling_metadata
 
+    @property
+    def webpage_url(self) -> StringFormatterValidator:
+        """
+        Optional. After ytdl-sub performs the metadata download, it will inspect each
+        entry's .info.json file and perform the actual download from yt-dlp using
+        `webpage_url <config_reference/scripting/entry_variables:webpage_url>`. This
+        can be overwritten by supplying parameter with a modification to ``webpage_url`` in the
+        form of an override variable.
+
+        Defaults to ``{webpage_url}``.
+        """
+        return self._webpage_url
+
 
 class UrlStringOrDictValidator(UrlValidator):
     """

ytdl_sub/entries/script/variable_definitions.py

@@ -1162,6 +1162,7 @@ class VariableDefinitions(
         """
         return {
             self.uid,
+            self.extractor,
             self.extractor_key,
             self.epoch,
             self.webpage_url,

ytdl_sub/plugins/subtitles.py

@@ -1,8 +1,10 @@
+import os
 from pathlib import Path
 from typing import Dict
 from typing import List
 from typing import Optional
 from typing import Set
+from typing import Tuple
 
 from ytdl_sub.config.plugin.plugin import Plugin
 from ytdl_sub.config.plugin.plugin_operation import PluginOperation
@@ -11,6 +13,7 @@ from ytdl_sub.downloaders.ytdl_options_builder import YTDLOptionsBuilder
 from ytdl_sub.entries.entry import Entry
 from ytdl_sub.entries.script.variable_definitions import VARIABLES
 from ytdl_sub.entries.script.variable_definitions import VariableDefinitions
+from ytdl_sub.script.utils.exceptions import UserThrownRuntimeError
 from ytdl_sub.utils.file_handler import FileHandler
 from ytdl_sub.utils.file_handler import FileMetadata
 from ytdl_sub.utils.logger import Logger
@@ -57,6 +60,7 @@ class SubtitleOptions(ToggleableOptionsDictValidator):
         "subtitles_type",
         "embed_subtitles",
         "languages",
+        "languages_required",
         "allow_auto_generated_subtitles",
     }
 
@@ -76,6 +80,9 @@ class SubtitleOptions(ToggleableOptionsDictValidator):
         self._languages = self._validate_key_if_present(
             key="languages", validator=StringListValidator, default=["en"]
         ).list
+        self._languages_required = self._validate_key_if_present(
+            key="languages_required", validator=StringListValidator, default=[]
+        ).list
         self._allow_auto_generated_subtitles = self._validate_key_if_present(
             key="allow_auto_generated_subtitles", validator=BoolValidator, default=False
         ).value
@@ -121,6 +128,16 @@ class SubtitleOptions(ToggleableOptionsDictValidator):
         """
         return [lang.value for lang in self._languages]
 
+    @property
+    def languages_required(self) -> Optional[List[str]]:
+        """
+        :expected type: Optional[List[String]]
+        :description:
+          Language code(s) that are required to be present for downloads to continue. If missing,
+          ytdl-sub will throw an error. NOTE: currently this only checks file-based subtitles.
+        """
+        return [lang.value for lang in self._languages_required]
+
     @property
     def allow_auto_generated_subtitles(self) -> Optional[bool]:
         """
@@ -211,7 +228,21 @@ class SubtitlesPlugin(Plugin[SubtitleOptions]):
         if self.plugin_options.embed_subtitles:
             file_metadata = FileMetadata(f"Embedded subtitles with lang(s) {', '.join(langs)}")
         if self.plugin_options.subtitles_name:
+            download_subtitle_lang_file_names: List[Tuple[str, str]] = []
+
             for lang in langs:
+                download_subtitle_file_name = entry.base_filename(
+                    ext=f"{lang}.{self.plugin_options.subtitles_type}"
+                )
+                if os.path.isfile(Path(self.working_directory) / download_subtitle_file_name):
+                    download_subtitle_lang_file_names.append((lang, download_subtitle_file_name))
+                elif lang in self.plugin_options.languages_required:
+                    raise UserThrownRuntimeError(
+                        f"Required the subtitle lang {lang}, but the file could not be found for "
+                        f"the entry {entry.title}."
+                    )
+
+            for lang, file_name in download_subtitle_lang_file_names:
                 output_subtitle_file_name = self.overrides.apply_formatter(
                     formatter=self.plugin_options.subtitles_name,
                     entry=entry,
@@ -219,9 +250,7 @@ class SubtitlesPlugin(Plugin[SubtitleOptions]):
                 )
 
                 self.save_file(
-                    file_name=entry.base_filename(
-                        ext=f"{lang}.{self.plugin_options.subtitles_type}"
-                    ),
+                    file_name=file_name,
                     output_file_name=output_subtitle_file_name,
                     entry=entry,
                 )