Add yt-dlp stubs #14216

Tatsh · 2025-06-03T23:51:19Z

Upstream is unlikely to have full types any time soon. Though it may seem like an insular project, there is utility in using yt-dlp outside as I do in some of my projects. Examples:

Use yt-dlp in addition to other code when archiving a site (yt-dlp does a good job collecting metadata with the videos)
Use yt-dlp but write an extractor you do not wish to contribute to yt-dlp (added via YoutubeDL.add_info_extractor()).

Private methods are included in yt_dlp.extractor.common.InfoExtractor because it is normal to extend this class and override them.

There is no intention to stub all the different extractors and post-processors. Generally they are only called by yt-dlp's 'main'.

Deprecated functions and methods are generally not included.

Once accepted I will deprecate and archive yt-dlp-types on Github and on PyPI.

cc @Sky-NiniKo @thcrt

Usages:

https://github.com/Tatsh/yt-dlp-utils/blob/master/yt_dlp_utils/lib.py#L51
https://github.com/Tatsh/patreon-archiver/blob/master/patreon_archiver/main.py#L68 (indirect through yt-dlp-utils)

thcrt · 2025-06-05T13:06:53Z

Cheers for cc-ing me, appreciate it. It would indeed be nice to have the stubs maintained in typeshed and hence more easily discoverable for devs calling yt-dlp directly.

Tatsh · 2025-06-08T05:15:45Z

@srittau this is ready for review.

github-actions · 2025-06-08T05:29:12Z

Diff from mypy_primer, showing the effect of this PR on open source code:

core (https://github.com/home-assistant/core)
+ homeassistant/components/media_extractor/__init__.py:63: error: Incompatible types (expression has type "Logger", TypedDict item "logger" has type "_LoggerProtocol")  [typeddict-item]
+ homeassistant/components/media_extractor/__init__.py:63: note: "Logger" is missing following "_LoggerProtocol" protocol members:
+ homeassistant/components/media_extractor/__init__.py:63: note:     stderr, stdout
+ homeassistant/components/media_extractor/__init__.py:63: note: Following member(s) of "Logger" have conflicts:
+ homeassistant/components/media_extractor/__init__.py:63: note:     Expected:
+ homeassistant/components/media_extractor/__init__.py:63: note:         def warning(self, message: str, *, once: bool = ..., only_once: bool = ...) -> None
+ homeassistant/components/media_extractor/__init__.py:63: note:     Got:
+ homeassistant/components/media_extractor/__init__.py:63: note:         def warning(self, msg: object, *args: object, exc_info: bool | tuple[type[BaseException], BaseException, TracebackType | None] | tuple[None, None, None] | BaseException | None = ..., stack_info: bool = ..., stacklevel: int = ..., extra: Mapping[str, object] | None = ...) -> None
+ homeassistant/components/media_extractor/__init__.py:186: error: Argument 1 to "YoutubeDL" has incompatible type "dict[str, object]"; expected "_Params | None"  [arg-type]
+ homeassistant/components/media_extractor/__init__.py:196: error: TypedDict "_InfoDict" has no key "entries"  [typeddict-item]
+ homeassistant/components/media_extractor/__init__.py:215: error: TypedDict "_InfoDict" has no key "extractor"  [typeddict-item]
+ homeassistant/components/media_extractor/__init__.py:216: error: Argument 1 to "get_best_stream_youtube" has incompatible type "list[object] | None"; expected "list[dict[str, Any]]"  [arg-type]
+ homeassistant/components/media_extractor/__init__.py:217: error: Argument 1 to "get_best_stream" has incompatible type "list[object] | None"; expected "list[dict[str, Any]]"  [arg-type]