8000 gh-115664: Reorganize versionadded directives for -X options by serhiy-storchaka · Pull Request #116304 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

gh-115664: Reorganize versionadded directives for -X options #116304

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 15, 2024
Merged

gh-115664: Reorganize versionadded directives for -X options #116304

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
53ccb81
gh-115664: Reorganize versionadded directives for -X options
serhiy-storchaka Mar 4, 2024
035761b
Merge branch 'main' into docs-versionadded-xoptions
serhiy-storchaka Mar 7, 2024
f7237c7
Merge branch 'main' into docs-versionadded-xoptions
serhiy-storchaka Apr 15, 2024
78b9ea0
Keep notes about removed options.
serhiy-storchaka Apr 15, 2024
29b0d1f
Remove notes about the dev mode changes which are documented in a sep…
serhiy-storchaka Apr 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 45 additions & 34 deletions Doc/using/cmdline.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -500,43 +500,73 @@ Miscellaneous options

* ``-X faulthandler`` to enable :mod:`faulthandler`.
See also :envvar:`PYTHONFAULTHANDLER`.

.. versionadded:: 3.3

* ``-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 :ref:`debug builds
<debug-build>`.

.. versionadded:: 3.4

* ``-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 :func:`tracemalloc.start` and :envvar:`PYTHONTRACEMALLOC`
for more information.

.. versionadded:: 3.4

* ``-X int_max_str_digits`` configures the :ref:`integer string conversion
length limitation <int_max_str_digits>`. See also
:envvar:`PYTHONINTMAXSTRDIGITS`.

.. versionadded:: 3.11

* ``-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
application. Typical usage is ``python3 -X importtime -c 'import
asyncio'``. See also :envvar:`PYTHONPROFILEIMPORTTIME`.

.. versionadded:: 3.7

* ``-X dev``: enable :ref:`Python Development Mode <devmode>`, introducing
additional runtime checks that are too expensive to be enabled by
default. See also :envvar:`PYTHONDEVMODE`.

.. versionadded:: 3.7

* ``-X utf8`` enables the :ref:`Python UTF-8 Mode <utf8-mode>`.
``-X utf8=0`` explicitly disables :ref:`Python UTF-8 Mode <utf8-mode>`
(even when it would otherwise activate automatically).
See also :envvar:`PYTHONUTF8`.

.. versionadded:: 3.7

* ``-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`.

.. versionadded:: 3.8

* ``-X warn_default_encoding`` issues a :class:`EncodingWarning` when the
locale-specific default encoding is used for opening files.
See also :envvar:`PYTHONWARNDEFAULTENCODING`.

.. versionadded:: 3.10

* ``-X no_debug_ranges`` 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. See also
:envvar:`PYTHONNODEBUGRANGES`.

.. versionadded:: 3.11

* ``-X frozen_modules`` determines whether or not frozen modules are
ignored by the import machinery. A value of ``on`` means they get
imported and ``off`` means they are ignored. The default is ``on``
Expand All @@ -545,71 +575,52 @@ Miscellaneous options
Note that the :mod:`!importlib_bootstrap` and
:mod:`!importlib_bootstrap_external` frozen modules are always used, even
if this flag is set to ``off``. See also :envvar:`PYTHON_FROZEN_MODULES`.

.. versionadded:: 3.11

* ``-X perf`` enables support for the Linux ``perf`` profiler.
When this option is provided, the ``perf`` profiler will be able to
report Python calls. This option is only available on some platforms and
will do nothing if is not supported on the current system. The default value
is "off". See also :envvar:`PYTHONPERFSUPPORT` and :ref:`perf_profiling`.

.. versionadded:: 3.12

* :samp:`-X cpu_count={n}` overrides :func:`os.cpu_count`,
:func:`os.process_cpu_count`, and :func:`multiprocessing.cpu_count`.
*n* must be greater than or equal to 1.
This option may be useful for users who need to limit CPU resources of a
container system. See also :envvar:`PYTHON_CPU_COUNT`.
If *n* is ``default``, nothing is overridden.

.. versionadded:: 3.13

* :samp:`-X presite={package.module}` specifies a module that should be
imported before the :mod:`site` module is executed and before the
:mod:`__main__` module exists. Therefore, the imported module isn't
:mod:`__main__`. This can be used to execute code early during Python
initialization. Python needs to be :ref:`built in debug mode <debug-build>`
for this option to exist. See also :envvar:`PYTHON_PRESITE`.

.. versionadded:: 3.13

* :samp:`-X gil={0,1}` forces the GIL to be disabled or enabled,
respectively. Only available in builds configured with
:option:`--disable-gil`. See also :envvar:`PYTHON_GIL`.

.. versionadded:: 3.13

It also allows passing arbitrary values and retrieving them through the
:data:`sys._xoptions` dictionary.

.. versionadded:: 3.2

.. versionchanged:: 3.3
Added the ``-X faulthandler`` option.

.. versionchanged:: 3.4
Added the ``-X showrefcount`` and ``-X tracemalloc`` options.

.. versionchanged:: 3.6
Added the ``-X showalloccount`` option.

.. versionchanged:: 3.7
Added the ``-X importtime``, ``-X dev`` and ``-X utf8`` options.

.. versionchanged:: 3.8
Added the ``-X pycache_prefix`` option. The ``-X dev`` option now logs
``close()`` exceptions in :class:`io.IOBase` destructor.

.. versionchanged:: 3.9
Using ``-X dev`` option, check *encoding* and *errors* arguments on
string encoding and decoding operations.

The ``-X showalloccount`` option has been removed.
Removed the ``-X showalloccount`` option.

.. versionchanged:: 3.10
Added the ``-X warn_default_encoding`` option.
Removed the ``-X oldparser`` option.

.. versionchanged:: 3.11
Added the ``-X no_debug_ranges``, ``-X frozen_modules`` and
``-X int_max_str_digits`` options.

.. versionchanged:: 3.12
Added the ``-X perf`` option.

.. versionchanged:: 3.13
Added the ``-X cpu_count`` and ``-X presite`` options.

.. versionchanged:: 3.13
Added the ``-X gil`` option.

.. _using-on-controlling-color:

Controlling color
Expand Down
0