Deprecate passing file paths instead of URLs to `mimetypes.guess_type()`

[NaveenKumarG-dev]

Feature or enhancement

Proposal:

In Python 3.13, mimetypes.guess_file_type() was introduced as the preferred alternative to guess_type() for file paths. The documentation was updated with a .. soft-deprecated:: 3.13 note at the time.

However, the # TODO: Deprecate accepting file paths (in particular path-like objects) comment in Lib/mimetypes.py was never fulfilled, and no actual DeprecationWarning is currently emitted at runtime when paths are passed in.

This proposal is to fulfill the existing # TODO and emit a DeprecationWarning for passing plain strings (with no valid URL scheme), bytes, and os.PathLike objects into mimetypes.guess_type().

This completes the soft-deprecation cycle initiated in Python 3.13.

Has this already been discussed elsewhere?

No response given

Links to previous discussion of this feature:

This fulfills the existing # TODO added during the introduction of guess_file_type() in Python 3.13:
https://github.com/python/cpython/blob/main/Lib/mimetypes.py#L131

Linked PRs

• gh-151575: Deprecate passing file paths instead of URLs to mimetypes.guess_type() #151576

[da-woods]

This completes the soft-deprecation cycle

There isn't really a soft-deprecation "cycle" though. It's mostly just an end state where the documentation recommends against something, it isn't developed further, but it stays basically indefinitely.

https://peps.python.org/pep-0387/#soft-deprecation

[NaveenKumarG-dev]

Thanks for the clarification. You're right that soft deprecation itself does not imply a future runtime deprecation. My reasoning was based primarily on the existing TODO in mimetypes.py and the introduction of guess_file_type() as the preferred API for file paths. I'll update the wording in the issue/PR description to avoid implying that soft deprecation automatically progresses to a runtime deprecation.