bpo-39427: Document -X opt options in the CLI --help and the man page (GH-18131)

https://bugs.python.org/issue39427



Automerge-Triggered-By: @pablogsal

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.

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

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\
 ";