gh-151575: Deprecate passing file paths instead of URLs to mimetypes.guess_type() by NaveenKumarG-dev · Pull Request #151576 · python/cpython

NaveenKumarG-dev · 2026-06-17T05:12:05Z

Context

mimetypes.guess_type() is intended for URLs, while mimetypes.guess_file_type() was introduced in Python 3.13 as the preferred API for file paths.

The implementation still accepts file paths without warning, despite the existing # TODO: Deprecate accepting file paths (in particular path-like objects) comment in Lib/mimetypes.py. This PR implements that TODO by deprecating file path inputs to guess_type() and directing users to guess_file_type() instead.

Changes Made

Implementation: Modified mimetypes.MimeTypes.guess_type() to emit a DeprecationWarning (stacklevel=2) when called with a file path instead of a URL.
Coverage: The warning triggers for plain strings that do not contain a valid URL scheme, as well as for bytes and os.PathLike objects. Valid URLs such as http://, ftp://, and data: continue to behave as before.
Testing: Added GuessTypeDeprecationTestCase to Lib/test/test_mimetypes.py covering path and URL inputs to verify warning behavior and prevent regressions.
Documentation:
- Updated Doc/library/mimetypes.rst to document the runtime deprecation.
- Added entries to Doc/whatsnew/3.16.rst and Doc/deprecations/pending-removal-in-future.rst.
NEWS: Added the required NEWS entry using blurb.

Rationale

This change aligns the runtime behavior with the documented distinction between URL handling (guess_type()) and file-path handling (guess_file_type()), while implementing the existing deprecation TODO in the source code.

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 (CLA)

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

…r file paths

read-the-docs-community · 2026-06-17T05:15:51Z

Documentation build overview

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

🔍 Preview build

169 files changed · + 3 added · ± 165 modified · - 1 deleted

+ Added

± Modified

- Deleted

library/asyncio-policy.html

…ess_type with new guess_file_type method

…com/NaveenKumarG-dev/cpython into gh-mimetypes-guess-type-deprecation

StanFromIreland · 2026-06-26T13:10:52Z

-   .. soft-deprecated:: 3.13
-      Passing a file path instead of URL.
-      Use :func:`guess_file_type` for this.
+   .. deprecated:: 3.16


Schedule removal for Python 3.21. Also, please add a note that it was soft-deprecated since Python 3.13.

All of these "scheduled for removal" notes should be in Doc/deprecations/pending-removal-in-3.21.rst, not inline in all of the various notes. @NaveenKumarG-dev, could you move them over to there? You'll see some examples of other pending items in that doc directory.

@StanFromIreland, is it right to include a note about the soft-deprecated history? I don't see that on other deprecations.

EDIT: I was mistaken here, see the thread below for more accurate details on what should change. Sorry! 😅

All of these "scheduled for removal" notes should be in Doc/deprecations/pending-removal-in-3.21.rst, not inline in all of the various notes.

I would prefer we have them here as well, that's our usual process. Otherwise, how is a user meant to know whether the function is going away, compared to just a subset of its functionality?

@StanFromIreland, is it right to include a note about the soft-deprecated history? I don't see that on other deprecations.

Let's include it for clarity. (And that's probably because they weren't soft-deprecated before, it's quite rare to do this.)

Schedule removal for Python 3.21.

Suggested change

.. deprecated:: 3.16

.. deprecated-removed:: 3.16 3.21

I would prefer we have them here as well, that's our usual process.

Oh, now that I'm looking more carefully and tracing this back, this is my mistake! Your statement that this is the norm made me recheck things, and I now see that we have a dedicated directive for this, deprecated-removed.

I believe that the correct course of action here is to update all of these to use deprecated-removed:: 3.16 3.21.

The text which is added here, stating the removal plan, is not typical, and I think should be removed.

Does the soft-deprecation need to be a textual note, or should it be simply a set of stacked directives, like so?

.. soft-deprecated:: 3.13 .. deprecated-removed:: 3.16 3.21 text goes here

Setting aside my earlier mistake, I think the correct rewrite is to remove the part of the note which details soft-deprecation and removal schedule, and use the directives instead.

So the rewrite should be something like this:

- .. deprecated:: 3.16 + .. soft-deprecated:: 3.13 + .. deprecated-removed:: 3.16 3.21 Passing a file path (or path-like object) instead of a URL. Use :meth:`guess_file_type` instead. - Soft-deprecated since Python 3.13, scheduled for removal in Python 3.21.

Using the bare directive makes it appear that the function itself is soft-deprecated, I'd prefer we state it instead to avoid such confusion and duplicating the details. We should however use deprecated-removed, and remove the ", scheduled ..." bit as it's rendered by the directive.

Hugo made a comment below which suggested using soft-deprecated along with deprecated-removed, but maybe he didn't mean stacking them without a body?

I tried a local doc build with this:

As you say, it looks like the whole function is soft deprecated, which is misleading.

I tried putting a body line in for the soft deprecation and I think I like that best:

Do you prefer a textual note inside of the deprecated-removed directive over this?

I think a textual note is less noise/clutter/duplication, ultimately, once it's removed its previous soft deprecation is not particularly significant.

Yep, it would be a bit shorter/simpler. I'm convinced!
In terms of getting this unblocked, I think it would be best if the PR author updates to match your feedback.

@NaveenKumarG-dev, could you implement Stan's recommendation here, which is to add a final line in the deprecated-removed notes that simply says "Soft-deprecated since version 3.13 ?
Sorry for giving misleading feedback earlier.

StanFromIreland · 2026-06-26T13:12:19Z

Please also remove file paths/path-like objects here.

StanFromIreland · 2026-06-26T13:15:10Z

            type='image/jpeg', strict=True), ['.jpg', '.jpe', '.jpeg'])


+class GuessTypeDeprecationTestCase(unittest.TestCase):


This is already covered above, I don't see anything that adds new coverage? We also run our test suite with -Werror on buildbots, so we don't miss spurious warnings.

StanFromIreland · 2026-06-26T13:15:29Z

-        """Guess the type of a file which is either a URL or a path-like object.
+        """Guess the type of a file based on its URL.
+
+        .. deprecated:: 3.16


Please remove this note.

StanFromIreland · 2026-06-26T13:16:05Z

            scheme = p.scheme
            url = p.path
        else:
+            # Input has no URL scheme — it is a file path, not a URL.


Suggested change

# Input has no URL scheme — it is a file path, not a URL.

I think it's sufficiently clear from reading the logic, let's not repeat ourselves.

StanFromIreland · 2026-06-26T13:16:57Z

@@ -0,0 +1 @@
+Emit DeprecationWarning when a file path is passed to :func:`mimetypes.guess_type`. Use :func:`mimetypes.guess_file_type` instead.


Reword it like so please: "Deprecate passing X to X. Use X instead."

…IME lookups

StanFromIreland · 2026-06-29T09:37:43Z

Please do not use the Update Branch button unless necessary (e.g. fixing conflicts, jogging the CI, or very old PRs) as it uses valuable resources and results in spurious notifications. For more information see the devguide.

sirosen · 2026-07-27T23:57:30Z

+   Guess the type of a file based on its URL, given by *url*.
+   URL can be a string.


This change seems malformed. "URL can be a string." isn't a normal sentence to have in docs.

I suggest:

Suggested change

Guess the type of a file based on its URL, given by *url*.

URL can be a string.

Guess the type of a file based on its URL, given as a string.

sirosen · 2026-07-28T14:27:14Z

-   .. soft-deprecated:: 3.13
-      Passing a file path instead of URL.
-      Use :func:`guess_file_type` for this.
+   .. deprecated:: 3.16


All of these "scheduled for removal" notes should be in Doc/deprecations/pending-removal-in-3.21.rst, not inline in all of the various notes. @NaveenKumarG-dev, could you move them over to there? You'll see some examples of other pending items in that doc directory.

@StanFromIreland, is it right to include a note about the soft-deprecated history? I don't see that on other deprecations.

EDIT: I was mistaken here, see the thread below for more accurate details on what should change. Sorry! 😅

StanFromIreland · 2026-07-28T17:41:47Z

 import io
 import mimetypes
 import os
+


Revert these unrelated changes.

StanFromIreland · 2026-07-28T17:42:25Z

        # Lazy import to improve module import time
        import os
        import urllib.parse
+        import warnings


Use lazy import (and you can move the others as well).

hugovk · 2026-07-28T18:25:29Z

-   .. soft-deprecated:: 3.13
-      Passing a file path instead of URL.
-      Use :func:`guess_file_type` for this.
+   .. deprecated:: 3.16


Schedule removal for Python 3.21.

Suggested change

.. deprecated:: 3.16

.. deprecated-removed:: 3.16 3.21

hugovk · 2026-07-28T18:26:14Z

      Similar to the :func:`guess_type` function, using the tables stored as part of
      the object.

+      .. deprecated:: 3.16


Suggested change

.. deprecated:: 3.16

.. deprecated-removed:: 3.16 3.21

hugovk · 2026-07-28T18:27:02Z

+   .. deprecated:: 3.16
+      Passing a file path (or path-like object) instead of a URL.
+      Use :func:`guess_file_type` instead.
+      Soft-deprecated since Python 3.13, scheduled for removal in Python 3.21.


We can skip this if we keep the .. soft-deprecated:: 3.13 bit and use .. deprecated-removed:: 3.16 3.21:

Suggested change

Soft-deprecated since Python 3.13, scheduled for removal in Python 3.21.

hugovk · 2026-07-28T18:27:08Z

+      .. deprecated:: 3.16
+         Passing a file path (or path-like object) instead of a URL.
+         Use :meth:`guess_file_type` instead.
+         Soft-deprecated since Python 3.13, scheduled for removal in Python 3.21.


Suggested change

Soft-deprecated since Python 3.13, scheduled for removal in Python 3.21.

…tions

sirosen · 2026-07-30T21:25:22Z

            scheme = p.scheme
            url = p.path
        else:
+            import warnings


In a previous review comment, this was flagged to move into a lazy import warnings at the top of the module.

You should do the same for import urllib.parse, above (and therefore removing it from the location where it appears below).

@StanFromIreland, I think the import os should just move to the top of the module, but not become lazy? Does that sound right to you? My impression is that it's pulled in on interpreter start. I suppose other interpreters might not do that?

sirosen · 2026-07-30T21:31:10Z

-   .. soft-deprecated:: 3.13
-      Passing a file path instead of URL.
-      Use :func:`guess_file_type` for this.
+   .. deprecated:: 3.16


Yep, it would be a bit shorter/simpler. I'm convinced!
In terms of getting this unblocked, I think it would be best if the PR author updates to match your feedback.

@NaveenKumarG-dev, could you implement Stan's recommendation here, which is to add a final line in the deprecated-removed notes that simply says "Soft-deprecated since version 3.13 ?
Sorry for giving misleading feedback earlier.

pythongh-151575: Emit DeprecationWarning in mimetypes.guess_type() fo…

1788ed3

…r file paths

NaveenKumarG-dev requested review from a team and AA-Turner as code owners June 17, 2026 05:12

bedevere-app Bot added the awaiting review label Jun 17, 2026

bedevere-app Bot mentioned this pull request Jun 17, 2026

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

Open

Merge branch 'main' into gh-mimetypes-guess-type-deprecation

afd0726

NaveenKumarG-dev changed the title ~~gh-151575: Emit DeprecationWarning in mimetypes.guess_type() for file…~~ gh-151575: Deprecate passing file paths instead of URLs to mimetypes.guess_type() Jun 17, 2026

NaveenKumarG-dev added 5 commits June 17, 2026 20:26

feat: introduce MimeTypes class and deprecate file path support in gu…

9276f2c

…ess_type with new guess_file_type method

Merge branch 'gh-mimetypes-guess-type-deprecation' of https://github.…

95c0ab0

…com/NaveenKumarG-dev/cpython into gh-mimetypes-guess-type-deprecation

Merge branch 'main' into gh-mimetypes-guess-type-deprecation

dbe1247

Merge branch 'main' into gh-mimetypes-guess-type-deprecation

89980ed

Merge branch 'main' into gh-mimetypes-guess-type-deprecation

2c00715

StanFromIreland reviewed Jun 26, 2026

View reviewed changes

NaveenKumarG-dev added 5 commits June 28, 2026 14:10

feat: add guess_file_type to mimetypes module to support path-based M…

1aba67d

…IME lookups

test: add test suite for mimetypes module

2f7b8ed

Merge branch 'main' into gh-mimetypes-guess-type-deprecation

71871a5

Merge branch 'main' into gh-mimetypes-guess-type-deprecation

c7a343d

Merge branch 'main' into gh-mimetypes-guess-type-deprecation

d6ac72c

Merge branch 'main' into gh-mimetypes-guess-type-deprecation

ec6e1da

sirosen requested changes Jul 28, 2026

View reviewed changes

bedevere-app Bot added awaiting core review and removed awaiting review labels Jul 28, 2026

StanFromIreland reviewed Jul 28, 2026

View reviewed changes

hugovk reviewed Jul 28, 2026

View reviewed changes

sirosen reviewed Jul 28, 2026

View reviewed changes

Comment thread Doc/library/mimetypes.rst Outdated

NaveenKumarG-dev added 2 commits July 30, 2026 13:33

Address PR feedback: fix mimetypes CLI, lazy imports, and doc depreca…

4b8515d

…tions

Merge branch 'main' into gh-mimetypes-guess-type-deprecation

36d97a7

Revert pre-commit adding newlines to mypy symlinks

e819067

sirosen reviewed Jul 30, 2026

View reviewed changes

		type='image/jpeg', strict=True), ['.jpg', '.jpe', '.jpeg'])


		class GuessTypeDeprecationTestCase(unittest.TestCase):

		@@ -0,0 +1 @@
		Emit DeprecationWarning when a file path is passed to :func:`mimetypes.guess_type`. Use :func:`mimetypes.guess_file_type` instead.

		Guess the type of a file based on its URL, given by url.
		URL can be a string.

Uh oh!

Uh oh!

Conversation

NaveenKumarG-dev commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

Changes Made

Rationale

Linked Issue

Code of Conduct and CLA

Uh oh!

read-the-docs-community Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sirosen Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StanFromIreland commented Jun 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sirosen Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

NaveenKumarG-dev commented Jun 17, 2026 •

edited

Loading

read-the-docs-community Bot commented Jun 17, 2026 •

edited

Loading

sirosen Jul 28, 2026 •

edited

Loading

sirosen Jul 28, 2026 •

edited

Loading