From 7421a5f410e6a4e848122081f3ed3536cb21db83 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 28 Feb 2020 11:55:35 +0100 Subject: [PATCH] bpo-39712: Add doc refs for env. vars & -X options Mention corresponding environment variables in -X option documentation. Also reference -X options in environment variable documentation. --- Doc/using/cmdline.rst | 15 ++++++++++----- .../2020-02-28-12-34-31.bpo-39712.sfwsas.rst | 1 + 2 files changed, 11 insertions(+), 5 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2020-02-28-12-34-31.bpo-39712.sfwsas.rst diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 04e0f3267db..40397a164d7 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -430,15 +430,17 @@ Miscellaneous options Reserved for various implementation-specific options. CPython currently defines the following possible values: - * ``-X faulthandler`` to enable :mod:`faulthandler`; + * ``-X faulthandler`` to enable :mod:`faulthandler`. See also + :envvar:`PYTHONFAULTHANDLER`. * ``-X showrefcount`` to 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`` to start tracing Python memory allocations using the :mod:`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. See the - :func:`tracemalloc.start` for more information. + tracing with a traceback limit of *NFRAME* frames. See + :func:`tracemalloc.start` and :envvar:`PYTHONTRACEMALLOC` for more + information. * ``-X importtime`` to 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 @@ -450,6 +452,7 @@ Miscellaneous options * ``-X utf8`` enables the :ref:`Python UTF-8 Mode `. ``-X utf8=0`` explicitly disables :ref:`Python UTF-8 Mode ` (even when it would otherwise activate automatically). + See also :envvar:`PYTHONUTF8`. * ``-X pycache_prefix=PATH`` enables writing ``.pyc`` files to a parallel tree rooted at the given directory instead of to the code tree. See also :envvar:`PYTHONPYCACHEPREFIX`. @@ -738,7 +741,8 @@ conflict. Python memory allocations using the :mod:`tracemalloc` module. The value of the variable is the maximum number of frames stored in a traceback of a trace. For example, ``PYTHONTRACEMALLOC=1`` stores only the most recent - frame. See the :func:`tracemalloc.start` for more information. + frame. See the :func:`tracemalloc.start` for more information. This is + equivalent to :option:`-X` ``tracemalloc`` option. .. versionadded:: 3.4 @@ -747,7 +751,7 @@ conflict. 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 - ``-X importtime`` on the command line. + option :option:`-X` ``importtime`` on the command line. .. versionadded:: 3.7 @@ -893,6 +897,7 @@ conflict. If this environment variable is set to a non-empty string, enable :ref:`Python Development Mode `, introducing additional runtime checks that are too expensive to be enabled by default. + This is equivalent to :option:`-X` ``dev`` option. .. versionadded:: 3.7 diff --git a/Misc/NEWS.d/next/Documentation/2020-02-28-12-34-31.bpo-39712.sfwsas.rst b/Misc/NEWS.d/next/Documentation/2020-02-28-12-34-31.bpo-39712.sfwsas.rst new file mode 100644 index 00000000000..01e0f91530c --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2020-02-28-12-34-31.bpo-39712.sfwsas.rst @@ -0,0 +1 @@ +Add cross references for environment variables and -X command line options