From 810fde134f0ecef435e40c03290254e5b7f3c4e7 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Fri, 24 Oct 2025 20:55:48 +0530 Subject: [PATCH 01/30] gh-140281: Doc: Update free-threading how-to --- Doc/howto/free-threading-python.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst index 24069617c47ae1..cdfd1e28de7094 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -116,12 +116,12 @@ after the main thread is running. The following objects are immortalized: * :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. +objects of these types may see increased memory usage. Work to further reduce +this overhead continued 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. +returned by :func:`sys.intern` are also immortalized. This behavior remains +in the 3.14 free-threaded build. Frame objects @@ -152,9 +152,10 @@ 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. +expected to be reduced in upcoming Python release. This overhead **was reduced** +in the 3.14 release. Reducing overhead further **remains an active development goal**, +with an aim for 10% or less on the pyperformance suite compared to the default GIL-enabled +build. Behavioral changes From b9ca059fb1c0c84b8be72356bb5801a22120f0a0 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Fri, 24 Oct 2025 21:00:03 +0530 Subject: [PATCH 02/30] gh-140281: Doc: Update free-threading how-to --- Doc/howto/free-threading-python.rst | 4 ++-- .../2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst index cdfd1e28de7094..1b82fb372188b7 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -152,8 +152,8 @@ 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. This overhead **was reduced** -in the 3.14 release. Reducing overhead further **remains an active development goal**, +expected to be reduced in upcoming Python release. This overhead was reduced +in the 3.14 release. Reducing overhead further remains an active development goal, with an aim for 10% or less on the pyperformance suite compared to the default GIL-enabled build. diff --git a/Misc/NEWS.d/next/Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst b/Misc/NEWS.d/next/Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst new file mode 100644 index 00000000000000..884b13b0077d73 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst @@ -0,0 +1 @@ +Update the free-threading how-to guide for 3.14 status. From 16a1c465e85da250e92245247013680626102d8a Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 01:48:41 +0530 Subject: [PATCH 03/30] Fix trailing whitespace --- Doc/howto/free-threading-python.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst index 1b82fb372188b7..85640e1f143ae2 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -116,11 +116,11 @@ after the main thread is running. The following objects are immortalized: * :ref:`classes ` (type objects) Because immortal objects are never deallocated, applications that create many -objects of these types may see increased memory usage. Work to further reduce +objects of these types may see increased memory usage. Work to further reduce this overhead continued 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 remains +returned by :func:`sys.intern` are also immortalized. This behavior remains in the 3.14 free-threaded build. @@ -154,8 +154,8 @@ 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. This overhead was reduced in the 3.14 release. Reducing overhead further remains an active development goal, -with an aim for 10% or less on the pyperformance suite compared to the default GIL-enabled -build. +with an aim for 10% or less on the pyperformance suite compared to the default GIL-enabled +build. Behavioral changes From 3f0aa483ab632cf3e0e068ca7f0ff541ff0e49e8 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 14:03:23 +0530 Subject: [PATCH 04/30] doc fixing of the cpython fixes#84116 --- Doc/library/argparse.rst | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 418f514995df3a..56f9fc8bde403a 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1672,10 +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: * *title* - title for the sub-parser group in help output; by default From 343648b7a4edfd12cc8428e851b54c80af31c941 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 15:45:31 +0530 Subject: [PATCH 05/30] Docs: Document help and aliases for argparse.add_parser() (gh-84116) --- .../2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst 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. From 4b07ba3c5178046328347ddec19590f9f715f5a2 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 16:05:01 +0530 Subject: [PATCH 06/30] Docs: Document help and aliases for argparse.add_parser() (gh-84116) --- Doc/library/argparse.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 56f9fc8bde403a..180a4a6510fdce 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1673,6 +1673,7 @@ Sub-commands :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`: + .. method:: _SubParsersAction.add_parser(name, *, help=None, aliases=None, **kwargs) Creates and returns a new :class:`!ArgumentParser` object for the @@ -1687,7 +1688,7 @@ Sub-commands 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: From 8bb4bae60eb458605c39c9f28a622d05382c8544 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 16:16:25 +0530 Subject: [PATCH 07/30] Fix trailing whitespace --- Doc/library/argparse.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 180a4a6510fdce..3230b29fd50073 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1690,7 +1690,6 @@ Sub-commands :class:`!ArgumentParser` constructor. This returned :class:`!ArgumentParser` object can be modified as usual. - Description of parameters: * *title* - title for the sub-parser group in help output; by default From 3361447262f447bf84670c65a43f9c5fc9331385 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 16:25:24 +0530 Subject: [PATCH 08/30] Fix trailing whitespace --- Doc/library/argparse.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 3230b29fd50073..f3e1b816181078 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1687,8 +1687,7 @@ Sub-commands 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. - + :class:`!ArgumentParser` constructor. This returned :class:`!ArgumentParser` object can be modified as usual. Description of parameters: From 100207d9a48df71f790223a7b1a4e83505213450 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 16:29:25 +0530 Subject: [PATCH 09/30] Fix trailing whitespace --- Doc/library/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index f3e1b816181078..b7144628fde539 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1687,7 +1687,7 @@ Sub-commands 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. + :class:`!ArgumentParser` constructor. This returned :class:`!ArgumentParser` object can be modified as usual. Description of parameters: From 0f27e636433b514fb69bc15cb1c2be235b6889b9 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 16:34:25 +0530 Subject: [PATCH 10/30] Fix trailing whitespace --- Doc/library/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index b7144628fde539..f8c5bdbc2e8eda 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1687,7 +1687,7 @@ Sub-commands 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. + :class:`!ArgumentParser` constructor. This returned :class:`!ArgumentParser` object can be modified as usual. Description of parameters: From 7e6102ada5fb4831ef87ee39c8bc83513d9ed9b3 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 16:40:44 +0530 Subject: [PATCH 11/30] Fix trailing whitespace --- Doc/library/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index f8c5bdbc2e8eda..a8eac8f40e076d 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1687,7 +1687,7 @@ Sub-commands 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. + :class:`!ArgumentParser` constructor. This returned :class:`!ArgumentParser` object can be modified as usual. Description of parameters: From a76954c4f44bd0a107d6f818cff7ec3d70527476 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 16:55:53 +0530 Subject: [PATCH 12/30] Fix trailing whitespace --- Doc/library/argparse.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index a8eac8f40e076d..3e8790e1b0bf22 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1676,19 +1676,19 @@ Sub-commands .. 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. + 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: * *title* - title for the sub-parser group in help output; by default From ac2b754734e2b89a8d37750588e3f68b67db96ad Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 17:02:45 +0530 Subject: [PATCH 13/30] Fix trailing errors --- Doc/library/argparse.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 3e8790e1b0bf22..9ba1da361ad936 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1688,7 +1688,9 @@ Sub-commands 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: * *title* - title for the sub-parser group in help output; by default From b08e8edc88a9a6427e59a1391e55dceb03dff8bd Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 17:06:40 +0530 Subject: [PATCH 14/30] Fix trailing errors and spaces --- Doc/library/argparse.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 9ba1da361ad936..3123f9f1423e11 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1690,7 +1690,6 @@ Sub-commands :class:`!ArgumentParser` constructor. This returned :class:`!ArgumentParser` object can be modified as usual. - Description of parameters: * *title* - title for the sub-parser group in help output; by default From fa1d8770649fb7307acef560febdc3ff5aa7ed90 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 17:14:07 +0530 Subject: [PATCH 15/30] Fix docutils formatting, NEWS ref, and trailing whitespace --- Doc/library/argparse.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 3123f9f1423e11..9ba1da361ad936 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1690,6 +1690,7 @@ Sub-commands :class:`!ArgumentParser` constructor. This returned :class:`!ArgumentParser` object can be modified as usual. + Description of parameters: * *title* - title for the sub-parser group in help output; by default From e955fb0c994bf1fb7c89d6f8fd4efb8b007e1829 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 19:27:43 +0530 Subject: [PATCH 16/30] Docs: Update argparse.rst and add NEWS entry --- Doc/library/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 9ba1da361ad936..8e37179e533f45 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1690,7 +1690,7 @@ Sub-commands :class:`!ArgumentParser` constructor. This returned :class:`!ArgumentParser` object can be modified as usual. - + Description of parameters: * *title* - title for the sub-parser group in help output; by default From 3d4cf26424a88c4209a2ec33facc1dca4daf3f57 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 19:29:32 +0530 Subject: [PATCH 17/30] Delete Doc/howto/free-threading-python.rst --- Doc/howto/free-threading-python.rst | 188 ---------------------------- 1 file changed, 188 deletions(-) delete mode 100644 Doc/howto/free-threading-python.rst diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst deleted file mode 100644 index 85640e1f143ae2..00000000000000 --- a/Doc/howto/free-threading-python.rst +++ /dev/null @@ -1,188 +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. Work to further reduce -this overhead continued 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 remains -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. This overhead was reduced -in the 3.14 release. Reducing overhead further remains an active development goal, -with an aim for 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. From e3af10b812177199c3059bee964dc68699a081a8 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Sat, 25 Oct 2025 19:30:02 +0530 Subject: [PATCH 18/30] Delete Misc/NEWS.d/next/Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst --- .../Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst | 1 - 1 file changed, 1 deletion(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst diff --git a/Misc/NEWS.d/next/Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst b/Misc/NEWS.d/next/Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst deleted file mode 100644 index 884b13b0077d73..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst +++ /dev/null @@ -1 +0,0 @@ -Update the free-threading how-to guide for 3.14 status. From 59a1ad9c04eac55d05e73e25b50abb9bc3a205f5 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Mon, 8 Dec 2025 23:24:19 +0530 Subject: [PATCH 19/30] adding the depreceated tag --- Doc/library/argparse.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 8e37179e533f45..9c3feb3cbea507 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1674,7 +1674,7 @@ Sub-commands called with no arguments and returns a special action object. This object has a single method, :meth:`~_SubParsersAction.add_parser`: - .. method:: _SubParsersAction.add_parser(name, *, help=None, aliases=None, **kwargs) + .. method:: _SubParsersAction.add_parser(name, *, help=None, aliases=None, deprecated=False, **kwargs) Creates and returns a new :class:`!ArgumentParser` object for the subcommand *name*. @@ -1686,6 +1686,8 @@ Sub-commands :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 deprecated:If :const:`True`, marks the sub-command as deprecated, + which typically issues a warning when used. :param kwargs: All other keyword arguments are passed directly to the :class:`!ArgumentParser` constructor. From defd2c3de2987911694bbde96e8b88e48f8b8bbe Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Tue, 9 Dec 2025 00:08:25 +0530 Subject: [PATCH 20/30] The error indexing was fixed --- Doc/library/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 9c3feb3cbea507..370fa7d3636c04 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1686,7 +1686,7 @@ Sub-commands :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 deprecated:If :const:`True`, marks the sub-command as deprecated, + :param deprecated: If :const:`True`, marks the sub-command as deprecated, which typically issues a warning when used. :param kwargs: All other keyword arguments are passed directly to the :class:`!ArgumentParser` constructor. From cd445fcb8cffea966500fe07c23cba09329aadd1 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Tue, 9 Dec 2025 00:20:09 +0530 Subject: [PATCH 21/30] Fix trailing whitespace --- Doc/library/argparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 370fa7d3636c04..e90cf17b1c7ec8 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1686,8 +1686,8 @@ Sub-commands :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 deprecated: If :const:`True`, marks the sub-command as deprecated, - which typically issues a warning when used. + :param deprecated: If :const:`True`, marks the sub-command as deprecated, + which typically issues a warning when used. :param kwargs: All other keyword arguments are passed directly to the :class:`!ArgumentParser` constructor. From 2e270ef56f1b4bcccfea44927f0cd50533ad38f1 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Tue, 9 Dec 2025 00:28:04 +0530 Subject: [PATCH 22/30] Restore missing free-threading documentation --- Doc/howto/free-threading-python.rst | 187 ++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 Doc/howto/free-threading-python.rst diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst new file mode 100644 index 00000000000000..24069617c47ae1 --- /dev/null +++ b/Doc/howto/free-threading-python.rst @@ -0,0 +1,187 @@ +.. _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. From 3e87e19e3deffb516b3a24375bc85670b1784849 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Tue, 9 Dec 2025 01:36:44 +0530 Subject: [PATCH 23/30] fixing some minor error --- Doc/library/argparse.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index e90cf17b1c7ec8..eaff43c121b053 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1686,8 +1686,8 @@ Sub-commands :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 deprecated: If :const:`True`, marks the sub-command as deprecated, - which typically issues a warning when used. + :param deprecated: If :const:`True`, marks the sub-command as deprecated, + which typically issues a warning when used. :param kwargs: All other keyword arguments are passed directly to the :class:`!ArgumentParser` constructor. @@ -1744,7 +1744,7 @@ Sub-commands >>> parser.parse_args(['--foo', 'b', '--baz', 'Z']) Namespace(baz='Z', foo=True) - Note that the object returned by :meth:`parse_args` will only contain + Note that the object returned by :meth:`~ArgumentParser.parse_args` will only contain attributes for the main parser and the subparser that was selected by the command line (and not any other subparsers). So in the example above, when the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are @@ -1755,7 +1755,7 @@ Sub-commands for that particular parser will be printed. The help message will not include parent parser or sibling parser messages. (A help message for each subparser command, however, can be given by supplying the ``help=`` argument - to :meth:`~_SubParsersAction.add_parser` as above.) + to ``add_parser()`` as above.) :: @@ -1787,7 +1787,7 @@ Sub-commands -h, --help show this help message and exit --baz {X,Y,Z} baz help - The :meth:`add_subparsers` method also supports ``title`` and ``description`` + The :meth:`~ArgumentParser.add_subparsers` method also supports ``title`` and ``description`` keyword arguments. When either is present, the subparser's commands will appear in their own group in the help output. For example:: From 1867c7103659397c8a9a9b401a116b2860dd0736 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Tue, 9 Dec 2025 01:49:45 +0530 Subject: [PATCH 24/30] fixing some minor error part 2 --- Doc/library/argparse.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index eaff43c121b053..da28dd69558427 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1835,7 +1835,7 @@ Sub-commands .. versionadded:: 3.13 One particularly effective way of handling subcommands is to combine the use - of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so + of the :meth:`~ArgumentParser.add_subparsers` method with calls to :meth:`~ArgumentParser.set_defaults` so that each subparser knows which Python function it should execute. For example:: @@ -1871,12 +1871,12 @@ Sub-commands >>> args.func(args) ((XYZYX)) - This way, you can let :meth:`parse_args` do the job of calling the + This way, you can let :meth:`~ArgumentParser.parse_args` do the job of calling the appropriate function after argument parsing is complete. Associating functions with actions like this is typically the easiest way to handle the different actions for each of your subparsers. However, if it is necessary to check the name of the subparser that was invoked, the ``dest`` keyword - argument to the :meth:`add_subparsers` call will work:: + argument to the :meth:`~ArgumentParser.add_subparsers` call will work:: >>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers(dest='subparser_name') From ef450f63e5de705ebfec7ef4a2e812e652f47202 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Tue, 9 Dec 2025 01:52:52 +0530 Subject: [PATCH 25/30] fixing some minor error part 3 --- Doc/library/argparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index da28dd69558427..8438f3c65329d0 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1686,8 +1686,8 @@ Sub-commands :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 deprecated: If :const:`True`, marks the sub-command as deprecated, - which typically issues a warning when used. + :param deprecated: If :const:`True`, marks the sub-command as deprecated, + which typically issues a warning when used. :param kwargs: All other keyword arguments are passed directly to the :class:`!ArgumentParser` constructor. From 4d27843b174fa23395241787f3e302b2991bae3c Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Tue, 9 Dec 2025 02:02:48 +0530 Subject: [PATCH 26/30] Fix NEWS entry format --- .../Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 0d21195a7df932..7abb3600acc8c3 100644 --- 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 @@ -1,3 +1,3 @@ Document ``help`` and ``aliases`` parameters for -:meth:`argparse._SubParsersAction.add_parser` in the :mod:`argparse` +`argparse._SubParsersAction.add_parser` in the :mod:`argparse` documentation. From 83ff9bf2656e3f3aabf29e637af1ad00efd81e6b Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Tue, 9 Dec 2025 02:56:06 +0530 Subject: [PATCH 27/30] Final cleanup of NEWS entry format 2 --- .../Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 7abb3600acc8c3..3a0ea841da94d3 100644 --- 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 @@ -1,3 +1,3 @@ Document ``help`` and ``aliases`` parameters for -`argparse._SubParsersAction.add_parser` in the :mod:`argparse` +``argparse._SubParsersAction.add_parser`` in the :mod:`argparse` documentation. From 77cc182ba9b58816228685887428449a58274e51 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Tue, 9 Dec 2025 05:01:31 +0530 Subject: [PATCH 28/30] changes in the argparse.rst --- Doc/library/argparse.rst | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 8438f3c65329d0..81a47100d381e6 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1679,18 +1679,14 @@ Sub-commands 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 deprecated: If :const:`True`, marks the sub-command as deprecated, - which typically issues a warning when used. - :param kwargs: All other keyword arguments are passed directly to the - :class:`!ArgumentParser` constructor. + The *name* argument is the name of the sub-command. + The *help* argument provides 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``). + The *aliases* argument allows to provide a sequence of strings that can be used as alternative names for this sub-command (e.g., ``aliases=['r']`` for a ``'run'`` command). + + The *deprecated* argument, if :const:`True`, marks the sub-command as deprecated, which typically issues a warning when used. + 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: From 1a5c449dc581238d0966b171b070f39123d1acdc Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Tue, 9 Dec 2025 05:02:25 +0530 Subject: [PATCH 29/30] Remove unnecessary NEWS entry --- .../2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst 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 deleted file mode 100644 index 3a0ea841da94d3..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst +++ /dev/null @@ -1,3 +0,0 @@ -Document ``help`` and ``aliases`` parameters for -``argparse._SubParsersAction.add_parser`` in the :mod:`argparse` -documentation. From 2dd07bb6bb4c2da79c406138f17013ae75f18ea3 Mon Sep 17 00:00:00 2001 From: Krishna-web-hub Date: Thu, 11 Dec 2025 23:17:52 +0530 Subject: [PATCH 30/30] Fixing the issue as requested --- Doc/library/argparse.rst | 24 +++++++++---------- ...5-10-25-14-08-42.gh-issue-84116.lKcoHw.rst | 3 +++ 2 files changed, 15 insertions(+), 12 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 81a47100d381e6..60c277acb93a59 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1656,7 +1656,7 @@ The Namespace object Other utilities --------------- -Sub-commands +Subcommands ^^^^^^^^^^^^ .. method:: ArgumentParser.add_subparsers(*, [title], [description], [prog], \ @@ -1679,42 +1679,42 @@ Sub-commands Creates and returns a new :class:`!ArgumentParser` object for the subcommand *name*. - The *name* argument is the name of the sub-command. - The *help* argument provides 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``). + The *name* argument is the name of the subcommand. + The *help* argument provides a short description for this subcommand. If provided, it will be listed next to the command in the main parser's help message (e.g., ``PROG --help``). - The *aliases* argument allows to provide a sequence of strings that can be used as alternative names for this sub-command (e.g., ``aliases=['r']`` for a ``'run'`` command). + The *aliases* argument allows to provide a sequence of strings that can be used as alternative names for this subcommand (e.g., ``aliases=['r']`` for a ``'run'`` command). - The *deprecated* argument, if :const:`True`, marks the sub-command as deprecated, which typically issues a warning when used. + The *deprecated* argument, if :const:`True`, marks the subcommand as deprecated, which typically issues a warning when used. 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: - * *title* - title for the sub-parser group in help output; by default + * *title* - title for the subparser group in help output; by default "subcommands" if description is provided, otherwise uses title for positional arguments - * *description* - description for the sub-parser group in help output, by + * *description* - description for the subparser group in help output, by default ``None`` - * *prog* - usage information that will be displayed with sub-command help, + * *prog* - usage information that will be displayed with subcommand help, by default the name of the program and any positional arguments before the subparser argument - * *parser_class* - class which will be used to create sub-parser instances, by + * *parser_class* - class which will be used to create subparser instances, by default the class of the current parser (e.g. :class:`ArgumentParser`) * action_ - the basic type of action to be taken when this argument is encountered at the command line - * dest_ - name of the attribute under which sub-command name will be + * dest_ - name of the attribute under which subcommand name will be stored; by default ``None`` and no value is stored * required_ - Whether or not a subcommand must be provided, by default ``False`` (added in 3.7) - * help_ - help for sub-parser group in help output, by default ``None`` + * help_ - help for subparser group in help output, by default ``None`` * metavar_ - string presenting available subcommands in help; by default it is ``None`` and presents subcommands in form {cmd1, cmd2, ..} @@ -2254,7 +2254,7 @@ Registering custom types or actions Sometimes it's desirable to use a custom string in error messages to provide more user-friendly output. In these cases, :meth:`!register` can be used to - register custom actions or types with a parser and allow you to reference the + register custom actions or types with a parser anto reference the type by their registered name instead of their callable name. The :meth:`!register` method accepts three arguments - a *registry_name*, 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..3a0ea841da94d3 --- /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 +``argparse._SubParsersAction.add_parser`` in the :mod:`argparse` +documentation.