diff --git a/Misc/python.man b/Misc/python.man index 4076b8d3d1ba30..970612ae4e52a1 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 @@ -313,56 +321,77 @@ 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 + \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 - -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 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 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 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' + \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 + \fBpython3 -X importtime -c 'import asyncio'\fR - -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 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 int_max_str_digits=number: limit the size of int<->str conversions. + \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. + + \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. + \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. + + \fB-X perf\fR: support the Linux "perf" profiler; also \fBPYTHONPERFSUPPORT=1\fR + + \fB-X perf_jit\fR: support the Linux "perf" profiler with DWARF support; + also \fBPYTHON_PERF_JIT_SUPPORT=1\fR + + \fB-X presite=\fIMOD\fR: import this module before site; also \fBPYTHON_PRESITE\fR + This only works on debug builds. + + \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. + + \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 + + \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 + + \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 + + \fB-X warn_default_encoding\fR: enable opt-in EncodingWarning for 'encoding=None' + .TP .B \-x Skip the first line of the source. This is intended for a DOS @@ -447,83 +476,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 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. +.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 PYTHONHASHSEED If this variable is set to "random", a random value is used to seed the hashes of str and bytes objects. @@ -536,11 +559,33 @@ 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. 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 @@ -567,9 +612,67 @@ 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 PYTHONASYNCIODEBUG -If this environment variable is set to a non-empty string, enable the debug -mode of the asyncio module. +.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 +information. +Setting to 0 disables. +.IP +See also the \fB\-X perf_jit\fR option. +.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 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 +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. @@ -578,40 +681,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_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 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 @@ -619,6 +708,17 @@ 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. +.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 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"