From 1d05d84b51beeee706f7635293e9755e708813a3 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:39:08 -0400 Subject: [PATCH 01/24] Document PYTHONPYCACHEPREFIX in the manpage --- Misc/python.man | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 4076b8d3d1ba30..4fb4ba825cdca0 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -499,6 +499,12 @@ If this is set to a non-empty string it is equivalent to specifying the \fB\-B\fP option (don't try to write .I .pyc files). +.IP PYTHONPYCACHEPREFIX +If this is set, Python will write \fB.pyc\fR files in a mirror directory tree +at this path, instead of in \fB__pycache__\fR directories within the source +tree. +.IP +This is equivalent to specifying the \fB\-X pycache_prefix=\fIPATH\fR option. .IP PYTHONINSPECT If this is set to a non-empty string it is equivalent to specifying the \fB\-i\fP option. From baf369c0ca67e1dc622a61091351b7665f144853 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:42:10 -0400 Subject: [PATCH 02/24] Document PYTHONCOERCELOCALE in the manpage --- Misc/python.man | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 4fb4ba825cdca0..aedcbde507431c 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -573,6 +573,10 @@ This variable is ignored if the environment variable is used to force the .BR malloc (3) allocator of the C library, or if Python is configured without pymalloc support. +.IP PYTHONCOERCELOCALE +If set to the value 0, causes the main Python command line application to skip +coercing the legacy ASCII-based C and POSIX locales to a more capable UTF-8 +based alternative. .IP PYTHONASYNCIODEBUG If this environment variable is set to a non-empty string, enable the debug mode of the asyncio module. From 05a5279f4e8e9f75ac23caff7f657309ddc21fae Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:43:59 -0400 Subject: [PATCH 03/24] Document PYTHONDEVMODE in the manpage --- Misc/python.man | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index aedcbde507431c..fb445fbeb3656c 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -577,6 +577,12 @@ allocator of the C library, or if Python is configured without pymalloc support. If set to the value 0, causes the main Python command line application to skip coercing the legacy ASCII-based C and POSIX locales to a more capable UTF-8 based alternative. +.IP PYTHONDEVMODE +If this environment variable is set to a non-empty string, enable Python's +"development mode", introducing additional runtime checks that are too +expensive to be enabled by default. +.IP +This is equivalent to the \fB\-X dev\fR option. .IP PYTHONASYNCIODEBUG If this environment variable is set to a non-empty string, enable the debug mode of the asyncio module. From 24e2f70c8465046bad12a6d0afbdf33dc091dc21 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:46:04 -0400 Subject: [PATCH 04/24] Document PYTHONUTF8 in the manpage --- Misc/python.man | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index fb445fbeb3656c..1bfbcddbf0907f 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -583,6 +583,8 @@ If this environment variable is set to a non-empty string, enable Python's expensive to be enabled by default. .IP This is equivalent to the \fB\-X dev\fR option. +.IP PYTHONUTF8 +If set to 1, enable the Python "UTF-8 Mode". Setting to 0 disables. .IP PYTHONASYNCIODEBUG If this environment variable is set to a non-empty string, enable the debug mode of the asyncio module. From 282e4905fd86a77831cf4764431025ac79a0e9df Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:47:07 -0400 Subject: [PATCH 05/24] Document PYTHONWARNDEFAULTENCODING in the manpage --- Misc/python.man | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 1bfbcddbf0907f..d44deac581a5b8 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -585,6 +585,9 @@ expensive to be enabled by default. This is equivalent to the \fB\-X dev\fR option. .IP PYTHONUTF8 If set to 1, enable the Python "UTF-8 Mode". Setting to 0 disables. +.IP PYTHONWARNDEFAULTENCODING +If this environment variable is set to a non-empty string, issue a +\fIEncodingWarning\fR when the locale-specific default encoding is used. .IP PYTHONASYNCIODEBUG If this environment variable is set to a non-empty string, enable the debug mode of the asyncio module. From 0ca6b150fcbe31ebbf5cfb5d9d94b10b171a3fde Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:48:09 -0400 Subject: [PATCH 06/24] Document PYTHONNODEBUGRANGES in the manpage --- Misc/python.man | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index d44deac581a5b8..117509da3bd3d8 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -588,6 +588,12 @@ If set to 1, enable the Python "UTF-8 Mode". Setting to 0 disables. .IP PYTHONWARNDEFAULTENCODING If this environment variable is set to a non-empty string, issue a \fIEncodingWarning\fR when the locale-specific default encoding is used. +.IP PYTHONNODEBUGRANGES +If this variable is set, it disables the inclusion of the tables mapping +extra location information (end line, start column offset and end column +offset) to every instruction in code objects. This is useful when smaller code +objects and pyc files are desired as well as suppressing the extra visual +location indicators when the interpreter displays tracebacks. .IP PYTHONASYNCIODEBUG If this environment variable is set to a non-empty string, enable the debug mode of the asyncio module. From 4c31a4fb5d972eea255feba19058b620253879f0 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:50:06 -0400 Subject: [PATCH 07/24] Document PYTHONPERFSUPPORT in the manpage --- Misc/python.man | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 117509da3bd3d8..8a49324b960f03 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -594,6 +594,12 @@ extra location information (end line, start column offset and end column offset) to every instruction in code objects. This is useful when smaller code objects and pyc files are desired as well as suppressing the extra visual location indicators when the interpreter displays tracebacks. +.IP PYTHONPERFSUPPORT +If this variable is set to a nonzero value, it enables support for +the Linux perf profiler so Python calls can be detected by it. +Setting to 0 disables. +.IP +See also the \fB\-X perf\fR option. .IP PYTHONASYNCIODEBUG If this environment variable is set to a non-empty string, enable the debug mode of the asyncio module. From 92804981e27fea7885c23203d84a4aba58711660 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:51:55 -0400 Subject: [PATCH 08/24] Document PYTHON_PERF_JIT_SUPPORT in the manpage --- Misc/python.man | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 8a49324b960f03..8383da4d1242c7 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -600,6 +600,13 @@ the Linux perf profiler so Python calls can be detected by it. Setting to 0 disables. .IP See also the \fB\-X perf\fR option. +.IP PYTHON_PERF_JIT_SUPPORT +If this variable is set to a nonzero value, it enables support for +the Linux perf profiler so Python calls can be detected by it using DWARF +information. +Setting to 0 disables. +.IP +See also the \fB\-X perf_jit\fR option. .IP PYTHONASYNCIODEBUG If this environment variable is set to a non-empty string, enable the debug mode of the asyncio module. From 9363383d2ebbb89dc89ee494abaf4236144effe5 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:53:15 -0400 Subject: [PATCH 09/24] Document PYTHON_CPU_COUNT in the manpage --- Misc/python.man | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 8383da4d1242c7..1efeefe1ef7142 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -607,6 +607,11 @@ information. Setting to 0 disables. .IP See also the \fB\-X perf_jit\fR option. +.IP PYTHON_CPU_COUNT +If this variable is set to a positive integer, it overrides the return +values of \fIos.cpu_count\fR and \fIos.process_cpu_count\fR. +.IP +See also the \fB\-X cpu_count\fR option. .IP PYTHONASYNCIODEBUG If this environment variable is set to a non-empty string, enable the debug mode of the asyncio module. From c8456d1f0498a5ddfd54ee7e86c6beb6619c0f61 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:55:52 -0400 Subject: [PATCH 10/24] Document PYTHON_FROZEN_MODULES in the manpage --- Misc/python.man | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 1efeefe1ef7142..1555768eda7eb7 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -612,6 +612,13 @@ If this variable is set to a positive integer, it overrides the return values of \fIos.cpu_count\fR and \fIos.process_cpu_count\fR. .IP See also the \fB\-X cpu_count\fR option. +.IP PYTHON_FROZEN_MODULES +If this variable is set to \fBon\fR or \fBoff\fR, it determines whether or not +frozen modules are ignored by the import machinery. A value of \fBon\fR means +they get imported and \fBoff\fR means they are ignored. The default is \fBon\fR +for non-debug builds (the normal case) and \fBoff\fR for debug builds. +.IP +See also the \fB\-X frozen_modules\fR option. .IP PYTHONASYNCIODEBUG If this environment variable is set to a non-empty string, enable the debug mode of the asyncio module. From a41dbec7e6fc25d44097cc9d2d59a729271cc711 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:56:42 -0400 Subject: [PATCH 11/24] Document PYTHON_BASIC_REPL in the manpage --- Misc/python.man | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 1555768eda7eb7..7fba74a36a3956 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -657,6 +657,10 @@ can be set to the callable of your debugger of choice. .IP PYTHON_COLORS If this variable is set to 1, the interpreter will colorize various kinds of output. Setting it to 0 deactivates this behavior. +.IP PYTHON_BASIC_REPL +If this variable is set to any value, the interpreter will not attempt to +load the Python-based REPL that requires curses and readline, and will instead +use the traditional parser-based REPL. .IP PYTHON_HISTORY This environment variable can be used to set the location of a history file (on Unix, it is \fI~/.python_history\fP by default). From d5f25081df161541627b2a78437250eece02716f Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:57:33 -0400 Subject: [PATCH 12/24] Document PYTHONDUMPREFSFILE in the manpage --- Misc/python.man | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 7fba74a36a3956..84b23554c66151 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -675,6 +675,10 @@ if Python was configured with the .IP PYTHONDUMPREFS If this environment variable is set, Python will dump objects and reference counts still alive after shutting down the interpreter. +.IP PYTHONDUMPREFSFILE +If set, Python will dump objects and reference counts still alive after +shutting down the interpreter into a file under the path given as the value to +this environment variable. .SH AUTHOR The Python Software Foundation: https://www.python.org/psf/ .SH INTERNET RESOURCES From fd595b410b328b9142614119ebb0879d19c61cea Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 09:58:45 -0400 Subject: [PATCH 13/24] Document PYTHON_PRESITE in the manpage --- Misc/python.man | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 84b23554c66151..8a78c9c8c7299d 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -679,6 +679,13 @@ counts still alive after shutting down the interpreter. If set, Python will dump objects and reference counts still alive after shutting down the interpreter into a file under the path given as the value to this environment variable. +.IP PYTHON_PRESITE +If this variable is set to a module, that module will be imported +early in the interpreter lifecycle, before the \fIsite\fR module is +executed, and before the \fI__main__\fR module is created. +This only works on debug builds. +.IP +This is equivalent to the \fB-X presite=\fImodule\fR option. .SH AUTHOR The Python Software Foundation: https://www.python.org/psf/ .SH INTERNET RESOURCES From 995268d7e5fe4a7ecd9142ea33671e2e37950ab2 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 14:09:45 -0400 Subject: [PATCH 14/24] Document the -R option in the manpage --- Misc/python.man | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 8a78c9c8c7299d..03a86e11cc8c78 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -37,6 +37,9 @@ python \- an interpreted, interactive, object-oriented programming language .B \-q ] [ +.B \-R +] +[ .B \-O ] [ @@ -212,6 +215,11 @@ as the current directory, the script's directory or an empty string. See also th Do not print the version and copyright messages. These messages are also suppressed in non-interactive mode. .TP +.B \-R +Turn on hash randomization. This option only has an effect if the +\fBPYTHONHASHSEED\fR environment variable is set to \fB0\fR, since hash +randomization is enabled by default. +.TP .B \-s Don't add user site directory to sys.path. .TP From 3169524f758e276e321a6f90af409354cd62e073 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 14:14:04 -0400 Subject: [PATCH 15/24] Mention that int_max_str_digits is equivalent to PYTHONINTMAXSTRDIGITS in the manpage --- Misc/python.man | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 03a86e11cc8c78..d6780817e00909 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -555,6 +555,8 @@ Limit the maximum digit characters in an int value when converting from a string and when converting an int back to a str. A value of 0 disables the limit. Conversions to or from bases 2, 4, 8, 16, and 32 are never limited. +.IP +This is equivalent to the \fB-X int_max_str_digits=\fINUMBER\fR option. .IP PYTHONMALLOC Set the Python memory allocators and/or install debug hooks. The available memory allocators are From a715cfed943f7004324e595182d4f0468a532ee6 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 14:20:12 -0400 Subject: [PATCH 16/24] Document -X perf in the manpage --- Misc/python.man | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index d6780817e00909..3ec8e4fde93bb9 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -371,6 +371,8 @@ Set implementation-specific option. The following options are available: This helps avoid denial of service attacks when parsing untrusted data. The default is sys.int_info.default_max_str_digits. 0 disables. + -X perf: support the Linux "perf" profiler; also PYTHONPERFSUPPORT=1 + .TP .B \-x Skip the first line of the source. This is intended for a DOS From b7006c3420ad2d5e53651f95e4d99c99efa4d921 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 14:20:21 -0400 Subject: [PATCH 17/24] Document -X perf_jit in --help-xoptions --- Python/initconfig.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Python/initconfig.c b/Python/initconfig.c index 4db77ef47d2362..1733ed05a3e8d9 100644 --- a/Python/initconfig.c +++ b/Python/initconfig.c @@ -305,6 +305,8 @@ The following implementation-specific options are available:\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\ +-X perf_jit: support the Linux \"perf\" profiler with DWARF support;\n\ + also PYTHON_PERF_JIT_SUPPORT=1\n\ " #ifdef Py_DEBUG "-X presite=MOD: import this module before site; also PYTHON_PRESITE\n" From f3f24cedc7ff41958f2f9468c9e639d2fe64eea8 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 14:20:59 -0400 Subject: [PATCH 18/24] Document -X perf_jit in the manpage --- Misc/python.man | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 3ec8e4fde93bb9..d32d15bce7065b 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -373,6 +373,9 @@ Set implementation-specific option. The following options are available: -X perf: support the Linux "perf" profiler; also PYTHONPERFSUPPORT=1 + -X perf_jit: support the Linux "perf" profiler with DWARF support; + also PYTHON_PERF_JIT_SUPPORT=1 + .TP .B \-x Skip the first line of the source. This is intended for a DOS From c83ede7b7e9ac954cb04a4521171369cdf9fe7e2 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 14:22:13 -0400 Subject: [PATCH 19/24] Document -X cpu_count in the manpage --- Misc/python.man | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index d32d15bce7065b..9797e9310596ee 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -376,6 +376,9 @@ Set implementation-specific option. The following options are available: -X perf_jit: support the Linux "perf" profiler with DWARF support; also PYTHON_PERF_JIT_SUPPORT=1 + -X cpu_count=N: override the return value of os.cpu_count(); + -X cpu_count=default cancels overriding; also PYTHON_CPU_COUNT + .TP .B \-x Skip the first line of the source. This is intended for a DOS From 60290c159ee109ffcde17b807ab2b4b9e56038bf Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 14:25:28 -0400 Subject: [PATCH 20/24] Document -X presite in the manpage --- Misc/python.man | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index 9797e9310596ee..e86d799c4d6b20 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -379,6 +379,9 @@ Set implementation-specific option. The following options are available: -X cpu_count=N: override the return value of os.cpu_count(); -X cpu_count=default cancels overriding; also PYTHON_CPU_COUNT + -X presite=MOD: import this module before site; also PYTHON_PRESITE + This only works on debug builds. + .TP .B \-x Skip the first line of the source. This is intended for a DOS From 682aca2eee3f6da31dc759897ed5d532ceef131c Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Mon, 3 Feb 2025 14:29:01 -0400 Subject: [PATCH 21/24] Document the -X gil option in the manpage --- Misc/python.man | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Misc/python.man b/Misc/python.man index e86d799c4d6b20..c024727e302b1e 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -367,6 +367,9 @@ Set implementation-specific option. The following options are available: -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). + -X gil=[0|1]: enable (1) or disable (0) the GIL; also PYTHON_GIL + Only available in builds configured with --disable-gil. + -X int_max_str_digits=number: limit the size of int<->str conversions. This helps avoid denial of service attacks when parsing untrusted data. The default is sys.int_info.default_max_str_digits. 0 disables. @@ -689,6 +692,8 @@ This environment variable can be used to set the location of a history file If this variable is set to 1, the global interpreter lock (GIL) will be forced on. Setting it to 0 forces the GIL off. Only available in builds configured with \fB--disable-gil\fP. +.IP +This is equivalent to the \fB-X gil\fR option. .SS Debug-mode variables Setting these variables only has an effect in a debug build of Python, that is, if Python was configured with the From 3179d0d6203cbce5ae7de8c813c75d87ffdc8e61 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Tue, 11 Feb 2025 10:12:22 -0400 Subject: [PATCH 22/24] Manpage: Sort -X options --- Misc/python.man | 62 ++++++++++++++++++++++++------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/Misc/python.man b/Misc/python.man index c024727e302b1e..5b13a9d7444a63 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -321,21 +321,8 @@ a regular expression on the warning message. .BI "\-X " option Set implementation-specific option. The following options are available: - -X faulthandler: enable faulthandler - - -X showrefcount: output the total reference count and number of used - memory blocks when the program finishes or after each statement in the - interactive interpreter. This only works on debug builds - - -X tracemalloc: start tracing Python memory allocations using the - tracemalloc module. By default, only the most recent frame is stored in a - traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a - traceback limit of NFRAME frames - - -X importtime: show how long each import takes. It shows module name, - cumulative time (including nested imports) and self time (excluding - nested imports). Note that its output may be broken in multi-threaded - application. Typical usage is python3 -X importtime -c 'import asyncio' + -X cpu_count=N: override the return value of os.cpu_count(); + -X cpu_count=default cancels overriding; also PYTHON_CPU_COUNT -X dev: enable CPython's "development mode", introducing additional runtime checks which are too expensive to be enabled by default. It will not be @@ -349,20 +336,12 @@ Set implementation-specific option. The following options are available: * Set the dev_mode attribute of sys.flags to True * io.IOBase destructor logs close() exceptions - -X utf8: enable UTF-8 mode for operating system interfaces, overriding the default - locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when it would - otherwise activate automatically). See PYTHONUTF8 for more details - - -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the - given directory instead of to the code tree. - - -X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None' + -X importtime: show how long each import takes. It shows module name, + cumulative time (including nested imports) and self time (excluding + nested imports). Note that its output may be broken in multi-threaded + application. Typical usage is python3 -X importtime -c 'import asyncio' - -X no_debug_ranges: disable the inclusion of the tables mapping extra location - information (end line, start column offset and end column offset) to every - instruction in code objects. This is useful when smaller code objects and pyc - files are desired as well as suppressing the extra visual location indicators - when the interpreter displays tracebacks. + -X faulthandler: enable faulthandler -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). @@ -374,17 +353,38 @@ Set implementation-specific option. The following options are available: This helps avoid denial of service attacks when parsing untrusted data. The default is sys.int_info.default_max_str_digits. 0 disables. + -X no_debug_ranges: disable the inclusion of the tables mapping extra location + information (end line, start column offset and end column offset) to every + instruction in code objects. This is useful when smaller code objects and pyc + files are desired as well as suppressing the extra visual location indicators + when the interpreter displays tracebacks. + -X perf: support the Linux "perf" profiler; also PYTHONPERFSUPPORT=1 -X perf_jit: support the Linux "perf" profiler with DWARF support; also PYTHON_PERF_JIT_SUPPORT=1 - -X cpu_count=N: override the return value of os.cpu_count(); - -X cpu_count=default cancels overriding; also PYTHON_CPU_COUNT - -X presite=MOD: import this module before site; also PYTHON_PRESITE This only works on debug builds. + -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the + given directory instead of to the code tree. + + -X showrefcount: output the total reference count and number of used + memory blocks when the program finishes or after each statement in the + interactive interpreter. This only works on debug builds + + -X tracemalloc: start tracing Python memory allocations using the + tracemalloc module. By default, only the most recent frame is stored in a + traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a + traceback limit of NFRAME frames + + -X utf8: enable UTF-8 mode for operating system interfaces, overriding the default + locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when it would + otherwise activate automatically). See PYTHONUTF8 for more details + + -X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None' + .TP .B \-x Skip the first line of the source. This is intended for a DOS From 8548c32afc720c5cb11d23b14713645ee0d35cea Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Tue, 11 Feb 2025 10:46:44 -0400 Subject: [PATCH 23/24] Manpage: Sort the environment variables --- Misc/python.man | 296 ++++++++++++++++++++++++------------------------ 1 file changed, 148 insertions(+), 148 deletions(-) diff --git a/Misc/python.man b/Misc/python.man index 5b13a9d7444a63..023d183aeca3fe 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -469,89 +469,77 @@ needed for developing Python extensions and embedding the interpreter. .RE .SH ENVIRONMENT VARIABLES -.IP PYTHONSAFEPATH -If this is set to a non-empty string, don't automatically prepend a potentially -unsafe path to \fBsys.path\fP such as the current directory, the script's -directory or an empty string. See also the \fB\-P\fP option. -.IP PYTHONHOME -Change the location of the standard Python libraries. By default, the -libraries are searched in ${prefix}/lib/python and -${exec_prefix}/lib/python, where ${prefix} and ${exec_prefix} -are installation-dependent directories, both defaulting to -\fI/usr/local\fP. When $PYTHONHOME is set to a single directory, its value -replaces both ${prefix} and ${exec_prefix}. To specify different values -for these, set $PYTHONHOME to ${prefix}:${exec_prefix}. -.IP PYTHONPATH -Augments the default search path for module files. -The format is the same as the shell's $PATH: one or more directory -pathnames separated by colons. -Non-existent directories are silently ignored. -The default search path is installation dependent, but generally -begins with ${prefix}/lib/python (see PYTHONHOME above). -The default search path is always appended to $PYTHONPATH. -If a script argument is given, the directory containing the script is -inserted in the path in front of $PYTHONPATH. -The search path can be manipulated from within a Python program as the -variable -.IR sys.path . -.IP PYTHONPLATLIBDIR -Override sys.platlibdir. -.IP PYTHONSTARTUP -If this is the name of a readable file, the Python commands in that -file are executed before the first prompt is displayed in interactive -mode. -The file is executed in the same name space where interactive commands -are executed so that objects defined or imported in it can be used -without qualification in the interactive session. -You can also change the prompts -.I sys.ps1 -and -.I sys.ps2 -in this file. -.IP PYTHONOPTIMIZE -If this is set to a non-empty string it is equivalent to specifying -the \fB\-O\fP option. If set to an integer, it is equivalent to -specifying \fB\-O\fP multiple times. +.IP PYTHONASYNCIODEBUG +If this environment variable is set to a non-empty string, enable the debug +mode of the asyncio module. +.IP PYTHON_BASIC_REPL +If this variable is set to any value, the interpreter will not attempt to +load the Python-based REPL that requires curses and readline, and will instead +use the traditional parser-based REPL. +.IP PYTHONBREAKPOINT +If this environment variable is set to 0, it disables the default debugger. It +can be set to the callable of your debugger of choice. +.IP PYTHONCOERCELOCALE +If set to the value 0, causes the main Python command line application to skip +coercing the legacy ASCII-based C and POSIX locales to a more capable UTF-8 +based alternative. +.IP PYTHON_COLORS +If this variable is set to 1, the interpreter will colorize various kinds of +output. Setting it to 0 deactivates this behavior. +.IP PYTHON_CPU_COUNT +If this variable is set to a positive integer, it overrides the return +values of \fIos.cpu_count\fR and \fIos.process_cpu_count\fR. +.IP +See also the \fB\-X cpu_count\fR option. .IP PYTHONDEBUG If this is set to a non-empty string it is equivalent to specifying the \fB\-d\fP option. If set to an integer, it is equivalent to specifying \fB\-d\fP multiple times. +.IP PYTHONEXECUTABLE +If this environment variable is set, +.IB sys.argv[0] +will be set to its value instead of the value got through the C runtime. Only +works on Mac OS X. +.IP PYTHONFAULTHANDLER +If this environment variable is set to a non-empty string, +.IR faulthandler.enable() +is called at startup: install a handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS +and SIGILL signals to dump the Python traceback. +.IP +This is equivalent to the \fB-X faulthandler\fP option. +.IP PYTHON_FROZEN_MODULES +If this variable is set to \fBon\fR or \fBoff\fR, it determines whether or not +frozen modules are ignored by the import machinery. A value of \fBon\fR means +they get imported and \fBoff\fR means they are ignored. The default is \fBon\fR +for non-debug builds (the normal case) and \fBoff\fR for debug builds. +.IP +See also the \fB\-X frozen_modules\fR option. +.IP PYTHON_GIL +If this variable is set to 1, the global interpreter lock (GIL) will be forced +on. Setting it to 0 forces the GIL off. Only available in builds configured +with \fB--disable-gil\fP. +.IP PYTHON_HISTORY +This environment variable can be used to set the location of a history file +(on Unix, it is \fI~/.python_history\fP by default). +.IP +This is equivalent to the \fB-X gil\fR option. +.IP PYTHONNODEBUGRANGES +If this variable is set, it disables the inclusion of the tables mapping +extra location information (end line, start column offset and end column +offset) to every instruction in code objects. This is useful when smaller code +objects and pyc files are desired as well as suppressing the extra visual +location indicators when the interpreter displays tracebacks. .IP PYTHONDONTWRITEBYTECODE If this is set to a non-empty string it is equivalent to specifying the \fB\-B\fP option (don't try to write .I .pyc files). -.IP PYTHONPYCACHEPREFIX -If this is set, Python will write \fB.pyc\fR files in a mirror directory tree -at this path, instead of in \fB__pycache__\fR directories within the source -tree. +.IP PYTHONDEVMODE +If this environment variable is set to a non-empty string, enable Python's +"development mode", introducing additional runtime checks that are too +expensive to be enabled by default. .IP -This is equivalent to specifying the \fB\-X pycache_prefix=\fIPATH\fR option. -.IP PYTHONINSPECT -If this is set to a non-empty string it is equivalent to specifying -the \fB\-i\fP option. -.IP PYTHONIOENCODING -If this is set before running the interpreter, it overrides the encoding used -for stdin/stdout/stderr, in the syntax -.IB encodingname ":" errorhandler -The -.IB errorhandler -part is optional and has the same meaning as in str.encode. For stderr, the -.IB errorhandler - part is ignored; the handler will always be \'backslashreplace\'. -.IP PYTHONNOUSERSITE -If this is set to a non-empty string it is equivalent to specifying the -\fB\-s\fP option (Don't add the user site directory to sys.path). -.IP PYTHONUNBUFFERED -If this is set to a non-empty string it is equivalent to specifying -the \fB\-u\fP option. -.IP PYTHONVERBOSE -If this is set to a non-empty string it is equivalent to specifying -the \fB\-v\fP option. If set to an integer, it is equivalent to -specifying \fB\-v\fP multiple times. -.IP PYTHONWARNINGS -If this is set to a comma-separated string it is equivalent to -specifying the \fB\-W\fP option for each separate value. +This is equivalent to the \fB\-X dev\fR option. .IP PYTHONHASHSEED If this variable is set to "random", a random value is used to seed the hashes of str and bytes objects. @@ -564,6 +552,17 @@ values. The integer must be a decimal number in the range [0,4294967295]. Specifying the value 0 will disable hash randomization. +.IP PYTHONHOME +Change the location of the standard Python libraries. By default, the +libraries are searched in ${prefix}/lib/python and +${exec_prefix}/lib/python, where ${prefix} and ${exec_prefix} +are installation-dependent directories, both defaulting to +\fI/usr/local\fP. When $PYTHONHOME is set to a single directory, its value +replaces both ${prefix} and ${exec_prefix}. To specify different values +for these, set $PYTHONHOME to ${prefix}:${exec_prefix}. +.IP PYTHONINSPECT +If this is set to a non-empty string it is equivalent to specifying +the \fB\-i\fP option. .IP PYTHONINTMAXSTRDIGITS Limit the maximum digit characters in an int value when converting from a string and when converting an int back to a str. @@ -571,6 +570,15 @@ A value of 0 disables the limit. Conversions to or from bases 2, 4, 8, 16, and 32 are never limited. .IP This is equivalent to the \fB-X int_max_str_digits=\fINUMBER\fR option. +.IP PYTHONIOENCODING +If this is set before running the interpreter, it overrides the encoding used +for stdin/stdout/stderr, in the syntax +.IB encodingname ":" errorhandler +The +.IB errorhandler +part is optional and has the same meaning as in str.encode. For stderr, the +.IB errorhandler +part is ignored; the handler will always be \'backslashreplace\'. .IP PYTHONMALLOC Set the Python memory allocators and/or install debug hooks. The available memory allocators are @@ -597,33 +605,26 @@ This variable is ignored if the environment variable is used to force the .BR malloc (3) allocator of the C library, or if Python is configured without pymalloc support. -.IP PYTHONCOERCELOCALE -If set to the value 0, causes the main Python command line application to skip -coercing the legacy ASCII-based C and POSIX locales to a more capable UTF-8 -based alternative. -.IP PYTHONDEVMODE -If this environment variable is set to a non-empty string, enable Python's -"development mode", introducing additional runtime checks that are too -expensive to be enabled by default. -.IP -This is equivalent to the \fB\-X dev\fR option. -.IP PYTHONUTF8 -If set to 1, enable the Python "UTF-8 Mode". Setting to 0 disables. -.IP PYTHONWARNDEFAULTENCODING -If this environment variable is set to a non-empty string, issue a -\fIEncodingWarning\fR when the locale-specific default encoding is used. -.IP PYTHONNODEBUGRANGES -If this variable is set, it disables the inclusion of the tables mapping -extra location information (end line, start column offset and end column -offset) to every instruction in code objects. This is useful when smaller code -objects and pyc files are desired as well as suppressing the extra visual -location indicators when the interpreter displays tracebacks. -.IP PYTHONPERFSUPPORT -If this variable is set to a nonzero value, it enables support for -the Linux perf profiler so Python calls can be detected by it. -Setting to 0 disables. -.IP -See also the \fB\-X perf\fR option. +.IP PYTHONNOUSERSITE +If this is set to a non-empty string it is equivalent to specifying the +\fB\-s\fP option (Don't add the user site directory to sys.path). +.IP PYTHONOPTIMIZE +If this is set to a non-empty string it is equivalent to specifying +the \fB\-O\fP option. If set to an integer, it is equivalent to +specifying \fB\-O\fP multiple times. +.IP PYTHONPATH +Augments the default search path for module files. +The format is the same as the shell's $PATH: one or more directory +pathnames separated by colons. +Non-existent directories are silently ignored. +The default search path is installation dependent, but generally +begins with ${prefix}/lib/python (see PYTHONHOME above). +The default search path is always appended to $PYTHONPATH. +If a script argument is given, the directory containing the script is +inserted in the path in front of $PYTHONPATH. +The search path can be manipulated from within a Python program as the +variable +.IR sys.path . .IP PYTHON_PERF_JIT_SUPPORT If this variable is set to a nonzero value, it enables support for the Linux perf profiler so Python calls can be detected by it using DWARF @@ -631,21 +632,40 @@ information. Setting to 0 disables. .IP See also the \fB\-X perf_jit\fR option. -.IP PYTHON_CPU_COUNT -If this variable is set to a positive integer, it overrides the return -values of \fIos.cpu_count\fR and \fIos.process_cpu_count\fR. +.IP PYTHONPERFSUPPORT +If this variable is set to a nonzero value, it enables support for +the Linux perf profiler so Python calls can be detected by it. +Setting to 0 disables. .IP -See also the \fB\-X cpu_count\fR option. -.IP PYTHON_FROZEN_MODULES -If this variable is set to \fBon\fR or \fBoff\fR, it determines whether or not -frozen modules are ignored by the import machinery. A value of \fBon\fR means -they get imported and \fBoff\fR means they are ignored. The default is \fBon\fR -for non-debug builds (the normal case) and \fBoff\fR for debug builds. +See also the \fB\-X perf\fR option. +.IP PYTHONPLATLIBDIR +Override sys.platlibdir. +.IP PYTHONPROFILEIMPORTTIME +If this environment variable is set to a non-empty string, Python will +show how long each import takes. This is exactly equivalent to setting +\fB\-X importtime\fP on the command line. +.IP PYTHONPYCACHEPREFIX +If this is set, Python will write \fB.pyc\fR files in a mirror directory tree +at this path, instead of in \fB__pycache__\fR directories within the source +tree. .IP -See also the \fB\-X frozen_modules\fR option. -.IP PYTHONASYNCIODEBUG -If this environment variable is set to a non-empty string, enable the debug -mode of the asyncio module. +This is equivalent to specifying the \fB\-X pycache_prefix=\fIPATH\fR option. +.IP PYTHONSAFEPATH +If this is set to a non-empty string, don't automatically prepend a potentially +unsafe path to \fBsys.path\fP such as the current directory, the script's +directory or an empty string. See also the \fB\-P\fP option. +.IP PYTHONSTARTUP +If this is the name of a readable file, the Python commands in that +file are executed before the first prompt is displayed in interactive +mode. +The file is executed in the same name space where interactive commands +are executed so that objects defined or imported in it can be used +without qualification in the interactive session. +You can also change the prompts +.I sys.ps1 +and +.I sys.ps2 +in this file. .IP PYTHONTRACEMALLOC If this environment variable is set to a non-empty string, start tracing Python memory allocations using the tracemalloc module. @@ -654,46 +674,26 @@ The value of the variable is the maximum number of frames stored in a traceback of a trace. For example, .IB PYTHONTRACEMALLOC=1 stores only the most recent frame. -.IP PYTHONFAULTHANDLER -If this environment variable is set to a non-empty string, -.IR faulthandler.enable() -is called at startup: install a handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS -and SIGILL signals to dump the Python traceback. -.IP -This is equivalent to the \fB-X faulthandler\fP option. -.IP PYTHONEXECUTABLE -If this environment variable is set, -.IB sys.argv[0] -will be set to its value instead of the value got through the C runtime. Only -works on Mac OS X. +.IP PYTHONUNBUFFERED +If this is set to a non-empty string it is equivalent to specifying +the \fB\-u\fP option. .IP PYTHONUSERBASE Defines the user base directory, which is used to compute the path of the user .IR site-packages directory and installation paths for .IR "python \-m pip install \-\-user" . -.IP PYTHONPROFILEIMPORTTIME -If this environment variable is set to a non-empty string, Python will -show how long each import takes. This is exactly equivalent to setting -\fB\-X importtime\fP on the command line. -.IP PYTHONBREAKPOINT -If this environment variable is set to 0, it disables the default debugger. It -can be set to the callable of your debugger of choice. -.IP PYTHON_COLORS -If this variable is set to 1, the interpreter will colorize various kinds of -output. Setting it to 0 deactivates this behavior. -.IP PYTHON_BASIC_REPL -If this variable is set to any value, the interpreter will not attempt to -load the Python-based REPL that requires curses and readline, and will instead -use the traditional parser-based REPL. -.IP PYTHON_HISTORY -This environment variable can be used to set the location of a history file -(on Unix, it is \fI~/.python_history\fP by default). -.IP PYTHON_GIL -If this variable is set to 1, the global interpreter lock (GIL) will be forced -on. Setting it to 0 forces the GIL off. Only available in builds configured -with \fB--disable-gil\fP. -.IP -This is equivalent to the \fB-X gil\fR option. +.IP PYTHONUTF8 +If set to 1, enable the Python "UTF-8 Mode". Setting to 0 disables. +.IP PYTHONVERBOSE +If this is set to a non-empty string it is equivalent to specifying +the \fB\-v\fP option. If set to an integer, it is equivalent to +specifying \fB\-v\fP multiple times. +.IP PYTHONWARNDEFAULTENCODING +If this environment variable is set to a non-empty string, issue a +\fIEncodingWarning\fR when the locale-specific default encoding is used. +.IP PYTHONWARNINGS +If this is set to a comma-separated string it is equivalent to +specifying the \fB\-W\fP option for each separate value. .SS Debug-mode variables Setting these variables only has an effect in a debug build of Python, that is, if Python was configured with the From 757d76be968e01762c79078762a038dee4c37032 Mon Sep 17 00:00:00 2001 From: Stefano Rivera Date: Tue, 11 Feb 2025 11:00:00 -0400 Subject: [PATCH 24/24] Manpage: Some formatting in the -X options --- Misc/python.man | 77 +++++++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 35 deletions(-) diff --git a/Misc/python.man b/Misc/python.man index 023d183aeca3fe..970612ae4e52a1 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -321,69 +321,76 @@ a regular expression on the warning message. .BI "\-X " option Set implementation-specific option. The following options are available: - -X cpu_count=N: override the return value of os.cpu_count(); - -X cpu_count=default cancels overriding; also PYTHON_CPU_COUNT - - -X dev: enable CPython's "development mode", introducing additional runtime - checks which are too expensive to be enabled by default. It will not be - more verbose than the default if the code is correct: new warnings are - only emitted when an issue is detected. Effect of the developer mode: - * Add default warning filter, as -W default - * Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks() - C function - * Enable the faulthandler module to dump the Python traceback on a crash + \fB-X cpu_count=\fIN\fR: override the return value of \fIos.cpu_count()\fR; + \fB-X cpu_count=default\fR cancels overriding; also \fBPYTHON_CPU_COUNT\fI + + \fB-X dev\fR: enable CPython's "development mode", introducing additional + runtime checks which are too expensive to be enabled by default. It + will not be more verbose than the default if the code is correct: new + warnings are only emitted when an issue is detected. Effect of the + developer mode: + * Add default warning filter, as \fB-W default\fR + * Install debug hooks on memory allocators: see the + PyMem_SetupDebugHooks() C function + * Enable the faulthandler module to dump the Python traceback on a + crash * Enable asyncio debug mode * Set the dev_mode attribute of sys.flags to True * io.IOBase destructor logs close() exceptions - -X importtime: show how long each import takes. It shows module name, + \fB-X importtime\fR: show how long each import takes. It shows module name, cumulative time (including nested imports) and self time (excluding nested imports). Note that its output may be broken in multi-threaded - application. Typical usage is python3 -X importtime -c 'import asyncio' + application. Typical usage is + \fBpython3 -X importtime -c 'import asyncio'\fR - -X faulthandler: enable faulthandler + \fB-X faulthandler\fR: enable faulthandler - -X frozen_modules=[on|off]: whether or not frozen modules should be used. + \fB-X frozen_modules=\fR[\fBon\fR|\fBoff\fR]: whether or not frozen modules + should be used. The default is "on" (or "off" if you are running a local build). - -X gil=[0|1]: enable (1) or disable (0) the GIL; also PYTHON_GIL - Only available in builds configured with --disable-gil. + \fB-X gil=\fR[\fB0\fR|\fB1\fR]: enable (1) or disable (0) the GIL; also + \fBPYTHON_GIL\fR + Only available in builds configured with \fB--disable-gil\fR. - -X int_max_str_digits=number: limit the size of int<->str conversions. + \fB-X int_max_str_digits=\fInumber\fR: limit the size of int<->str conversions. This helps avoid denial of service attacks when parsing untrusted data. The default is sys.int_info.default_max_str_digits. 0 disables. - -X no_debug_ranges: disable the inclusion of the tables mapping extra location - information (end line, start column offset and end column offset) to every - instruction in code objects. This is useful when smaller code objects and pyc - files are desired as well as suppressing the extra visual location indicators - when the interpreter displays tracebacks. + \fB-X no_debug_ranges\fR: disable the inclusion of the tables mapping extra + location information (end line, start column offset and end column + offset) to every instruction in code objects. This is useful when + smaller code objects and pyc files are desired as well as suppressing + the extra visual location indicators when the interpreter displays + tracebacks. - -X perf: support the Linux "perf" profiler; also PYTHONPERFSUPPORT=1 + \fB-X perf\fR: support the Linux "perf" profiler; also \fBPYTHONPERFSUPPORT=1\fR - -X perf_jit: support the Linux "perf" profiler with DWARF support; - also PYTHON_PERF_JIT_SUPPORT=1 + \fB-X perf_jit\fR: support the Linux "perf" profiler with DWARF support; + also \fBPYTHON_PERF_JIT_SUPPORT=1\fR - -X presite=MOD: import this module before site; also PYTHON_PRESITE + \fB-X presite=\fIMOD\fR: import this module before site; also \fBPYTHON_PRESITE\fR This only works on debug builds. - -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the - given directory instead of to the code tree. + \fB-X pycache_prefix=\fIPATH\fR: enable writing .pyc files to a parallel + tree rooted at the given directory instead of to the code tree. - -X showrefcount: output the total reference count and number of used + \fB-X showrefcount\fR: output the total reference count and number of used memory blocks when the program finishes or after each statement in the interactive interpreter. This only works on debug builds - -X tracemalloc: start tracing Python memory allocations using the + \fB-X tracemalloc\fR: start tracing Python memory allocations using the tracemalloc module. By default, only the most recent frame is stored in a traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a traceback limit of NFRAME frames - -X utf8: enable UTF-8 mode for operating system interfaces, overriding the default - locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when it would - otherwise activate automatically). See PYTHONUTF8 for more details + \fB-X utf8\fR: enable UTF-8 mode for operating system interfaces, + overriding the default locale-aware mode. \fB-X utf8=0\fR explicitly + disables UTF-8 mode (even when it would otherwise activate + automatically). See \fBPYTHONUTF8\fR for more details - -X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None' + \fB-X warn_default_encoding\fR: enable opt-in EncodingWarning for 'encoding=None' .TP .B \-x