https://github.com/python/cpython/commit/333b9899fc7807575d1742b77b4633ac53b... commit: 333b9899fc7807575d1742b77b4633ac53bd528f branch: 3.7 author: Pablo Galindo <Pablogsal@gmail.com> committer: GitHub <noreply@github.com> date: 2020-02-23T20:48:30Z summary: [3.7] bpo-39427: Document -X opt options in the CLI --help and the man page (GH-18131) (#18134) 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 Modules/main.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 8d5ad8cd6ca87..67a5bb4cf849d 100644 --- a/Misc/python.man +++ b/Misc/python.man @@ -273,7 +273,42 @@ 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 + + -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 + .TP .B \-x Skip the first line of the source. This is intended for a DOS diff --git a/Modules/main.c b/Modules/main.c index 4d13184f2d184..33aa36d196f17 100644 --- a/Modules/main.c +++ b/Modules/main.c @@ -114,7 +114,35 @@ 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\ + -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\ +\n\ --check-hash-based-pycs always|default|never:\n\ control how Python invalidates hash-based .pyc files\n\ ";