gh-90300: Improve the Python CLI help output (GH-115853)

* document equivalent command-line options for all environment variables
* document equivalent environment variables for all command-line options
* reduce the size of variable and option descriptions to minimum
* remove the ending period in single-sentence descriptions

Co-authored-by: Éric <merwok@netwok.org>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

1 files changed, 40 insertions, 78 deletions

diff --git a/Python/initconfig.c b/Python/initconfig.c
index bbd611f..95234ee 100644
--- a/Python/initconfig.c
+++ b/Python/initconfig.c
@@ -161,7 +161,7 @@ Options (and corresponding environment variables):\n\
 -P     : don't prepend a potentially unsafe path to sys.path; also\n\
          PYTHONSAFEPATH\n\
 -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 add user site directory to sys.path; also PYTHONNOUSERSITE=x\n\
 -S     : don't imply 'import site' on initialization\n\
 -u     : force the stdout and stderr streams to be unbuffered;\n\
          this option has no effect on stdin; also PYTHONUNBUFFERED=x\n\
@@ -187,67 +187,41 @@ arg ...: arguments passed to program in sys.argv[1:]\n\
 
 static const char usage_xoptions[] = "\
 The following implementation-specific options are available:\n\
--X cpu_count=[n|default]: Override the return value of os.cpu_count(),\n\
-         os.process_cpu_count(), and multiprocessing.cpu_count().  This can\n\
-         help users who need to limit resources in a container.\n\
--X dev : enable CPython's \"development mode\", introducing additional runtime\n\
-         checks which are too expensive to be enabled by default.  Effect of\n\
-         the developer mode:\n\
-          * Add default warning filter, as -W default\n\
-          * Install debug hooks on memory allocators: see the\n\
-            PyMem_SetupDebugHooks() C function\n\
-          * Enable the faulthandler module to dump the Python traceback on\n\
-            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 faulthandler: enable faulthandler\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 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\n\
-         multi-threaded application.\n\
-         Typical usage is python3 -X importtime -c 'import asyncio'\n\
--X int_max_str_digits=number: limit the size of int<->str conversions.\n\
-         This helps avoid denial of service attacks when parsing untrusted\n\
-         data.  The default is sys.int_info.default_max_str_digits.\n\
-         0 disables.\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\n\
-         every instruction in code objects.  This is useful when smaller code\n\
-         objects and pyc files are desired as well as suppressing the extra\n\
-         visual location indicators when the interpreter displays tracebacks.\n\
--X perf: activate support for the Linux \"perf\" profiler by activating the\n\
-         \"perf\" trampoline.  When this option is activated, the Linux \"perf\"\n\
-         profiler will be able to report Python calls.  This option is only\n\
-         available on some platforms and will do nothing if is not supported\n\
-         on the current system.  The default value is \"off\".\n\
+-X cpu_count=N: override the return value of os.cpu_count();\n\
+         -X cpu_count=default cancels overriding; also PYTHON_CPU_COUNT\n\
+-X dev : enable Python Development Mode; also PYTHONDEVMODE\n\
+-X faulthandler: dump the Python traceback on fatal errors;\n\
+         also PYTHONFAULTHANDLER\n\
+-X frozen_modules=[on|off]: whether to use frozen modules; the default is \"on\"\n\
+         for installed Python and \"off\" for a local build;\n\
+         also PYTHON_FROZEN_MODULES\n\
+-X importtime: show how long each import takes; also PYTHONPROFILEIMPORTTIME\n\
+-X int_max_str_digits=N: limit the size of int<->str conversions;\n\
+         0 disables the limit; also PYTHONINTMAXSTRDIGITS\n\
+-X no_debug_ranges: don't include extra location information in code objects;\n\
+         also PYTHONNODEBUGRANGES\n\
+-X perf: support the Linux \"perf\" profiler; also PYTHONPERFSUPPORT=1\n\
 "
 #ifdef Py_DEBUG
-"-X presite=package.module: import this module before site.py is run.\n"
+"-X presite=MOD: import this module before site; also PYTHON_PRESITE\n"
 #endif
 "\
--X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted\n\
-         at the given directory instead of to the code tree\n\
+-X pycache_prefix=PATH: write .pyc files to a parallel tree instead of to the\n\
+         code tree; also PYTHONPYCACHEPREFIX\n\
 "
 #ifdef Py_STATS
-"-X pystats: Enable pystats collection at startup.\n"
+"-X pystats: enable pystats collection at startup; also PYTHONSTATS\n"
 #endif
 "\
 -X showrefcount: output the total reference count and number of used\n\
          memory blocks when the program finishes or after each statement in\n\
-         the 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\n\
-         in a traceback of a trace.  Use -X tracemalloc=NFRAME to start\n\
-         tracing with a traceback limit of NFRAME frames\n\
--X utf8: enable UTF-8 mode for operating system interfaces, overriding the\n\
-         default locale-aware mode.  -X utf8=0 explicitly disables UTF-8 mode\n\
-         (even when it would otherwise activate automatically)\n\
--X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None'\
-"
-;
+         the interactive interpreter; only works on debug builds\n\
+-X tracemalloc[=N]: trace Python memory allocations; N sets a traceback limit\n\
+         of N frames (default: 1); also PYTHONTRACEMALLOC=N\n\
+-X utf8[=0|1]: enable (1) or disable (0) UTF-8 mode; also PYTHONUTF8\n\
+-X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None';\n\
+         also PYTHONWARNDEFAULTENCODING\
+";
 
 /* Envvars that don't have equivalent command-line options are listed first */
 static const char usage_envvars[] =
@@ -257,9 +231,9 @@ static const char usage_envvars[] =
 "                  default module search path.  The result is sys.path.\n"
 "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"
-"PYTHONIOENCODING: Encoding[:errors] used for stdin/stdout/stderr.\n"
+"PYTHONPLATLIBDIR: override sys.platlibdir\n"
+"PYTHONCASEOK    : ignore case in 'import' statements (Windows)\n"
+"PYTHONIOENCODING: encoding[:errors] used for stdin/stdout/stderr\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\n"
 "                  set to an integer in the range [0,4294967295] to get hash\n"
@@ -280,39 +254,27 @@ static const char usage_envvars[] =
 "PYTHON_HISTORY  : the location of a .python_history file.\n"
 "\n"
 "These variables have equivalent command-line options (see --help for details):\n"
-"PYTHON_CPU_COUNT: Overrides the return value of os.process_cpu_count(),\n"
-"                  os.cpu_count(), and multiprocessing.cpu_count() if set to\n"
-"                  a positive integer. (-X cpu_count)\n"
+"PYTHON_CPU_COUNT: override the return value of os.cpu_count() (-X cpu_count)\n"
 "PYTHONDEBUG     : enable parser debug mode (-d)\n"
-"PYTHONDEVMODE   : enable the development mode (-X dev)\n"
+"PYTHONDEVMODE   : enable Python Development Mode (-X dev)\n"
 "PYTHONDONTWRITEBYTECODE: don't write .pyc files (-B)\n"
 "PYTHONFAULTHANDLER: dump the Python traceback on fatal errors (-X faulthandler)\n"
-"PYTHON_FROZEN_MODULES: if this variable is set, it determines whether or not\n"
-"                  frozen modules should be used.  The default is \"on\" (or\n"
-"                  \"off\" if you are running a local build).\n"
+"PYTHON_FROZEN_MODULES: whether to use frozen modules; the default is \"on\"\n"
+"                  for installed Python and \"off\" for a local build\n"
 "                  (-X frozen_modules)\n"
 #ifdef Py_GIL_DISABLED
 "PYTHON_GIL      : when set to 0, disables the GIL (-X gil)\n"
 #endif
 "PYTHONINSPECT   : inspect interactively after running script (-i)\n"
-"PYTHONINTMAXSTRDIGITS: limits the maximum digit characters in an int value\n"
-"                  when converting from a string and when converting an int\n"
-"                  back to a str.  A value of 0 disables the limit.\n"
-"                  Conversions to or from bases 2, 4, 8, 16, and 32 are never\n"
-"                  limited.\n"
-"                  (-X int_max_str_digits=number)\n"
-"PYTHONNODEBUGRANGES: if this variable is set, it disables the inclusion of\n"
-"                  the tables mapping extra location information (end line,\n"
-"                  start column offset and end column offset) to every\n"
-"                  instruction in code objects.  This is useful when smaller\n"
-"                  code objects and pyc files are desired as well as\n"
-"                  suppressing the extra visual location indicators when the\n"
-"                  interpreter displays tracebacks. (-X no_debug_ranges)\n"
+"PYTHONINTMAXSTRDIGITS: limit the size of int<->str conversions;\n"
+"                  0 disables the limit (-X int_max_str_digits=N)\n"
+"PYTHONNODEBUGRANGES: don't include extra location information in code objects\n"
+"                  (-X no_debug_ranges)\n"
 "PYTHONNOUSERSITE: disable user site directory (-s)\n"
 "PYTHONOPTIMIZE  : enable level 1 optimizations (-O)\n"
 "PYTHONPERFSUPPORT: support the Linux \"perf\" profiler (-X perf)\n"
 #ifdef Py_DEBUG
-"PYTHON_PRESITE=pkg.mod: import this module before site.py is run (-X presite)\n"
+"PYTHON_PRESITE: import this module before site (-X presite)\n"
 #endif
 "PYTHONPROFILEIMPORTTIME: show how long each import takes (-X importtime)\n"
 "PYTHONPYCACHEPREFIX: root directory for bytecode cache (pyc) files\n"
@@ -323,11 +285,11 @@ static const char usage_envvars[] =
 #endif
 "PYTHONTRACEMALLOC: trace Python memory allocations (-X tracemalloc)\n"
 "PYTHONUNBUFFERED: disable stdout/stderr buffering (-u)\n"
-"PYTHONUTF8      : if set to 1, enable the UTF-8 mode (-X utf8)\n"
+"PYTHONUTF8      : control the UTF-8 mode (-X utf8)\n"
 "PYTHONVERBOSE   : trace import statements (-v)\n"
 "PYTHONWARNDEFAULTENCODING: enable opt-in EncodingWarning for 'encoding=None'\n"
 "                  (-X warn_default_encoding)\n"
-"PYTHONWARNINGS=arg: warning control (-W arg)\n"
+"PYTHONWARNINGS  : warning control (-W)\n"
 ;
 
 #if defined(MS_WINDOWS)