[Python-checkins] gh-90300: split --help output into separate options (GH-30331)

miss-islington webhook-mailer at python.org
Tue Jun 14 15:15:50 EDT 2022

• Previous message (by thread): [Python-checkins] [3.11] gh-91162: Support splitting of unpacked arbitrary-length tuple over TypeVar and TypeVarTuple parameters (alt) (GH-93412) (GH-93746)
• Next message (by thread): [Python-checkins] gh-92914: Round the allocated size for lists up to the even number (GH-92915)
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

---

https://github.com/python/cpython/commit/cbfbe248e304cc1936f04d3a3d2c3b115dea8663
commit: cbfbe248e304cc1936f04d3a3d2c3b115dea8663
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022年06月14日T12:15:42-07:00
summary:
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 8aa9d40b00741213c5a53b1ae15509998893ae31)
Co-authored-by: Éric <earaujo at caravan.coop>
files:
A Misc/NEWS.d/next/Core and Builtins/2022-01-02-14-53-59.bpo-46142.WayjgT.rst
M Doc/using/cmdline.rst
M Lib/test/test_cmd_line.py
M Misc/python.man
M Python/getopt.c
M Python/initconfig.c
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 668459f352008..af757d1e4ceb8 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -183,6 +183,8 @@ automatically enabled, if available on your platform (see
 Automatic enabling of tab-completion and history editing.
 
 
+.. _using-on-generic-options:
+
 Generic options
 ~~~~~~~~~~~~~~~
 
@@ -190,8 +192,28 @@ Generic options
 -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
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/Lib/test/test_cmd_line.py b/Lib/test/test_cmd_line.py
index 5a9e14bbd3200..83a357fe6b37d 100644
--- a/Lib/test/test_cmd_line.py
+++ b/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,
diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-01-02-14-53-59.bpo-46142.WayjgT.rst b/Misc/NEWS.d/next/Core and Builtins/2022-01-02-14-53-59.bpo-46142.WayjgT.rst
new file mode 100644
index 0000000000000..3c62c54289946
--- /dev/null
+++ b/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.
diff --git a/Misc/python.man b/Misc/python.man
index f6c28647a4e99..c979f5dff3cab 100644
--- a/Misc/python.man
+++ b/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
diff --git a/Python/getopt.c b/Python/getopt.c
index fcea60759d12c..4135bf1446ecf 100644
--- a/Python/getopt.c
+++ b/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 */
 };
 
 
diff --git a/Python/initconfig.c b/Python/initconfig.c
index 5c9c7ee41e753..86dcdd9a8bd6b 100644
--- a/Python/initconfig.c
+++ b/Python/initconfig.c
@@ -28,9 +28,10 @@
 static const char usage_line[] =
 "usage: %ls [option] ... [-c cmd | -m mod | file | -] [arg] ...\n";
 
-/* Long usage message, split into parts < 512 bytes */
-static const char usage_1[] = "\
-Options and arguments (and corresponding environment variables):\n\
+/* Long help message */
+/* Lines sorted by option name; keep in sync with usage_envvars* below */
+static const char usage_help[] = "\
+Options (and corresponding environment variables):\n\
 -b : issue warnings about str(bytes_instance), str(bytearray_instance)\n\
 and comparing bytes/bytearray with str. (-bb: issue errors)\n\
 -B : don't write .pyc files on import; also PYTHONDONTWRITEBYTECODE=x\n\
@@ -39,8 +40,6 @@ Options and arguments (and corresponding environment variables):\n\
 debug builds); also PYTHONDEBUG=x\n\
 -E : ignore PYTHON* environment variables (such as PYTHONPATH)\n\
 -h : print this help message and exit (also -? or --help)\n\
-";
-static const char usage_2[] = "\
 -i : inspect interactively after running script; forces a prompt even\n\
 if stdin does not appear to be a terminal; also PYTHONINSPECT=x\n\
 -I : isolate Python from the user's environment (implies -E and -s)\n\
@@ -53,8 +52,6 @@ static const char usage_2[] = "\
 -q : don't print version and copyright messages on interactive startup\n\
 -s : don't add user site directory to sys.path; also PYTHONNOUSERSITE\n\
 -S : don't imply 'import site' on initialization\n\
-";
-static const char usage_3[] = "\
 -u : force the stdout and stderr streams to be unbuffered;\n\
 this option has no effect on stdin; also PYTHONUNBUFFERED=x\n\
 -v : verbose (trace import statements); also PYTHONVERBOSE=x\n\
@@ -64,55 +61,72 @@ 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\
- -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\
- interactive interpreter. This only works on debug builds\n\
- -X tracemalloc: start tracing Python memory allocations using the\n\
- tracemalloc module. By default, only the most recent frame is stored in a\n\
- traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a\n\
- traceback limit of NFRAME frames\n\
- -X importtime: show how long each import takes. It shows module name,\n\
- cumulative time (including nested imports) and self time (excluding\n\
- nested imports). Note that its output may be broken in multi-threaded\n\
- application. Typical usage is python3 -X importtime -c 'import asyncio'\n\
- -X dev: enable CPython's \"development mode\", introducing additional runtime\n\
- checks which are too expensive to be enabled by default. Effect of the\n\
- developer mode:\n\
- * Add default warning filter, as -W default\n\
- * Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks()\n\
- C function\n\
- * Enable the faulthandler module to dump the Python traceback on a crash\n\
- * Enable asyncio debug mode\n\
- * Set the dev_mode attribute of sys.flags to True\n\
- * io.IOBase destructor logs close() exceptions\n\
- -X utf8: enable UTF-8 mode for operating system interfaces, overriding the default\n\
- locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when it would\n\
- otherwise activate automatically)\n\
- -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the\n\
- given directory instead of to the code tree\n\
- -X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None'\n\
- -X no_debug_ranges: disable the inclusion of the tables mapping extra location \n\
- information (end line, start column offset and end column offset) to every \n\
- instruction in code objects. This is useful when smaller code objects and pyc \n\
- files are desired as well as suppressing the extra visual location indicators \n\
- 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\
+-X opt : set implementation-specific option\n\
 --check-hash-based-pycs always|default|never:\n\
- control how Python invalidates hash-based .pyc files\n\
-";
-static const char usage_4[] = "\
+ control how Python invalidates hash-based .pyc files\n\
+--help-env : print help about Python environment variables and exit\n\
+--help-xoptions : print help about implementation-specific -X options and exit\n\
+--help-all : print complete help information and exit\n\
+Arguments:\n\
 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\
-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\
+arg ...: arguments passed to program in sys.argv[1:]\n\
 ";
-static const char usage_5[] =
+
+static const char usage_xoptions[] = "\
+The following implementation-specific options are available:\n\
+\n\
+-X faulthandler: enable faulthandler\n\
+\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\
+ interactive interpreter. This only works on debug builds\n\
+\n\
+-X tracemalloc: start tracing Python memory allocations using the\n\
+ tracemalloc module. By default, only the most recent frame is stored in a\n\
+ traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a\n\
+ traceback limit of NFRAME frames\n\
+\n\
+-X importtime: show how long each import takes. It shows module name,\n\
+ cumulative time (including nested imports) and self time (excluding\n\
+ nested imports). Note that its output may be broken in multi-threaded\n\
+ application. Typical usage is python3 -X importtime -c 'import asyncio'\n\
+\n\
+-X dev: enable CPython's \"development mode\", introducing additional runtime\n\
+ checks which are too expensive to be enabled by default. Effect of the\n\
+ developer mode:\n\
+ * Add default warning filter, as -W default\n\
+ * Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks()\n\
+ C function\n\
+ * Enable the faulthandler module to dump the Python traceback on a crash\n\
+ * Enable asyncio debug mode\n\
+ * Set the dev_mode attribute of sys.flags to True\n\
+ * io.IOBase destructor logs close() exceptions\n\
+\n\
+-X utf8: enable UTF-8 mode for operating system interfaces, overriding the default\n\
+ locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when it would\n\
+ otherwise activate automatically)\n\
+\n\
+-X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the\n\
+ given directory instead of to the code tree\n\
+\n\
+-X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None'\n\
+\n\
+-X no_debug_ranges: disable the inclusion of the tables mapping extra location \n\
+ information (end line, start column offset and end column offset) to every \n\
+ instruction in code objects. This is useful when smaller code objects and pyc \n\
+ files are desired as well as suppressing the extra visual location indicators \n\
+ when the interpreter displays tracebacks.\n\
+\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).";
+
+/* Envvars that don't have equivalent command-line options are listed first */
+static const char usage_envvars[] =
+"Environment variables that change behavior:\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"
 "PYTHONSAFEPATH: don't prepend a potentially unsafe path to sys.path.\n"
 "PYTHONHOME : alternate <prefix> directory (or <prefix>%lc<exec_prefix>).\n"
 " The default module search path uses %s.\n"
@@ -120,8 +134,7 @@ static const char usage_5[] =
 "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[] =
+"PYTHONFAULTHANDLER: dump the Python traceback on fatal errors.\n"
 "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"
@@ -141,7 +154,16 @@ static const char usage_6[] =
 " tables mapping extra location information (end line, start column offset \n"
 " and end column offset) to every instruction in code objects. This is useful \n"
 " when smaller code objects and pyc files are desired as well as suppressing the \n"
-" extra visual location indicators when the interpreter displays tracebacks.\n";
+" extra visual location indicators when the interpreter displays tracebacks.\n"
+"These variables have equivalent command-line parameters (see --help for details):\n"
+"PYTHONDEBUG : enable parser debug mode (-d)\n"
+"PYTHONDONTWRITEBYTECODE : don't write .pyc files (-B)\n"
+"PYTHONINSPECT : inspect interactively after running script (-i)\n"
+"PYTHONNOUSERSITE : disable user site directory (-s)\n"
+"PYTHONOPTIMIZE : enable level 1 optimizations (-O)\n"
+"PYTHONUNBUFFERED : disable stdout/stderr buffering (-u)\n"
+"PYTHONVERBOSE : trace import statements (-v)\n"
+"PYTHONWARNINGS=arg : warning control (-W arg)\n";
 
 #if defined(MS_WINDOWS)
 # define PYTHONHOMEHELP "<prefix>\\python{major}{minor}"
@@ -2084,7 +2106,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 --help-xoptions)");
 }
 
 if (config_get_xoption(config, L"showrefcount")) {
@@ -2237,15 +2259,32 @@ config_usage(int error, const wchar_t* program)
 if (error)
 fprintf(f, "Try `python -h' for more information.\n");
 else {
- 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_help, f);
 }
 }
 
+static void
+config_envvars_usage()
+{
+ printf(usage_envvars, (wint_t)DELIM, (wint_t)DELIM, PYTHONHOMEHELP);
+}
+
+static void
+config_xoptions_usage()
+{
+ puts(usage_xoptions);
+}
+
+static void
+config_complete_usage(const wchar_t* program)
+{
+ config_usage(0, program);
+ puts("\n");
+ config_envvars_usage();
+ puts("\n");
+ config_xoptions_usage();
+}
+
 
 /* Parse the command line arguments */
 static PyStatus
@@ -2297,9 +2336,9 @@ config_parse_cmdline(PyConfig *config, PyWideStringList *warnoptions,
 }
 
 switch (c) {
+ // Integers represent long options, see Python/getopt.c
 case 0:
- // Handle long option.
- assert(longindex == 0); // Only one long option now.
+ // check-hash-based-pycs
 if (wcscmp(_PyOS_optarg, L"always") == 0
 || wcscmp(_PyOS_optarg, L"never") == 0
 || wcscmp(_PyOS_optarg, L"default") == 0)
@@ -2317,6 +2356,21 @@ config_parse_cmdline(PyConfig *config, PyWideStringList *warnoptions,
 }
 break;
 
+ case 1:
+ // help-all
+ config_complete_usage(program);
+ return _PyStatus_EXIT(0);
+
+ case 2:
+ // help-env
+ config_envvars_usage();
+ return _PyStatus_EXIT(0);
+
+ case 3:
+ // help-xoptions
+ config_xoptions_usage();
+ return _PyStatus_EXIT(0);
+
 case 'b':
 config->bytes_warning++;
 break;

---

• Previous message (by thread): [Python-checkins] [3.11] gh-91162: Support splitting of unpacked arbitrary-length tuple over TypeVar and TypeVarTuple parameters (alt) (GH-93412) (GH-93746)
• Next message (by thread): [Python-checkins] gh-92914: Round the allocated size for lists up to the even number (GH-92915)
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

---

More information about the Python-checkins mailing list