https://github.com/python/cpython/commit/13951c7f25c628ea2dc0a869ebe18e7bf59... commit: 13951c7f25c628ea2dc0a869ebe18e7bf593fa6d branch: 3.8 author: Pablo Galindo <Pablogsal@gmail.com> committer: GitHub <noreply@github.com> date: 2020-02-23T20:48:27Z summary: [3.8] bpo-39427: Document -X opt options in the CLI --help and the man page (GH-18131) (GH-18133) https://bugs.python.org/issue39427 Automerge-Triggered-By: @pablogsal (cherry picked from commit 41f0ef6abbd304409c55612a08788cdd59fbc8a3) Co-authored-by: Pablo Galindo <Pablogsal@gmail.com> files: A Misc/NEWS.d/next/Core and Builtins/2020-01-22-22-28-04.bpo-39427.LiO-Eo.rst M Misc/python.man M Python/initconfig.c diff --git a/Misc/NEWS.d/next/Core and Builtins/2020-01-22-22-28-04.bpo-39427.LiO-Eo.rst b/Misc/NEWS.d/next/Core and Builtins/2020-01-22-22-28-04.bpo-39427.LiO-Eo.rst new file mode 100644 index 0000000000000..a3915a4d81c79 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2020-01-22-22-28-04.bpo-39427.LiO-Eo.rst @@ -0,0 +1,2 @@ +Document all possibilities for the ``-X`` options in the command line help +section. Patch by Pablo Galindo. diff --git a/Misc/python.man b/Misc/python.man index 3aa9f1f9c7eac..3645b0206eb2b 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -273,7 +273,45 @@ field matches the line number, where zero matches all line numbers and is thus equivalent to an omitted line number. .TP .BI "\-X " option -Set implementation specific 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 showalloccount: output the total count of allocated objects for each + type when the program finishes. This only works when Python was built with + COUNT_ALLOCS defined + + -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 + * 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. .TP .B \-x Skip the first line of the source. This is intended for a DOS diff --git a/Python/initconfig.c b/Python/initconfig.c index a30fdd1bab954..a0b2691bcd75c 100644 --- a/Python/initconfig.c +++ b/Python/initconfig.c @@ -63,7 +63,38 @@ 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\n\ +-X opt : set implementation-specific option. The following options are available:\n\ +\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 showalloccount: output the total count of allocated objects for each\n\ + type when the program finishes. This only works when Python was built with\n\ + COUNT_ALLOCS defined\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() 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\ +\n\ --check-hash-based-pycs always|default|never:\n\ control how Python invalidates hash-based .pyc files\n\ ";