[yt-dlp] Expose options type

[ryux1]

Closes #16331.

Expose the existing yt-dlp options TypedDict as the type-checking-only YoutubeDLOptions so callers can annotate a stored options dictionary before passing it to YoutubeDL. This preserves contextual typing for option values without widening the constructor to arbitrary mappings or changing runtime exports.

A regression test covers the reported stored-dictionary pattern and verifies that invalid option value types are still rejected.

Validated with:

• pre-commit run --files ...
• python tests/check_typeshed_structure.py
• python tests/mypy_test.py stubs/yt-dlp (Python 3.10–3.15)
• python tests/pyright_test.py stubs/yt-dlp
• python tests/regr_test.py yt-dlp
• python tests/stubtest_third_party.py yt-dlp

[donbarbos]

Thanks for contributing!
Your tests also pass on the main branch. The only change here is renaming the TypedDict, but unfortunately, there doesn't seem to be any justification for it (unless I'm missing something). _Params can also be imported.

[ryux1]

The distinction I’m addressing is public typing API rather than runtime importability. _Params can technically be imported, but its leading underscore marks it private, so recommending it in user annotations couples callers to an implementation name and can trigger private-usage diagnostics under stricter checker configurations.

The linked issue’s stored-dictionary pattern needs an explicit TypedDict annotation to retain per-key contextual types; YoutubeDLOptions provides a supported name for that annotation while preserving strict option-value checking. The added test exercises exactly that pattern.

If Typeshed’s policy is to leave this type private despite #16331, I’m happy to close this, but the rename is the intended behavioral change: making the existing option schema a public type-checking API.

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉