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 #33453444 | 📁 Comparing ec6e1da against main (9e863fa)

🔍 Preview build

84 files changed · ± 83 modified · - 1 deleted

± 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.

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

Wait, sorry Stephen, I may be misunderstanding, do you want them to remove the entire note under the directive? We need to be clear about what we're removing.

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.

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.

sirosen · 2026-07-28T14:38:01Z

    else:
        for gtype in args.type:
-            guess, encoding = guess_type(gtype, not args.lenient)
+            guess, encoding = guess_file_type(gtype, strict=not args.lenient)


This changes behavior in a way I wouldn't consider safe.

guess_type has capabilities that guess_file_type does not. For example, it can read data URLs:

$ python -m mimetypes 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==' type: text/plain encoding: None

I think the simplest thing to do here is to repeat the urllib.parse.urlparse and scheme check that guess_type currently includes. That way, CLI usage can switch between guess_type and guess_file_type safely.

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.

sirosen · 2026-07-28T18:45:41Z


+      .. deprecated:: 3.16
+         Passing a file path (or path-like object) instead of a URL.
+         Use :meth:`guess_file_type` instead.


Suggested change

Use :meth:`guess_file_type` instead.

Use :func:`guess_file_type` instead.

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

Comment thread Lib/test/test_mimetypes.py

import io

import mimetypes

import os

StanFromIreland Jul 28, 2026

Copy link
Copy Markdown

Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Revert these unrelated changes.

StanFromIreland reviewed Jul 28, 2026

View reviewed changes

hugovk reviewed Jul 28, 2026

View reviewed changes

sirosen reviewed Jul 28, 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.

	Use :meth:`guess_file_type` instead.
	Use :func:`guess_file_type` instead.

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

NaveenKumarG-dev commented Jun 17, 2026 •

edited

Loading

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

edited

Loading