diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst deleted file mode 100644 index 24069617c47ae1..00000000000000 --- a/Doc/howto/free-threading-python.rst +++ /dev/null @@ -1,187 +0,0 @@ -.. _freethreading-python-howto: - -********************************* -Python support for free threading -********************************* - -Starting with the 3.13 release, CPython has support for a build of -Python called :term:`free threading` where the :term:`global interpreter lock` -(GIL) is disabled. Free-threaded execution allows for full utilization of the -available processing power by running threads in parallel on available CPU cores. -While not all software will benefit from this automatically, programs -designed with threading in mind will run faster on multi-core hardware. - -The free-threaded mode is working and continues to be improved, but -there is some additional overhead in single-threaded workloads compared -to the regular build. Additionally, third-party packages, in particular ones -with an :term:`extension module`, may not be ready for use in a -free-threaded build, and will re-enable the :term:`GIL`. - -This document describes the implications of free threading -for Python code. See :ref:`freethreading-extensions-howto` for information on -how to write C extensions that support the free-threaded build. - -.. seealso:: - - :pep:`703` – Making the Global Interpreter Lock Optional in CPython for an - overall description of free-threaded Python. - - -Installation -============ - -Starting with Python 3.13, the official macOS and Windows installers -optionally support installing free-threaded Python binaries. The installers -are available at https://www.python.org/downloads/. - -For information on other platforms, see the `Installing a Free-Threaded Python -`_, a -community-maintained installation guide for installing free-threaded Python. - -When building CPython from source, the :option:`--disable-gil` configure option -should be used to build a free-threaded Python interpreter. - - -Identifying free-threaded Python -================================ - -To check if the current interpreter supports free-threading, :option:`python -VV <-V>` -and :data:`sys.version` contain "free-threading build". -The new :func:`sys._is_gil_enabled` function can be used to check whether -the GIL is actually disabled in the running process. - -The ``sysconfig.get_config_var("Py_GIL_DISABLED")`` configuration variable can -be used to determine whether the build supports free threading. If the variable -is set to ``1``, then the build supports free threading. This is the recommended -mechanism for decisions related to the build configuration. - - -The global interpreter lock in free-threaded Python -=================================================== - -Free-threaded builds of CPython support optionally running with the GIL enabled -at runtime using the environment variable :envvar:`PYTHON_GIL` or -the command-line option :option:`-X gil`. - -The GIL may also automatically be enabled when importing a C-API extension -module that is not explicitly marked as supporting free threading. A warning -will be printed in this case. - -In addition to individual package documentation, the following websites track -the status of popular packages support for free threading: - -* https://py-free-threading.github.io/tracking/ -* https://hugovk.github.io/free-threaded-wheels/ - - -Thread safety -============= - -The free-threaded build of CPython aims to provide similar thread-safety -behavior at the Python level to the default GIL-enabled build. Built-in -types like :class:`dict`, :class:`list`, and :class:`set` use internal locks -to protect against concurrent modifications in ways that behave similarly to -the GIL. However, Python has not historically guaranteed specific behavior for -concurrent modifications to these built-in types, so this should be treated -as a description of the current implementation, not a guarantee of current or -future behavior. - -.. note:: - - It's recommended to use the :class:`threading.Lock` or other synchronization - primitives instead of relying on the internal locks of built-in types, when - possible. - - -Known limitations -================= - -This section describes known limitations of the free-threaded CPython build. - -Immortalization ---------------- - -The free-threaded build of the 3.13 release makes some objects :term:`immortal`. -Immortal objects are not deallocated and have reference counts that are -never modified. This is done to avoid reference count contention that would -prevent efficient multi-threaded scaling. - -An object will be made immortal when a new thread is started for the first time -after the main thread is running. The following objects are immortalized: - -* :ref:`function ` objects declared at the module level -* :ref:`method ` descriptors -* :ref:`code ` objects -* :term:`module` objects and their dictionaries -* :ref:`classes ` (type objects) - -Because immortal objects are never deallocated, applications that create many -objects of these types may see increased memory usage. This is expected to be -addressed in the 3.14 release. - -Additionally, numeric and string literals in the code as well as strings -returned by :func:`sys.intern` are also immortalized. This behavior is -expected to remain in the 3.14 free-threaded build. - - -Frame objects -------------- - -It is not safe to access :ref:`frame ` objects from other -threads and doing so may cause your program to crash . This means that -:func:`sys._current_frames` is generally not safe to use in a free-threaded -build. Functions like :func:`inspect.currentframe` and :func:`sys._getframe` -are generally safe as long as the resulting frame object is not passed to -another thread. - -Iterators ---------- - -Sharing the same iterator object between multiple threads is generally not -safe and threads may see duplicate or missing elements when iterating or crash -the interpreter. - - -Single-threaded performance ---------------------------- - -The free-threaded build has additional overhead when executing Python code -compared to the default GIL-enabled build. In 3.13, this overhead is about -40% on the `pyperformance `_ suite. -Programs that spend most of their time in C extensions or I/O will see -less of an impact. The largest impact is because the specializing adaptive -interpreter (:pep:`659`) is disabled in the free-threaded build. We expect -to re-enable it in a thread-safe way in the 3.14 release. This overhead is -expected to be reduced in upcoming Python release. We are aiming for an -overhead of 10% or less on the pyperformance suite compared to the default -GIL-enabled build. - - -Behavioral changes -================== - -This section describes CPython behavioural changes with the free-threaded -build. - - -Context variables ------------------ - -In the free-threaded build, the flag :data:`~sys.flags.thread_inherit_context` -is set to true by default which causes threads created with -:class:`threading.Thread` to start with a copy of the -:class:`~contextvars.Context()` of the caller of -:meth:`~threading.Thread.start`. In the default GIL-enabled build, the flag -defaults to false so threads start with an -empty :class:`~contextvars.Context()`. - - -Warning filters ---------------- - -In the free-threaded build, the flag :data:`~sys.flags.context_aware_warnings` -is set to true by default. In the default GIL-enabled build, the flag defaults -to false. If the flag is true then the :class:`warnings.catch_warnings` -context manager uses a context variable for warning filters. If the flag is -false then :class:`~warnings.catch_warnings` modifies the global filters list, -which is not thread-safe. See the :mod:`warnings` module for more details. diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 418f514995df3a..8e37179e533f45 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1672,9 +1672,24 @@ Sub-commands :class:`ArgumentParser` supports the creation of such subcommands with the :meth:`!add_subparsers` method. The :meth:`!add_subparsers` method is normally called with no arguments and returns a special action object. This object - has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a - command name and any :class:`!ArgumentParser` constructor arguments, and - returns an :class:`!ArgumentParser` object that can be modified as usual. + has a single method, :meth:`~_SubParsersAction.add_parser`: + + .. method:: _SubParsersAction.add_parser(name, *, help=None, aliases=None, **kwargs) + + Creates and returns a new :class:`!ArgumentParser` object for the + subcommand *name*. + + :param name: The name of the sub-command. + :param help: A short description for this sub-command. If provided, + it will be listed next to the command in the main + parser's help message (e.g., ``PROG --help``). + :param aliases: A list or sequence of strings that can be used as + alternative names for this sub-command (e.g., ``aliases=['r']`` + for a ``'run'`` command). + :param kwargs: All other keyword arguments are passed directly to the + :class:`!ArgumentParser` constructor. + + This returned :class:`!ArgumentParser` object can be modified as usual. Description of parameters: diff --git a/Misc/NEWS.d/next/Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst b/Misc/NEWS.d/next/Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst new file mode 100644 index 00000000000000..0d21195a7df932 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst @@ -0,0 +1,3 @@ +Document ``help`` and ``aliases`` parameters for +:meth:`argparse._SubParsersAction.add_parser` in the :mod:`argparse` +documentation.