gh-151575: Emit DeprecationWarning in mimetypes.guess_type() for file…

[NaveenKumarG-dev]

Context

This PR completes the formal deprecation cycle for passing file paths into mimetypes.guess_type().

As noted by the long-standing # TODO in Lib/mimetypes.py, guess_type() is intended strictly for URLs. The function guess_file_type() was added in Python 3.13 as the preferred alternative, and the documentation was updated with a .. soft-deprecated:: 3.13 directive at that time. However, the runtime warning was never implemented.

Changes Made

• Implementation: Modified mimetypes.MimeTypes.guess_type() to emit a DeprecationWarning (with stacklevel=2) when it detects a file path instead of a valid URL.
• Coverage: The warning correctly triggers for plain strings (with no valid multi-character URL scheme), bytes objects, and os.PathLike objects. Valid URLs (like http://, ftp://, or data:) bypass the warning.
• Testing: Added GuessTypeDeprecationTestCase to Lib/test/test_mimetypes.py covering all the path and URL permutations to ensure correct behavior and avoid regressions.
• Documentation:
  • Upgraded the .. soft-deprecated:: 3.13 directive to .. deprecated:: 3.16 in Doc/library/mimetypes.rst.
  • Added entries in Doc/whatsnew/3.16.rst and Doc/deprecations/pending-removal-in-future.rst.
• NEWS: Generated the required NEWS blurb via blurb.

Linked Issue

Fixes #151575

---

Code of Conduct and CLA

• I have read the Python Developer's Guide
• I have read the Python Code of Conduct
• I have signed the Contributor License Agreement

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

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33178596 | 📁 Comparing afd0726 against main (9e863fa)

  🔍 Preview build  

9 files changed · ± 9 modified

± Modified

• deprecations/index.html
• deprecations/pending-removal-in-future.html
• library/mimetypes.html
• whatsnew/3.12.html
• whatsnew/3.13.html
• whatsnew/3.14.html
• whatsnew/3.15.html
• whatsnew/3.16.html
• whatsnew/changelog.html