gh-90300: split --help output into separate options (GH-30331)

Make --help output shorter and add new help options.

--help-env, --help-xoptions and --help-all command-line options are
added to complement --help.
(cherry picked from commit 8aa9d40)

Co-authored-by: Éric <[email protected]>

Author: miss-islington

Doc/using/cmdline.rst

@@ -183,15 +183,37 @@ automatically enabled, if available on your platform (see
    Automatic enabling of tab-completion and history editing.
 
 
+.. _using-on-generic-options:
+
 Generic options
 ~~~~~~~~~~~~~~~
 
 .. cmdoption:: -?
                -h
                --help
 
-   Print a short description of all command line options.
+   Print a short description of all command line options and corresponding
+   environment variables and exit.
+
+.. cmdoption:: --help-env
+
+   Print a short description of Python-specific environment variables
+   and exit.
+
+   .. versionadded:: 3.11
+
+.. cmdoption:: --help-xoptions
 
+   Print a description of implementation-specific :option:`-X` options
+   and exit.
+
+   .. versionadded:: 3.11
+
+.. cmdoption:: --help-all
+
+   Print complete usage information and exit.
+
+   .. versionadded:: 3.11
 
 .. cmdoption:: -V
                --version
@@ -212,6 +234,7 @@ Generic options
    .. versionadded:: 3.6
       The ``-VV`` option.
 
+
 .. _using-on-misc-options:
 
 Miscellaneous options
@@ -457,6 +480,7 @@ Miscellaneous options
    See :ref:`warning-filter` and :ref:`describing-warning-filters` for more
    details.
 
+
 .. cmdoption:: -x
 
    Skip the first line of the source, allowing use of non-Unix forms of
@@ -550,6 +574,7 @@ Miscellaneous options
       The ``-X frozen_modules`` option.
 
 
+
 Options you shouldn't use
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

Lib/test/test_cmd_line.py

@@ -28,32 +28,55 @@ def _kill_python_and_exit_code(p):
     returncode = p.wait()
     return data, returncode
 
+
 class CmdLineTest(unittest.TestCase):
     def test_directories(self):
         assert_python_failure('.')
         assert_python_failure('< .')
 
     def verify_valid_flag(self, cmd_line):
-        rc, out, err = assert_python_ok(*cmd_line)
+        rc, out, err = assert_python_ok(cmd_line)
         self.assertTrue(out == b'' or out.endswith(b'\n'))
         self.assertNotIn(b'Traceback', out)
         self.assertNotIn(b'Traceback', err)
+        return out
 
-    def test_optimize(self):
-        self.verify_valid_flag('-O')
-        self.verify_valid_flag('-OO')
+    def test_help(self):
+        self.verify_valid_flag('-h')
+        self.verify_valid_flag('-?')
+        out = self.verify_valid_flag('--help')
+        lines = out.splitlines()
+        self.assertIn(b'usage', lines[0])
+        self.assertNotIn(b'PYTHONHOME', out)
+        self.assertNotIn(b'-X dev', out)
+        self.assertLess(len(lines), 50)
 
-    def test_site_flag(self):
-        self.verify_valid_flag('-S')
+    def test_help_env(self):
+        out = self.verify_valid_flag('--help-env')
+        self.assertIn(b'PYTHONHOME', out)
+
+    def test_help_xoptions(self):
+        out = self.verify_valid_flag('--help-xoptions')
+        self.assertIn(b'-X dev', out)
 
-    def test_usage(self):
-        rc, out, err = assert_python_ok('-h')
+    def test_help_all(self):
+        out = self.verify_valid_flag('--help-all')
         lines = out.splitlines()
         self.assertIn(b'usage', lines[0])
+        self.assertIn(b'PYTHONHOME', out)
+        self.assertIn(b'-X dev', out)
+
         # The first line contains the program name,
         # but the rest should be ASCII-only
         b''.join(lines[1:]).decode('ascii')
 
+    def test_optimize(self):
+        self.verify_valid_flag('-O')
+        self.verify_valid_flag('-OO')
+
+    def test_site_flag(self):
+        self.verify_valid_flag('-S')
+
     def test_version(self):
         version = ('Python %d.%d' % sys.version_info[:2]).encode("ascii")
         for switch in '-V', '--version', '-VV':
@@ -93,7 +116,7 @@ def get_xoptions(*args):
     def test_unknown_xoptions(self):
         rc, out, err = assert_python_failure('-X', 'blech')
         self.assertIn(b'Unknown value for option -X', err)
-        msg = b'Fatal Python error: Unknown value for option -X'
+        msg = b'Fatal Python error: Unknown value for option -X (see --help-xoptions)'
         self.assertEqual(err.splitlines().count(msg), 1)
         self.assertEqual(b'', out)
 
@@ -137,7 +160,6 @@ def test_xoption_frozen_modules(self):
         }
         for raw, expected in tests:
             cmd = ['-X', f'frozen_modules{raw}',
-                   #'-c', 'import os; print(os.__spec__.loader.__name__, end="")']
                    '-c', 'import os; print(os.__spec__.loader, end="")']
             with self.subTest(raw):
                 res = assert_python_ok(*cmd)
@@ -170,7 +192,6 @@ def test_relativedir_bug46421(self):
         # Test `python -m unittest` with a relative directory beginning with ./
         # Note: We have to switch to the project's top module's directory, as per
         # the python unittest wiki. We will switch back when we are done.
-        defaultwd = os.getcwd()
         projectlibpath = os.path.dirname(__file__).removesuffix("test")
         with os_helper.change_cwd(projectlibpath):
             # Testing with and without ./
@@ -250,7 +271,6 @@ def test_invalid_utf8_arg(self):
         #
         # Test with default config, in the C locale, in the Python UTF-8 Mode.
         code = 'import sys, os; s=os.fsencode(sys.argv[1]); print(ascii(s))'
-        base_cmd = [sys.executable, '-c', code]
 
         def run_default(arg):
             cmd = [sys.executable, '-c', code, arg]
@@ -895,6 +915,7 @@ def test_sys_flags_not_set(self):
             PYTHONSAFEPATH="1",
         )
 
+
 class SyntaxErrorTests(unittest.TestCase):
     def check_string(self, code):
         proc = subprocess.run([sys.executable, "-"], input=code,

Misc/NEWS.d/next/Core and Builtins/2022-01-02-14-53-59.bpo-46142.WayjgT.rst

@@ -0,0 +1,3 @@
+Make ``--help`` output shorter by moving some info to the new
+``--help-env`` and ``--help-xoptions`` command-line options.
+Also add ``--help-all`` option to print complete usage.

Misc/python.man

@@ -84,6 +84,19 @@ python \- an interpreted, interactive, object-oriented programming language
 |
 .I never
 ]
+.br
+       [
+.B \--help
+]
+[
+.B \--help-env
+]
+[
+.B \--help-xoptions
+]
+[
+.B \--help-all
+]
 .br
        [
 .B \-c
@@ -149,6 +162,16 @@ the behavior of the interpreter.
 .B \-h ", " \-? ", "\-\-help
 Prints the usage for the interpreter executable and exits.
 .TP
+.B "\-\-help\-env"
+Prints help about Python-specific environment variables and exits.
+.TP
+.B "\-\-help\-xoptions"
+Prints help about implementation-specific \fB\-X\fP options and exits.
+.TP
+.TP
+.B "\-\-help\-all"
+Prints complete usage information and exits.
+.TP
 .B \-i
 When a script is passed as first argument or the \fB\-c\fP option is
 used, enter interactive mode after executing the script or the
@@ -287,7 +310,7 @@ a regular expression on the warning message.
 
 .TP
 .BI "\-X " option
-Set implementation specific option. The following options are available:
+Set implementation-specific option. The following options are available:
 
     -X faulthandler: enable faulthandler
 
@@ -332,7 +355,7 @@ Set implementation specific option. The following options are available:
        files are desired as well as suppressing the extra visual location indicators
        when the interpreter displays tracebacks.
 
-    -X frozen_modules=[on|off]: whether or not frozen modules should be used
+    -X frozen_modules=[on|off]: whether or not frozen modules should be used.
        The default is "on" (or "off" if you are running a local build).
 
 .TP

Python/getopt.c

@@ -44,8 +44,12 @@ static const wchar_t *opt_ptr = L"";
 #define SHORT_OPTS L"bBc:dEhiIJm:OPqRsStuvVW:xX:?"
 
 static const _PyOS_LongOption longopts[] = {
+    /* name, has_arg, val (used in switch in initconfig.c) */
     {L"check-hash-based-pycs", 1, 0},
-    {NULL, 0, 0},
+    {L"help-all", 0, 1},
+    {L"help-env", 0, 2},
+    {L"help-xoptions", 0, 3},
+    {NULL, 0, -1},                     /* sentinel */
 };