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

Doc/deprecations/pending-removal-in-future.rst

@@ -75,6 +75,10 @@ although there is currently no date scheduled for their removal.
 * :mod:`mailbox`: Use of StringIO input and text mode is deprecated, use
   BytesIO and binary mode instead.
 
+* :mod:`mimetypes`: Passing a file path (including path-like objects and bytes
+  paths) to :func:`~mimetypes.guess_type`. Use
+  :func:`~mimetypes.guess_file_type` instead. (:gh:`151575`)
+
 * :mod:`os`: Calling :func:`os.register_at_fork` in a multi-threaded process.
 
 * :mod:`os.path`: :func:`os.path.commonprefix` is deprecated, use

Doc/library/mimetypes.rst

@@ -28,8 +28,7 @@ the information :func:`init` sets up.
 
    .. index:: pair: MIME; headers
 
-   Guess the type of a file based on its filename, path or URL, given by *url*.
-   URL can be a string or a :term:`path-like object`.
+   Guess the type of a file based on its URL, given as a string.
 
    The return value is a tuple ``(type, encoding)`` where *type* is ``None`` if the
    type can't be guessed (missing or unknown suffix) or a string of the form
@@ -54,9 +53,9 @@ the information :func:`init` sets up.
    .. versionchanged:: 3.8
       Added support for *url* being a :term:`path-like object`.
 
-   .. soft-deprecated:: 3.13
-      Passing a file path instead of URL.
-      Use :func:`guess_file_type` for this.
+   .. deprecated-removed:: 3.16 3.21
+      Passing a file path (or path-like object) instead of a URL.
+      Use :func:`guess_file_type` instead.
 
 
 .. function:: guess_file_type(path, *, strict=True)
@@ -263,6 +262,9 @@ than one MIME-type database; it provides an interface similar to the one of the
       Similar to the :func:`guess_type` function, using the tables stored as part of
       the object.
 
+      .. deprecated-removed:: 3.16 3.21
+         Passing a file path (or path-like object) instead of a URL.
+         Use :func:`guess_file_type` instead.
 
    .. method:: MimeTypes.guess_file_type(path, *, strict=True)
 

Doc/whatsnew/3.16.rst

@@ -741,6 +741,13 @@ New deprecations
     3.9, now issues a deprecation warning on use. This property is slated for
     removal in 3.21. Use ``ast.Tuple.elts`` instead.
 
+* :mod:`mimetypes`:
+
+  * Passing a file path (or :term:`path-like object`) to
+    :func:`mimetypes.guess_type` is now deprecated.
+    Use :func:`mimetypes.guess_file_type` instead.
+    (Contributed by Naveen Kumar G in :gh:`151575`.)
+
 * :mod:`struct`:
 
   * Soft-deprecated since Python 3.15, using ``'F'`` and ``'D'`` type codes are now

Lib/mimetypes.py

@@ -106,7 +106,7 @@ def add_type(self, type, ext, strict=True):
             exts.append(ext)
 
     def guess_type(self, url, strict=True):
-        """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.
 
         Return value is a tuple (type, encoding) where type is None if
         the type can't be guessed (no or unknown suffix) or a string
@@ -128,13 +128,19 @@ def guess_type(self, url, strict=True):
         import os
         import urllib.parse
 
-        # TODO: Deprecate accepting file paths (in particular path-like objects).
         url = os.fspath(url)
         p = urllib.parse.urlparse(url)
         if p.scheme and len(p.scheme) > 1:
             scheme = p.scheme
             url = p.path
         else:
+            import warnings
+            warnings.warn(
+                "Passing a file path to guess_type() is deprecated and will be "
+                "removed in a future version. Use guess_file_type() instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
             return self.guess_file_type(url, strict=strict)
         if scheme == 'data':
             # syntax of data URLs:
@@ -752,8 +758,13 @@ def _main(args=None):
                 results.append(f"error: unknown type {gtype}")
         return results
     else:
+        import urllib.parse
         for gtype in args.type:
-            guess, encoding = guess_type(gtype, not args.lenient)
+            p = urllib.parse.urlparse(gtype)
+            if p.scheme and len(p.scheme) > 1:
+                guess, encoding = guess_type(gtype, strict=not args.lenient)
+            else:
+                guess, encoding = guess_file_type(gtype, strict=not args.lenient)
             if guess:
                 results.append(f"type: {guess} encoding: {encoding}")
             else:

Lib/test/test_mimetypes.py

@@ -3,7 +3,9 @@
 import os
 import shlex
 import sys
+import unittest
 import unittest.mock
+
 from platform import win32_edition
 from test import support
 from test.support import cpython_only, force_not_colorized, os_helper, requires_subprocess
@@ -232,14 +234,14 @@ def test_init_knownfiles(self):
 
     def test_added_types_are_used(self):
         mimetypes.add_type('testing/default-type', '')
-        mime_type, _ = mimetypes.guess_type('')
+        mime_type, _ = mimetypes.guess_file_type('')
         self.assertEqual(mime_type, 'testing/default-type')
 
-        mime_type, _ = mimetypes.guess_type('test.myext')
+        mime_type, _ = mimetypes.guess_file_type('test.myext')
         self.assertEqual(mime_type, None)
 
         mimetypes.add_type('testing/type', '.myext')
-        mime_type, _ = mimetypes.guess_type('test.myext')
+        mime_type, _ = mimetypes.guess_file_type('test.myext')
         self.assertEqual(mime_type, 'testing/type')
 
     def test_add_type_with_undotted_extension_not_supported(self):
@@ -389,21 +391,26 @@ def test_filename_with_url_delimiters(self):
                 path = prefix + name
                 with self.subTest(path=path):
                     eq(self.db.guess_file_type(path), gzip_expected)
-                    eq(self.db.guess_type(path), gzip_expected)
+                    with self.assertWarns(DeprecationWarning):
+                        eq(self.db.guess_type(path), gzip_expected)
             expected = (None, None) if os.name == 'nt' else gzip_expected
             for prefix in ('//', '\\\\', '//share/', '\\\\share\\'):
                 path = prefix + name
                 with self.subTest(path=path):
                     eq(self.db.guess_file_type(path), expected)
-                    eq(self.db.guess_type(path), expected)
+                    with self.assertWarns(DeprecationWarning):
+                        eq(self.db.guess_type(path), expected)
         eq(self.db.guess_file_type(r" \"\`;b&b&c |.tar.gz"), gzip_expected)
-        eq(self.db.guess_type(r" \"\`;b&b&c |.tar.gz"), gzip_expected)
+        with self.assertWarns(DeprecationWarning):
+            eq(self.db.guess_type(r" \"\`;b&b&c |.tar.gz"), gzip_expected)
 
         eq(self.db.guess_file_type(r'foo/.tar.gz'), (None, 'gzip'))
-        eq(self.db.guess_type(r'foo/.tar.gz'), (None, 'gzip'))
+        with self.assertWarns(DeprecationWarning):
+            eq(self.db.guess_type(r'foo/.tar.gz'), (None, 'gzip'))
         expected = (None, 'gzip') if os.name == 'nt' else gzip_expected
         eq(self.db.guess_file_type(r'foo\.tar.gz'), expected)
-        eq(self.db.guess_type(r'foo\.tar.gz'), expected)
+        with self.assertWarns(DeprecationWarning):
+            eq(self.db.guess_type(r'foo\.tar.gz'), expected)
         eq(self.db.guess_type(r'scheme:foo\.tar.gz'), gzip_expected)
 
     def test_url(self):
@@ -461,16 +468,20 @@ def test_path_like_ob(self):
         expected = self.db.guess_file_type(filename)
 
         self.assertEqual(self.db.guess_file_type(filepath), expected)
-        self.assertEqual(self.db.guess_type(filepath), expected)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(self.db.guess_type(filepath), expected)
         self.assertEqual(self.db.guess_file_type(
             filepath_with_abs_dir), expected)
-        self.assertEqual(self.db.guess_type(
-            filepath_with_abs_dir), expected)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(self.db.guess_type(
+                filepath_with_abs_dir), expected)
         self.assertEqual(self.db.guess_file_type(filepath_relative), expected)
-        self.assertEqual(self.db.guess_type(filepath_relative), expected)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(self.db.guess_type(filepath_relative), expected)
 
         self.assertEqual(self.db.guess_file_type(path_dir), (None, None))
-        self.assertEqual(self.db.guess_type(path_dir), (None, None))
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(self.db.guess_type(path_dir), (None, None))
 
     def test_bytes_path(self):
         self.assertEqual(self.db.guess_file_type(b'foo.html'),
@@ -489,6 +500,9 @@ def test_keywords_args_api(self):
             type='image/jpeg', strict=True), ['.jpg', '.jpe', '.jpeg'])
 
 
+
+
+
 @unittest.skipUnless(sys.platform.startswith("win"), "Windows only")
 class Win32MimeTypesTestCase(unittest.TestCase):
     def setUp(self):
@@ -510,9 +524,9 @@ def test_registry_parsing(self):
         # Windows registry is undocumented AFAIK.
         # Use file types that should *always* exist:
         eq = self.assertEqual
-        eq(self.db.guess_type("foo.txt"), ("text/plain", None))
-        eq(self.db.guess_type("image.jpg"), ("image/jpeg", None))
-        eq(self.db.guess_type("image.png"), ("image/png", None))
+        eq(self.db.guess_file_type("foo.txt"), ("text/plain", None))
+        eq(self.db.guess_file_type("image.jpg"), ("image/jpeg", None))
+        eq(self.db.guess_file_type("image.png"), ("image/png", None))
 
     @unittest.skipIf(not hasattr(_winapi, "_mimetypes_read_windows_registry"),
                      "read_windows_registry accelerator unavailable")

Misc/NEWS.d/next/Library/2026-06-17-09-45-00.gh-issue-151575.mimetype.rst

@@ -0,0 +1 @@
+Deprecate passing a file path to :func:`mimetypes.guess_type`. Use :func:`mimetypes.guess_file_type` instead.