gh-93096: Make mimetypes CLI tool public

Doc/library/mimetypes.rst

@@ -272,3 +272,96 @@ than one MIME-type database; it provides an interface similar to the one of the
       types, else to the list of non-standard types.
 
       .. versionadded:: 3.2
+
+
+.. mimetypes-cli:
+
+Command-Line Usage
+------------------
+
+The :mod:`mimetypes` module can be executed as a script from the command line.
+
+.. code-block:: sh
+
+   python -m mimetypes [-e] [-l] type [type ...]
+
+The following options are accepted:
+
+.. program:: mimetypes
+
+.. cmdoption:: -h
+               --help
+
+   Show the help message and exit.
+
+.. cmdoption:: -e
+               --extension
+
+   Guess extension instead of type.
+
+.. cmdoption:: -l
+               --lenient
+
+   Additionally search for some common, but non-standard types.
+
+The script converts file extensions to MIME types if ``--extension`` option
+is specified, or vice versa if not.
+
+For each ``type`` entry, the script writes a line into the standard output
+stream. If an unknown type occurs, it writes an error message into the
+standard error stream and aborts with the return code ``1``.
+
+
+.. mimetypes-cli-example:
+
+Command-Line Example
+--------------------
+
+Here are some examples of typical usage of the :mod:`mimetypes` command
+line interface:
+
+.. code-block:: shell
+
+   # get a MIME type by a file name
+   $ python -m mimetypes filename.png
+   type: image/png encoding: None
+
+   # get a MIME type by a URL
+   python -m mimetypes http://example.com/filename.txt
+   type: text/plain encoding: None
+
+   # get a complex MIME type
+   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 -l filename.pict
+   type: image/pict encoding: None
+
+   # get a file extension by a MIME type
+   $ python -m mimetypes -e text/javascript
+   .js
+
+   # get a file extension by a rare MIME type
+   $ python -m mimetypes -e text/xul
+   error: unknown type text/xul
+
+   # now look in the extended database again
+   $ python -m mimetypes -e -l text/xul
+   .xul
+
+   # try to feed an unknown file extension
+   $ python -m mimetypes filename.sh filename.nc filename.xxx filename.txt
+   type: application/x-sh encoding: None
+   type: application/x-netcdf encoding: None
+   error: unknown extension of filename.xxx
+
+   # try to feed an unknown MIME type
+   $ python -m mimetypes -e audio/aac audio/opus audio/future audio/x-wav
+   .aac
+   .opus
+   error: unknown type audio/future

Lib/mimetypes.py

@@ -596,49 +596,36 @@ def _default_mime_types():
 
 
 def _main():
-    import getopt
-
-    USAGE = """\
-Usage: mimetypes.py [options] type
-
-Options:
-    --help / -h       -- print this message and exit
-    --lenient / -l    -- additionally search of some common, but non-standard
-                         types.
-    --extension / -e  -- guess extension instead of type
-
-More than one type argument may be given.
-"""
-
-    def usage(code, msg=''):
-        print(USAGE)
-        if msg: print(msg)
-        sys.exit(code)
-
-    try:
-        opts, args = getopt.getopt(sys.argv[1:], 'hle',
-                                   ['help', 'lenient', 'extension'])
-    except getopt.error as msg:
-        usage(1, msg)
-
-    strict = 1
-    extension = 0
-    for opt, arg in opts:
-        if opt in ('-h', '--help'):
-            usage(0)
-        elif opt in ('-l', '--lenient'):
-            strict = 0
-        elif opt in ('-e', '--extension'):
-            extension = 1
-    for gtype in args:
-        if extension:
-            guess = guess_extension(gtype, strict)
-            if not guess: print("I don't know anything about type", gtype)
-            else: print(guess)
-        else:
-            guess, encoding = guess_type(gtype, strict)
-            if not guess: print("I don't know anything about type", gtype)
-            else: print('type:', guess, 'encoding:', encoding)
+    """Run the mimetypes command line interface."""
+    from argparse import ArgumentParser
+    parser = ArgumentParser(description='map filename extensions to MIME types')
+    parser.add_argument(
+        '-e', '--extension',
+        action='store_true',
+        help='guess extension instead of type'
+    )
+    parser.add_argument(
+        '-l', '--lenient',
+        action='store_true',
+        help='additionally search for common but non-standard types'
+    )
+    parser.add_argument('type', nargs='+', help='a type to search')
+    arguments = parser.parse_args()
+
+    if arguments.extension:
+        for gtype in arguments.type:
+            guess = guess_extension(gtype, not arguments.lenient)
+            if guess:
+                print(guess)
+            else:
+                sys.exit(f"error: unknown type {gtype}")
+    else:
+        for gtype in arguments.type:
+            guess, encoding = guess_type(gtype, not arguments.lenient)
+            if guess:
+                print('type:', guess, 'encoding:', encoding)
+            else:
+                sys.exit(f"error: unknown extension of {gtype}")
 
 
 if __name__ == '__main__':

Lib/test/test_mimetypes.py

@@ -1,11 +1,13 @@
 import io
 import mimetypes
+from os import linesep
 import pathlib
 import sys
 import unittest.mock
 
 from test import support
 from test.support import os_helper
+from test.support.script_helper import run_python_until_end
 from platform import win32_edition
 
 try:
@@ -285,50 +287,54 @@ def test__all__(self):
 
 class MimetypesCliTestCase(unittest.TestCase):
 
-    def mimetypes_cmd(self, *args, **kwargs):
-        support.patch(self, sys, "argv", [sys.executable, *args])
-        with support.captured_stdout() as output:
-            mimetypes._main()
-            return output.getvalue().strip()
+    @classmethod
+    def mimetypes_cmd(cls, *args, **kwargs):
+        result, _ = run_python_until_end('-m', 'mimetypes', *args)
+        return result.rc, result.out.decode(), result.err.decode()
 
     def test_help_option(self):
-        support.patch(self, sys, "argv", [sys.executable, "-h"])
-        with support.captured_stdout() as output:
-            with self.assertRaises(SystemExit) as cm:
-                mimetypes._main()
-
-        self.assertIn("Usage: mimetypes.py", output.getvalue())
-        self.assertEqual(cm.exception.code, 0)
+        retcode, out, err = self.mimetypes_cmd('-h')
+        self.assertEqual(retcode, 0)
+        self.assertIn('usage: mimetypes.py', out)
+        self.assertEqual(err, '')
 
     def test_invalid_option(self):
-        support.patch(self, sys, "argv", [sys.executable, "--invalid"])
-        with support.captured_stdout() as output:
-            with self.assertRaises(SystemExit) as cm:
-                mimetypes._main()
-
-        self.assertIn("Usage: mimetypes.py", output.getvalue())
-        self.assertEqual(cm.exception.code, 1)
+        retcode, out, err = self.mimetypes_cmd('--invalid')
+        self.assertEqual(retcode, 2)
+        self.assertEqual(out, '')
+        self.assertIn('usage: mimetypes.py', err)
 
     def test_guess_extension(self):
-        eq = self.assertEqual
-
-        extension = self.mimetypes_cmd("-l", "-e", "image/jpg")
-        eq(extension, ".jpg")
+        retcode, out, err = self.mimetypes_cmd('-l', '-e', 'image/jpg')
+        self.assertEqual(retcode, 0)
+        self.assertEqual(out, f'.jpg{linesep}')
+        self.assertEqual(err, '')
 
-        extension = self.mimetypes_cmd("-e", "image/jpg")
-        eq(extension, "I don't know anything about type image/jpg")
+        retcode, out, err = self.mimetypes_cmd('-e', 'image/jpg')
+        self.assertEqual(retcode, 1)
+        self.assertEqual(out, '')
+        self.assertEqual(err, f"I don't know anything about type image/jpg{linesep}")
 
-        extension = self.mimetypes_cmd("-e", "image/jpeg")
-        eq(extension, ".jpg")
+        retcode, out, err = self.mimetypes_cmd('-e', 'image/jpeg')
+        self.assertEqual(retcode, 0)
+        self.assertEqual(out, f'.jpg{linesep}')
+        self.assertEqual(err, '')
 
     def test_guess_type(self):
-        eq = self.assertEqual
-
-        type_info = self.mimetypes_cmd("-l", "foo.pic")
-        eq(type_info, "type: image/pict encoding: None")
-
-        type_info = self.mimetypes_cmd("foo.pic")
-        eq(type_info, "I don't know anything about type foo.pic")
+        retcode, out, err = self.mimetypes_cmd('-l', 'foo.webp')
+        self.assertEqual(retcode, 0)
+        self.assertEqual(out, f'type: image/webp encoding: None{linesep}')
+        self.assertEqual(err, '')
+
+    @unittest.skipIf(
+        sys.platform == 'darwin',
+        'macOS lists common_types in mime.types thus making them always known'
+    )
+    def test_guess_type_conflicting_with_mimetypes(self):
+        retcode, out, err = self.mimetypes_cmd('foo.webp')
+        self.assertEqual(retcode, 1)
+        self.assertEqual(out, '')
+        self.assertEqual(err, f"I don't know anything about type foo.webp{linesep}")
 
 if __name__ == "__main__":
     unittest.main()

Misc/ACKS

@@ -814,6 +814,7 @@ Oleg Höfling
 Robert Hölzl
 Stefan Hölzl
 Catalin Iacob
+Oleg Iarygin
 Mihai Ibanescu
 Ali Ikinci
 Aaron Iles

Misc/NEWS.d/next/Documentation/2022-05-23-11-53-24.gh-issue-93096.TIuIhx.rst

@@ -0,0 +1 @@
+Added *Command-Line Usage* section for :mod:`mimetypes`. Patch by Oleg Iarygin.

Misc/NEWS.d/next/Library/2022-05-28-19-41-02.gh-issue-93096.qjUyRG.rst

@@ -0,0 +1,4 @@
+Command-line :mod:`mimetypes` now exits with ``1`` on failure instead of ``0``
+and ``2`` on incorrect command line parameters instead of ``1``.
+Also, errors are printed to stderr instead of stdout and their text is made
+tighter. Patch by Oleg Iarygin.