gh-149682: Fix mimetypes CLI to write error messages to stderr

Author: htjworld

Doc/library/mimetypes.rst

@@ -373,34 +373,32 @@ interface:
    $ python -m mimetypes filename.tar.gz
    type: application/x-tar encoding: gzip
 
-   $ # get a MIME type for a rare file extension
-   $ python -m mimetypes filename.pict
-   error: unknown extension of filename.pict
-
-   $ # now look in the extended database built into Python
-   $ python -m mimetypes --lenient filename.pict
-   type: image/pict encoding: None
+   $ # get a MIME type for an unknown file extension
+   $ python -m mimetypes filename.zzz
+   error: media type unknown for filename.zzz
 
    $ # get a file extension by a MIME type
    $ python -m mimetypes --extension text/javascript
    .js
 
-   $ # get a file extension by a rare MIME type
+   $ # get a file extension by a rare MIME type (error goes to stderr)
    $ python -m mimetypes --extension text/xul
    error: unknown type text/xul
 
    $ # now look in the extended database again
    $ python -m mimetypes --extension --lenient text/xul
    .xul
 
-   $ # try to feed an unknown file extension
-   $ python -m mimetypes filename.sh filename.nc filename.xxx filename.txt
+   $ # try to feed an unknown file extension (error goes to stderr)
+   $ python -m mimetypes filename.sh filename.nc filename.zzz filename.txt
    type: application/x-sh encoding: None
    type: application/x-netcdf encoding: None
-   error: unknown extension of filename.xxx
+   error: media type unknown for filename.zzz
+   type: text/plain encoding: None
 
-   $ # try to feed an unknown MIME type
+   $ # try to feed an unknown MIME type (error goes to stderr)
    $ python -m mimetypes --extension audio/aac audio/opus audio/future audio/x-wav
    .aac
    .opus
    error: unknown type audio/future
+   .wav

Lib/mimetypes.py

@@ -756,5 +756,11 @@ def _main(args=None):
     import sys
 
     results = _main()
-    print("\n".join(results))
-    sys.exit(any(result.startswith("error: ") for result in results))
+    has_error = False
+    for result in results:
+        if result.startswith("error: "):
+            print(result, file=sys.stderr, flush=True)
+            has_error = True
+        else:
+            print(result, flush=True)
+    sys.exit(has_error)

Lib/test/test_mimetypes.py

@@ -6,8 +6,9 @@
 import unittest.mock
 from platform import win32_edition
 from test import support
-from test.support import cpython_only, force_not_colorized, os_helper
+from test.support import cpython_only, force_not_colorized, os_helper, requires_subprocess
 from test.support.import_helper import ensure_lazy_imports
+from test.support.script_helper import assert_python_ok, assert_python_failure
 
 try:
     import _winapi
@@ -508,5 +509,57 @@ def test_invocation_error(self):
                 self.assertEqual(result, expected)
 
 
+@requires_subprocess()
+class CommandLineSubprocessTest(unittest.TestCase):
+    def test_help(self):
+        rc, stdout, stderr = assert_python_ok('-m', 'mimetypes', '--help')
+        self.assertIn(b'mimetypes', stdout)
+        self.assertIn(b'--extension', stdout)
+        self.assertIn(b'--lenient', stdout)
+
+    def test_type_lookup(self):
+        rc, stdout, stderr = assert_python_ok('-m', 'mimetypes', 'foo.pdf')
+        self.assertIn(b'application/pdf', stdout)
+        self.assertEqual(stderr, b'')
+
+    def test_type_lookup_unknown(self):
+        rc, stdout, stderr = assert_python_failure('-m', 'mimetypes', 'foo.unknownext12345')
+        self.assertEqual(stdout, b'')
+        self.assertIn(b'error:', stderr)
+
+    def test_extension_flag(self):
+        rc, stdout, stderr = assert_python_ok('-m', 'mimetypes', '-e', 'image/jpeg')
+        self.assertIn(b'.jpg', stdout)
+        self.assertEqual(stderr, b'')
+
+    def test_extension_flag_unknown(self):
+        rc, stdout, stderr = assert_python_failure('-m', 'mimetypes', '-e', 'image/unknowntype12345')
+        self.assertEqual(stdout, b'')
+        self.assertIn(b'error:', stderr)
+
+    def test_lenient_flag(self):
+        rc, stdout, stderr = assert_python_ok('-m', 'mimetypes', '-e', '--lenient', 'text/xul')
+        self.assertIn(b'.xul', stdout)
+        self.assertEqual(stderr, b'')
+
+    def test_multiple_inputs(self):
+        rc, stdout, stderr = assert_python_ok('-m', 'mimetypes', 'foo.pdf', 'foo.png')
+        self.assertIn(b'application/pdf', stdout)
+        self.assertIn(b'image/png', stdout)
+        self.assertEqual(stderr, b'')
+
+    def test_multiple_inputs_with_error(self):
+        rc, stdout, stderr = assert_python_failure(
+            '-m', 'mimetypes', 'foo.pdf', 'foo.unknownext12345'
+        )
+        self.assertIn(b'application/pdf', stdout)
+        self.assertNotIn(b'error:', stdout)
+        self.assertIn(b'error:', stderr)
+
+    def test_unknown_flag(self):
+        rc, stdout, stderr = assert_python_failure('-m', 'mimetypes', '--unknown-flag')
+        self.assertNotEqual(rc, 0)
+
+
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/Library/2026-05-11-23-38-47.gh-issue-149682.UE08R4.rst

@@ -0,0 +1,2 @@
+Fix :mod:`mimetypes` CLI to write error messages to stderr instead of stdout,
+and update the documentation examples to reflect the correct behavior.