gh-90300: split --help output into separate options

Doc/using/cmdline.rst

@@ -183,15 +183,21 @@ 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 related
+   environment variables.
+
+.. cmdoption:: --help-env
 
+   Print a short description of additional environment variables.
 
 .. cmdoption:: -V
                --version
@@ -212,6 +218,10 @@ Generic options
    .. versionadded:: 3.6
       The ``-VV`` option.
 
+   .. versionadded:: 3.11
+      The ``--help-env`` option.
+
+
 .. _using-on-misc-options:
 
 Miscellaneous options
@@ -436,6 +446,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
@@ -447,6 +458,7 @@ Miscellaneous options
    Reserved for various implementation-specific options.  CPython currently
    defines the following possible values:
 
+   * ``-X help`` to print a short description of all X options;
    * ``-X faulthandler`` to enable :mod:`faulthandler`;
    * ``-X showrefcount`` to output the total reference count and number of used
      memory blocks when the program finishes or after each statement in the
@@ -528,6 +540,9 @@ Miscellaneous options
    .. versionadded:: 3.11
       The ``-X frozen_modules`` option.
 
+   .. versionadded:: 3.11
+      The ``-X help`` option.
+
 
 Options you shouldn't use
 ~~~~~~~~~~~~~~~~~~~~~~~~~

Lib/test/test_cmd_line.py

@@ -37,6 +37,14 @@ def verify_valid_flag(self, cmd_line):
         self.assertNotIn(b'Traceback', out)
         self.assertNotIn(b'Traceback', err)
 
+    def test_help(self):
+        self.verify_valid_flag('-h')
+        self.verify_valid_flag('-?')
+        self.verify_valid_flag('--help')
+
+    def test_help_env(self):
+        self.verify_valid_flag('--help-env')
+
     def test_optimize(self):
         self.verify_valid_flag('-O')
         self.verify_valid_flag('-OO')
@@ -89,12 +97,20 @@ def get_xoptions(*args):
     @unittest.skipIf(interpreter_requires_environment(),
                      'Cannot run -E tests when PYTHON env vars are required.')
     def test_unknown_xoptions(self):
-        rc, out, err = assert_python_failure('-X', 'blech')
+        _, 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 -X help)'
         self.assertEqual(err.splitlines().count(msg), 1)
         self.assertEqual(b'', out)
 
+    @unittest.skipIf(interpreter_requires_environment(),
+                     'Cannot run -E tests when PYTHON env vars are required.')
+    def test_xoptions_help(self):
+        _, out, err = assert_python_ok('-X', 'help')
+        self.assertIn(b'implementation-specific options are available', out)
+        self.assertIn(b'-X faulthandler: enable faulthandler', out)
+        self.assertEqual(b'', err)
+
     def test_showrefcount(self):
         def run_python(*args):
             # this is similar to assert_python_ok but doesn't strip
@@ -234,7 +250,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]

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

@@ -0,0 +1,2 @@
+Make ``--help`` output shorter by moving some info to the new
+``--help-env`` and ``-X help`` options.

Misc/python.man

@@ -66,10 +66,10 @@ python \- an interpreted, interactive, object-oriented programming language
 .B \-x
 ]
 [
-[
 .B \-X
 .I option
 ]
+[
 .B \-?
 ]
 .br
@@ -81,6 +81,16 @@ python \- an interpreted, interactive, object-oriented programming language
 |
 .I never
 ]
+.br
+       [
+.B \--help
+]
+[
+.B \--help-env
+]
+[
+.B \-X help
+]
 .br
        [
 .B \-c
@@ -146,6 +156,9 @@ the behavior of the interpreter.
 .B \-h ", " \-? ", "\-\-help
 Prints the usage for the interpreter executable and exits.
 .TP
+.B \-\-help\-env
+Prints help about environment variables 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
@@ -279,7 +292,9 @@ 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 help: show help about available options
 
     -X faulthandler: enable faulthandler
 

Python/getopt.c

@@ -45,6 +45,7 @@ static const wchar_t *opt_ptr = L"";
 
 static const _PyOS_LongOption longopts[] = {
     {L"check-hash-based-pycs", 1, 0},
+    {L"help-env", 0, 0},
     {NULL, 0, 0},
 };
 

Python/initconfig.c

@@ -63,8 +63,20 @@ static const char usage_3[] = "\
 -W arg : warning control; arg is action:message:category:module:lineno\n\
          also PYTHONWARNINGS=arg\n\
 -x     : skip first line of source, allowing use of non-Unix forms of #!cmd\n\
--X opt : set implementation-specific option. The following options are available:\n\
-\n\
+-X opt : set implementation-specific option (see details with -X help)\n\
+--help-env : print help about other environment variables\n\
+--check-hash-based-pycs always|default|never :\n\
+         control how Python invalidates hash-based .pyc files\n\
+";
+static const char usage_4[] = "\
+file   : program read from script file\n\
+-      : program read from stdin (default; interactive mode if a tty)\n\
+arg ...: arguments passed to program in sys.argv[1:]\n\
+";
+
+static const char usage_xoptions[] = "\
+The following implementation-specific options are available:\n\
+         -X help: show this help\n\
          -X faulthandler: enable faulthandler\n\
          -X showrefcount: output the total reference count and number of used\n\
              memory blocks when the program finishes or after each statement in the\n\
@@ -99,28 +111,22 @@ static const char usage_3[] = "\
             when the interpreter displays tracebacks.\n\
          -X frozen_modules=[on|off]: whether or not frozen modules should be used.\n\
             The default is \"on\" (or \"off\" if you are running a local build).\n\
-\n\
---check-hash-based-pycs always|default|never:\n\
-    control how Python invalidates hash-based .pyc files\n\
 ";
-static const char usage_4[] = "\
-file   : program read from script file\n\
--      : program read from stdin (default; interactive mode if a tty)\n\
-arg ...: arguments passed to program in sys.argv[1:]\n\n\
-Other environment variables:\n\
+static const char usage_envvars1[] = "\
+Environment variables that change behavior (see also --help):\n\
 PYTHONSTARTUP: file executed on interactive startup (no default)\n\
 PYTHONPATH   : '%lc'-separated list of directories prefixed to the\n\
                default module search path.  The result is sys.path.\n\
 ";
-static const char usage_5[] =
+static const char usage_envvars2[] =
 "PYTHONHOME   : alternate <prefix> directory (or <prefix>%lc<exec_prefix>).\n"
 "               The default module search path uses %s.\n"
 "PYTHONPLATLIBDIR : override sys.platlibdir.\n"
 "PYTHONCASEOK : ignore case in 'import' statements (Windows).\n"
 "PYTHONUTF8: if set to 1, enable the UTF-8 mode.\n"
 "PYTHONIOENCODING: Encoding[:errors] used for stdin/stdout/stderr.\n"
 "PYTHONFAULTHANDLER: dump the Python traceback on fatal errors.\n";
-static const char usage_6[] =
+static const char usage_envvars3[] =
 "PYTHONHASHSEED: if this variable is set to 'random', a random value is used\n"
 "   to seed the hashes of str and bytes objects.  It can also be set to an\n"
 "   integer in the range [0,4294967295] to get hash values with a\n"
@@ -2005,6 +2011,7 @@ _PyConfig_InitImportConfig(PyConfig *config)
 // set, like -X showrefcount which requires a debug build. In this case unknown
 // options are silently ignored.
 const wchar_t* known_xoptions[] = {
+    L"help",
     L"faulthandler",
     L"showrefcount",
     L"tracemalloc",
@@ -2060,7 +2067,7 @@ config_read(PyConfig *config, int compute_path_config)
     /* -X options */
     const wchar_t* option = _Py_check_xoptions(&config->xoptions, known_xoptions);
     if (option != NULL) {
-        return PyStatus_Error("Unknown value for option -X");
+        return PyStatus_Error("Unknown value for option -X (see -X help)");
     }
 
     if (config_get_xoption(config, L"showrefcount")) {
@@ -2216,12 +2223,25 @@ config_usage(int error, const wchar_t* program)
         fputs(usage_1, f);
         fputs(usage_2, f);
         fputs(usage_3, f);
-        fprintf(f, usage_4, (wint_t)DELIM);
-        fprintf(f, usage_5, (wint_t)DELIM, PYTHONHOMEHELP);
-        fputs(usage_6, f);
+        fputs(usage_4, f);
     }
 }
 
+static void
+config_envvars_usage()
+{
+    FILE *f = stdout;
+    fprintf(f, usage_envvars1, (wint_t)DELIM);
+    fprintf(f, usage_envvars2, (wint_t)DELIM, PYTHONHOMEHELP);
+    fputs(usage_envvars3, f);
+}
+
+static void
+config_xoptions_usage()
+{
+    FILE *f = stdout;
+    fputs(usage_xoptions, f);
+}
 
 /* Parse the command line arguments */
 static PyStatus
@@ -2232,6 +2252,7 @@ config_parse_cmdline(PyConfig *config, PyWideStringList *warnoptions,
     const PyWideStringList *argv = &config->argv;
     int print_version = 0;
     const wchar_t* program = config->program_name;
+    const wchar_t* xoption_help;
 
     _PyOS_ResetGetOpt();
     do {
@@ -2274,8 +2295,11 @@ config_parse_cmdline(PyConfig *config, PyWideStringList *warnoptions,
 
         switch (c) {
         case 0:
-            // Handle long option.
-            assert(longindex == 0); // Only one long option now.
+          // Handle long options.
+          assert(longindex < 2);  // Only two long options for now.
+          switch(longindex) {
+          case 0:
+            // check-hash-based-pycs
             if (wcscmp(_PyOS_optarg, L"always") == 0
                 || wcscmp(_PyOS_optarg, L"never") == 0
                 || wcscmp(_PyOS_optarg, L"default") == 0)
@@ -2292,6 +2316,13 @@ config_parse_cmdline(PyConfig *config, PyWideStringList *warnoptions,
                 return _PyStatus_EXIT(2);
             }
             break;
+          case 1:
+            // help-env
+            config_envvars_usage();
+            return _PyStatus_EXIT(0);
+            break;
+          }
+          break;
 
         case 'b':
             config->bytes_warning++;
@@ -2308,7 +2339,6 @@ config_parse_cmdline(PyConfig *config, PyWideStringList *warnoptions,
 
         case 'E':
         case 'I':
-        case 'X':
             /* option handled by _PyPreCmdline_Read() */
             break;
 
@@ -2370,6 +2400,15 @@ config_parse_cmdline(PyConfig *config, PyWideStringList *warnoptions,
             config->use_hash_seed = 0;
             break;
 
+        case 'X':
+            xoption_help = config_get_xoption(config, L"help");
+            if (xoption_help) {
+                config_xoptions_usage();
+                return _PyStatus_EXIT(0);
+            }
+            /* option handled by _PyPreCmdline_Read() */
+            break;
+
         /* This space reserved for other options */
 
         default: