Add yt-dlp stubs

[Tatsh]

Porting over from Tatsh/yt-dlp-types.

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]

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]

@srittau this is ready for review.

[github-actions]

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]

[Sky-NiniKo]

Sorry I missed the notif, but like thcrt, thanks for cc-ing me. This is indeed a good idea, and it is well executed. Fingers crossed for a quick review and a peaceful merge.

[srittau]

Thanks, one note below.

Also, most uses of object should probably be Any. For example Mapping[str, object], where the type depends on the key, the type should be Mapping[str, Any]. Similar in other cases where *args arguments are marked as object. object is only applicable for argument types, if literally any object can be used in all situations. These are fairly rare. But please note that Any must be documented, unless it's obvious why Any was used (as is the case for Mapping[str, Any]).

Cases where object is appropriate:

• Return types of callables, where the returned value is ignored.
• Cases where the arguments are passed to str() or a similar function that can handle all objects.

[srittau]

It's easier and more readable to just use:

Suggested change

	@type_check_only
	class _RetrySleepFunctions(TypedDict):
	default: NotRequired[Callable[[int], int]]
	file_access: NotRequired[Callable[[int], int]]
	fragment: NotRequired[Callable[[int], int]]
	@type_check_only
	class _RetrySleepFunctions(TypedDict, total=False):
	default: Callable[[int], int]
	file_access: Callable[[int], int]
	fragment: Callable[[int], int]

Also applies to the TypedDicts below.