10000 [3.11] gh-90300: Improve the Python CLI help output (GH-115853) (GH-1… · python/cpython@051b8a2 · GitHub
[go: up one dir, main page]
Skip to content

Commit 051b8a2

Browse files
serhiy-storchakamerwokhugovk
authored
[3.11] gh-90300: Improve the Python CLI help output (GH-115853) (GH-117022) (GH-117034)
* 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 (cherry picked from commit b85572c) (cherry picked from commit 4be9fa8) Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
1 parent 1de746f commit 051b8a2

File tree

1 file changed

+31
-62
lines changed

1 file changed

+31
-62
lines changed

‎Python/initconfig.c

Lines changed: 31 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ Options (and corresponding environment variables):\n\
5252
-P : don't prepend a potentially unsafe path to sys.path; also\n\
5353
PYTHONSAFEPATH\n\
5454
-q : don't print version and copyright messages on interactive startup\n\
55-
-s : don't add user site directory to sys.path; also PYTHONNOUSERSITE\n\
55+
-s : don't add user site directory to sys.path; also PYTHONNOUSERSITE=x\n\
5656
-S : don't imply 'import site' on initialization\n\
5757
-u : force the stdout and stderr streams to be unbuffered;\n\
5858
this option has no effect on stdin; also PYTHONUNBUFFERED=x\n\
@@ -78,54 +78,32 @@ arg ...: arguments passed to program in sys.argv[1:]\n\
7878

7979
static const char usage_xoptions[] = "\
8080
The following implementation-specific options are available:\n\
81-
-X dev : enable CPython's \"development mode\", introducing additional runtime\n\
82-
checks which are too expensive to be enabled by default. Effect of\n\
83-
the developer mode:\n\
84-
* Add default warning filter, as -W default\n\
85-
* Install debug hooks on memory allocators: see the\n\
86-
PyMem_SetupDebugHooks() C function\n\
87-
* Enable the faulthandler module to dump the Python traceback on\n\
88-
a crash\n\
89-
* Enable asyncio debug mode\n\
90-
* Set the dev_mode attribute of sys.flags to True\n\
91-
* io.IOBase destructor logs close() exceptions\n\
92-
-X faulthandler: enable faulthandler\n\
93-
-X frozen_modules=[on|off]: whether or not frozen modules should be used.\n\
94-
The default is \"on\" (or \"off\" if you are running a local build).\n\
95-
-X importtime: show how long each import takes. It shows module name,\n\
96-
cumulative time (including nested imports) and self time (excluding\n\
97-
nested imports). Note that its output may be broken in\n\
98-
multi-threaded application.\n\
99-
Typical usage is python3 -X importtime -c 'import asyncio'\n\
100-
-X int_max_str_digits=number: limit the size of int<->str conversions.\n\
101-
This helps avoid denial of service attacks when parsing untrusted\n\
102-
data. The default is sys.int_info.default_max_str_digits.\n\
103-
0 disables.\n\
104-
-X no_debug_ranges: disable the inclusion of the tables mapping extra location\n\
105-
information (end line, start column offset and end column offset) to\n\
106-
every instruction in code objects. This is useful when smaller code\n\
107-
objects and pyc files are desired as well as suppressing the extra\n\
108-
visual location indicators when the interpreter displays tracebacks.\n\
109-
-X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted\n\
110-
at the given directory instead of to the code tree\n\
81+
-X dev : enable Python Development Mode; also PYTHONDEVMODE\n\
82+
-X faulthandler: dump the Python traceback on fatal errors;\n\
83+
also PYTHONFAULTHANDLER\n\
84+
-X frozen_modules=[on|off]: whether to use frozen modules; the default is \"on\"\n\
85+
for installed Python and \"off\" for a local build\n\
86+
-X importtime: show how long each import takes; also PYTHONPROFILEIMPORTTIME\n\
87+
-X int_max_str_digits=N: limit the size of int<->str conversions;\n\
88+
0 disables the limit; also PYTHONINTMAXSTRDIGITS\n\
89+
-X no_debug_ranges: don't include extra location information in code objects;\n\
90+
also PYTHONNODEBUGRANGES\n\
91+
-X pycache_prefix=PATH: write .pyc files to a parallel tree instead of to the\n\
92+
code tree; also PYTHONPYCACHEPREFIX\n\
11193
"
11294
#ifdef Py_STATS
113-
"-X pystats: Enable pystats collection at startup.\n"
95+
"-X pystats: enable pystats collection at startup; also PYTHONSTATS\n"
11496
#endif
11597
"\
11698
-X showrefcount: output the total reference count and number of used\n\
11799
memory blocks when the program finishes or after each statement in\n\
118-
the interactive interpreter. This only works on debug builds\n\
119-
-X tracemalloc: start tracing Python memory allocations using the\n\
120-
tracemalloc module. By default, only the most recent frame is stored\n\
121-
in a traceback of a trace. Use -X tracemalloc=NFRAME to start\n\
122-
tracing with a traceback limit of NFRAME frames\n\
123-
-X utf8: enable UTF-8 mode for operating system interfaces, overriding the\n\
124-
default locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode\n\
125-
(even when it would otherwise activate automatically)\n\
126-
-X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None'\
127-
"
128-
;
100+
the interactive interpreter; only works on debug builds\n\
101+
-X tracemalloc[=N]: trace Python memory allocations; N sets a traceback limit\n\
102+
of N frames (default: 1); also PYTHONTRACEMALLOC=N\n\
103+
-X utf8[=0|1]: enable (1) or disable (0) UTF-8 mode; also PYTHONUTF8\n\
104+
-X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None';\n\
105+
also PYTHONWARNDEFAULTENCODING\
106+
";
129107

130108
/* Envvars that don't have equivalent command-line options are listed first */
131109
static const char usage_envvars[] =
@@ -135,9 +113,9 @@ static const char usage_envvars[] =
135113
" default module search path. The result is sys.path.\n"
136114
"PYTHONHOME : alternate <prefix> directory (or <prefix>%lc<exec_prefix>).\n"
137115
" The default module search path uses %s.\n"
138-
"PYTHONPLATLIBDIR: override sys.platlibdir.\n"
139-
"PYTHONCASEOK : ignore case in 'import' statements (Windows).\n"
140-
"PYTHONIOENCODING: Encoding[:errors] used for stdin/stdout/stderr.\n"
116+
"PYTHONPLATLIBDIR: override sys.platlibdir\n"
117+
"PYTHONCASEOK : ignore case in 'import' statements (Windows)\n"
118+
"PYTHONIOENCODING: encoding[:errors] used for stdin/stdout/stderr\n"
141119
"PYTHONHASHSEED : if this variable is set to 'random', a random value is used\n"
142120
" to seed the hashes of str and bytes objects. It can also be\n"
143121
" set to an integer in the range [0,4294967295] to get hash\n"
@@ -155,23 +133,14 @@ static const char usage_envvars[] =
155133
"\n"
156134
"These variables have equivalent command-line options (see --help for details):\n"
157135
"PYTHONDEBUG : enable parser debug mode (-d)\n"
158-
"PYTHONDEVMODE : enable the development mode (-X dev)\n"
136+
"PYTHONDEVMODE : enable Python Development Mode (-X dev)\n"
159137
"PYTHONDONTWRITEBYTECODE: don't write .pyc files (-B)\n"
160138
"PYTHONFAULTHANDLER: dump the Python traceback on fatal errors (-X faulthandler)\n"
161139
"PYTHONINSPECT : inspect interactively after running script (-i)\n"
162-
"PYTHONINTMAXSTRDIGITS: limits the maximum digit characters in an int value\n"
163-
" when converting from a string and when converting an int\n"
164-
" back to a str. A value of 0 disables the limit.\n"
165-
" Conversions to or from bases 2, 4, 8, 16, and 32 are never\n"
166-
" limited.\n"
167-
" (-X int_max_str_digits=number)\n"
168-
"PYTHONNODEBUGRANGES: if this variable is set, it disables the inclusion of\n"
169-
" the tables mapping extra location information (end line,\n"
170-
" start column offset and end column offset) to every\n"
171-
" instruction in code objects. This is useful when smaller\n"
172-
" code objects and pyc files are desired as well as\n"
173-
" suppressing the extra visual location indicators when the\n"
174-
" interpreter displays tracebacks. (-X no_debug_ranges)\n"
140+
"PYTHONINTMAXSTRDIGITS: limit the size of int<->str conversions;\n"
141+
" 0 disables the limit (-X int_max_str_digits=N)\n"
142+
"PYTHONNODEBUGRANGES: don't include extra location information in code objects\n"
143+
" (-X no_debug_ranges)\n"
175144
"PYTHONNOUSERSITE: disable user site directory (-s)\n"
176145
"PYTHONOPTIMIZE : enable level 1 optimizations (-O)\n"
177146
"PYTHONPROFILEIMPORTTIME: show how long each import takes (-X importtime)\n"
@@ -180,11 +149,11 @@ static const char usage_envvars[] =
180149
"PYTHONSAFEPATH : don't prepend a potentially unsafe path to sys.path.\n"
181150
"PYTHONTRACEMALLOC: trace Python memory allocations (-X tracemalloc)\n"
182151
"PYTHONUNBUFFERED: disable stdout/stderr buffering (-u)\n"
183-
"PYTHONUTF8 : if set to 1, enable the UTF-8 mode (-X utf8)\n"
152+
"PYTHONUTF8 : control the UTF-8 mode (-X utf8)\n"
184153
"PYTHONVERBOSE : trace import statements (-v)\n"
185154
"PYTHONWARNDEFAULTENCODING: enable opt-in EncodingWarning for 'encoding=None'\n"
186155
" (-X warn_default_encoding)\n"
187-
"PYTHONWARNINGS=arg: warning control (-W arg)\n"
156+
"PYTHONWARNINGS : warning control (-W)\n"
188157
;
189158

190159
#if defined(MS_WINDOWS)

0 commit comments

Comments
 (0)
0