Merge branch 'main' of https://github.com/python/cpython

Author: hugovk

Doc/c-api/object.rst

@@ -801,3 +801,20 @@ Object Protocol
    cannot fail.
 
    .. versionadded:: 3.14
+
+.. c:function:: int PyUnstable_SetImmortal(PyObject *op)
+
+   Marks the object *op* :term:`immortal`. The argument should be uniquely referenced by
+   the calling thread. This is intended to be used for reducing reference counting contention
+   in the :term:`free-threaded build` for objects which are shared across threads.
+
+   This is a one-way process: objects can only be made immortal; they cannot be
+   made mortal once again. Immortal objects do not participate in reference counting
+   and will never be garbage collected. If the object is GC-tracked, it is untracked.
+
+   This function is intended to be used soon after *op* is created, by the code that
+   creates it, such as in the object's :c:member:`~PyTypeObject.tp_new` slot.
+   Returns 1 if the object was made immortal and returns 0 if it was not.
+   This function cannot fail.
+
+   .. versionadded:: next

Doc/glossary.rst

@@ -951,6 +951,16 @@ Glossary
       to locks exist such as queues, producer/consumer patterns, and
       thread-local state. See also :term:`deadlock`, and :term:`reentrant`.
 
+   lock-free
+      An operation that does not acquire any :term:`lock` and uses atomic CPU
+      instructions to ensure correctness. Lock-free operations can execute
+      concurrently without blocking each other and cannot be blocked by
+      operations that hold locks. In :term:`free-threaded <free threading>`
+      Python, built-in types like :class:`dict` and :class:`list` provide
+      lock-free read operations, which means other threads may observe
+      intermediate states during multi-step modifications even when those
+      modifications hold the :term:`per-object lock`.
+
    loader
       An object that loads a module.
       It must define the :meth:`!exec_module` and :meth:`!create_module` methods
@@ -1217,6 +1227,16 @@ Glossary
       <faq-argument-vs-parameter>`, the :class:`inspect.Parameter` class, the
       :ref:`function` section, and :pep:`362`.
 
+   per-object lock
+      A :term:`lock` associated with an individual object instance rather than
+      a global lock shared across all objects. In :term:`free-threaded
+      <free threading>` Python, built-in types like :class:`dict` and
+      :class:`list` use per-object locks to allow concurrent operations on
+      different objects while serializing operations on the same object.
+      Operations that hold the per-object lock prevent other locking operations
+      on the same object from proceeding, but do not block :term:`lock-free`
+      operations.
+
    path entry
       A single location on the :term:`import path` which the :term:`path
       based finder` consults to find modules for importing.

Doc/library/codecs.rst

@@ -1551,8 +1551,8 @@ mapping. It is not supported by :meth:`str.encode` (which only produces
    Restoration of the ``rot13`` alias.
 
 
-:mod:`encodings` --- Encodings package
---------------------------------------
+:mod:`!encodings` --- Encodings package
+---------------------------------------
 
 .. module:: encodings
    :synopsis: Encodings package
@@ -1611,8 +1611,8 @@ This module implements the following exception:
    Raised when a codec is invalid or incompatible.
 
 
-:mod:`encodings.idna` --- Internationalized Domain Names in Applications
-------------------------------------------------------------------------
+:mod:`!encodings.idna` --- Internationalized Domain Names in Applications
+-------------------------------------------------------------------------
 
 .. module:: encodings.idna
    :synopsis: Internationalized Domain Names implementation
@@ -1654,7 +1654,7 @@ When receiving host names from the wire (such as in reverse name lookup), no
 automatic conversion to Unicode is performed: applications wishing to present
 such host names to the user should decode them to Unicode.
 
-The module :mod:`encodings.idna` also implements the nameprep procedure, which
+The module :mod:`!encodings.idna` also implements the nameprep procedure, which
 performs certain normalizations on host names, to achieve case-insensitivity of
 international domain names, and to unify similar characters. The nameprep
 functions can be used directly if desired.
@@ -1677,8 +1677,8 @@ functions can be used directly if desired.
    Convert a label to Unicode, as specified in :rfc:`3490`.
 
 
-:mod:`encodings.mbcs` --- Windows ANSI codepage
------------------------------------------------
+:mod:`!encodings.mbcs` --- Windows ANSI codepage
+------------------------------------------------
 
 .. module:: encodings.mbcs
    :synopsis: Windows ANSI codepage
@@ -1695,8 +1695,8 @@ This module implements the ANSI codepage (CP_ACP).
    Support any error handler.
 
 
-:mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature
--------------------------------------------------------------
+:mod:`!encodings.utf_8_sig` --- UTF-8 codec with BOM signature
+--------------------------------------------------------------
 
 .. module:: encodings.utf_8_sig
    :synopsis: UTF-8 codec with BOM signature

Doc/library/curses.rst

@@ -1824,22 +1824,22 @@ The following table lists the predefined colors:
 +-------------------------+----------------------------+
 
 
-:mod:`curses.textpad` --- Text input widget for curses programs
-===============================================================
+:mod:`!curses.textpad` --- Text input widget for curses programs
+================================================================
 
 .. module:: curses.textpad
    :synopsis: Emacs-like input editing in a curses window.
 .. moduleauthor:: Eric Raymond <esr@thyrsus.com>
 .. sectionauthor:: Eric Raymond <esr@thyrsus.com>
 
 
-The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles
+The :mod:`!curses.textpad` module provides a :class:`Textbox` class that handles
 elementary text editing in a curses window, supporting a set of keybindings
 resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x,
 FrameMaker, and many other programs).  The module also provides a
 rectangle-drawing function useful for framing text boxes or for other purposes.
 
-The module :mod:`curses.textpad` defines the following function:
+The module :mod:`!curses.textpad` defines the following function:
 
 
 .. function:: rectangle(win, uly, ulx, lry, lrx)

Doc/library/dbm.rst

@@ -157,8 +157,8 @@ then prints out the contents of the database::
 
 The individual submodules are described in the following sections.
 
-:mod:`dbm.sqlite3` --- SQLite backend for dbm
----------------------------------------------
+:mod:`!dbm.sqlite3` --- SQLite backend for dbm
+----------------------------------------------
 
 .. module:: dbm.sqlite3
    :platform: All
@@ -172,7 +172,7 @@ The individual submodules are described in the following sections.
 
 This module uses the standard library :mod:`sqlite3` module to provide an
 SQLite backend for the :mod:`!dbm` module.
-The files created by :mod:`dbm.sqlite3` can thus be opened by :mod:`sqlite3`,
+The files created by :mod:`!dbm.sqlite3` can thus be opened by :mod:`sqlite3`,
 or any other SQLite browser, including the SQLite CLI.
 
 .. include:: ../includes/wasm-notavail.rst
@@ -220,8 +220,8 @@ or any other SQLite browser, including the SQLite CLI.
       .. versionadded:: 3.15
 
 
-:mod:`dbm.gnu` --- GNU database manager
----------------------------------------
+:mod:`!dbm.gnu` --- GNU database manager
+----------------------------------------
 
 .. module:: dbm.gnu
    :platform: Unix
@@ -231,20 +231,20 @@ or any other SQLite browser, including the SQLite CLI.
 
 --------------
 
-The :mod:`dbm.gnu` module provides an interface to the :abbr:`GDBM (GNU dbm)`
+The :mod:`!dbm.gnu` module provides an interface to the :abbr:`GDBM (GNU dbm)`
 library, similar to the :mod:`dbm.ndbm` module, but with additional
 functionality like crash tolerance.
 
 .. note::
 
-   The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
+   The file formats created by :mod:`!dbm.gnu` and :mod:`dbm.ndbm` are incompatible
    and can not be used interchangeably.
 
 .. include:: ../includes/wasm-mobile-notavail.rst
 
 .. exception:: error
 
-   Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is
+   Raised on :mod:`!dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is
    raised for general mapping errors like specifying an incorrect key.
 
 
@@ -343,8 +343,8 @@ functionality like crash tolerance.
       unwritten data to be written to the disk.
 
 
-:mod:`dbm.ndbm` --- New Database Manager
-----------------------------------------
+:mod:`!dbm.ndbm` --- New Database Manager
+-----------------------------------------
 
 .. module:: dbm.ndbm
    :platform: Unix
@@ -354,14 +354,14 @@ functionality like crash tolerance.
 
 --------------
 
-The :mod:`dbm.ndbm` module provides an interface to the
+The :mod:`!dbm.ndbm` module provides an interface to the
 :abbr:`NDBM (New Database Manager)` library.
 This module can be used with the "classic" NDBM interface or the
 :abbr:`GDBM (GNU dbm)` compatibility interface.
 
 .. note::
 
-   The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
+   The file formats created by :mod:`dbm.gnu` and :mod:`!dbm.ndbm` are incompatible
    and can not be used interchangeably.
 
 .. warning::
@@ -375,7 +375,7 @@ This module can be used with the "classic" NDBM interface or the
 
 .. exception:: error
 
-   Raised on :mod:`dbm.ndbm`-specific errors, such as I/O errors. :exc:`KeyError` is raised
+   Raised on :mod:`!dbm.ndbm`-specific errors, such as I/O errors. :exc:`KeyError` is raised
    for general mapping errors like specifying an incorrect key.
 
 
@@ -425,8 +425,8 @@ This module can be used with the "classic" NDBM interface or the
       Close the NDBM database.
 
 
-:mod:`dbm.dumb` --- Portable DBM implementation
------------------------------------------------
+:mod:`!dbm.dumb` --- Portable DBM implementation
+------------------------------------------------
 
 .. module:: dbm.dumb
    :synopsis: Portable implementation of the simple DBM interface.
@@ -437,14 +437,14 @@ This module can be used with the "classic" NDBM interface or the
 
 .. note::
 
-   The :mod:`dbm.dumb` module is intended as a last resort fallback for the
-   :mod:`!dbm` module when a more robust module is not available. The :mod:`dbm.dumb`
+   The :mod:`!dbm.dumb` module is intended as a last resort fallback for the
+   :mod:`!dbm` module when a more robust module is not available. The :mod:`!dbm.dumb`
    module is not written for speed and is not nearly as heavily used as the other
    database modules.
 
 --------------
 
-The :mod:`dbm.dumb` module provides a persistent :class:`dict`-like
+The :mod:`!dbm.dumb` module provides a persistent :class:`dict`-like
 interface which is written entirely in Python.
 Unlike other :mod:`!dbm` backends, such as :mod:`dbm.gnu`, no
 external library is required.
@@ -453,7 +453,7 @@ The :mod:`!dbm.dumb` module defines the following:
 
 .. exception:: error
 
-   Raised on :mod:`dbm.dumb`-specific errors, such as I/O errors.  :exc:`KeyError` is
+   Raised on :mod:`!dbm.dumb`-specific errors, such as I/O errors.  :exc:`KeyError` is
    raised for general mapping errors like specifying an incorrect key.
 
 
@@ -484,7 +484,7 @@ The :mod:`!dbm.dumb` module defines the following:
       Python's AST compiler.
 
    .. warning::
-      :mod:`dbm.dumb` does not support concurrent read/write access. (Multiple
+      :mod:`!dbm.dumb` does not support concurrent read/write access. (Multiple
       simultaneous read accesses are safe.) When a program has the database open
       for writing, no other program should have it open for reading or writing.
 

Doc/library/dialog.rst

@@ -1,8 +1,8 @@
 Tkinter Dialogs
 ===============
 
-:mod:`tkinter.simpledialog` --- Standard Tkinter input dialogs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:mod:`!tkinter.simpledialog` --- Standard Tkinter input dialogs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. module:: tkinter.simpledialog
    :platform: Tk
@@ -12,7 +12,7 @@ Tkinter Dialogs
 
 --------------
 
-The :mod:`tkinter.simpledialog` module contains convenience classes and
+The :mod:`!tkinter.simpledialog` module contains convenience classes and
 functions for creating simple modal dialogs to get a value from the user.
 
 
@@ -39,8 +39,8 @@ functions for creating simple modal dialogs to get a value from the user.
 
 
 
-:mod:`tkinter.filedialog` --- File selection dialogs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:mod:`!tkinter.filedialog` --- File selection dialogs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. module:: tkinter.filedialog
    :platform: Tk
@@ -50,7 +50,7 @@ functions for creating simple modal dialogs to get a value from the user.
 
 --------------
 
-The :mod:`tkinter.filedialog` module provides classes and factory functions for
+The :mod:`!tkinter.filedialog` module provides classes and factory functions for
 creating file/directory selection windows.
 
 Native Load/Save Dialogs
@@ -204,8 +204,8 @@ These do not emulate the native look-and-feel of the platform.
       directory. Confirmation is required if an already existing file is
       selected.
 
-:mod:`tkinter.commondialog` --- Dialog window templates
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:mod:`!tkinter.commondialog` --- Dialog window templates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. module:: tkinter.commondialog
    :platform: Tk
@@ -215,7 +215,7 @@ These do not emulate the native look-and-feel of the platform.
 
 --------------
 
-The :mod:`tkinter.commondialog` module provides the :class:`Dialog` class that
+The :mod:`!tkinter.commondialog` module provides the :class:`Dialog` class that
 is the base class for dialogs defined in other supporting modules.
 
 .. class:: Dialog(master=None, **options)

Doc/library/email.encoders.rst

@@ -25,7 +25,7 @@ is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type message
 containing binary data.
 
 The :mod:`email` package provides some convenient encoders in its
-:mod:`~email.encoders` module.  These encoders are actually used by the
+:mod:`!encoders` module.  These encoders are actually used by the
 :class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
 class constructors to provide default encodings.  All encoder functions take
 exactly one argument, the message object to encode.  They usually extract the

Doc/library/email.policy.rst

@@ -602,7 +602,7 @@ The header objects and their attributes are described in
 
    This concrete :class:`Policy` is the backward compatibility policy.  It
    replicates the behavior of the email package in Python 3.2.  The
-   :mod:`~email.policy` module also defines an instance of this class,
+   :mod:`!policy` module also defines an instance of this class,
    :const:`compat32`, that is used as the default policy.  Thus the default
    behavior of the email package is to maintain compatibility with Python 3.2.
 

Doc/library/importlib.rst

@@ -215,8 +215,8 @@ Functions
       in unexpected behavior. It's recommended to use the :class:`threading.Lock`
       or other synchronization primitives for thread-safe module reloading.
 
-:mod:`importlib.abc` -- Abstract base classes related to import
----------------------------------------------------------------
+:mod:`!importlib.abc` -- Abstract base classes related to import
+----------------------------------------------------------------
 
 .. module:: importlib.abc
     :synopsis: Abstract base classes related to import
@@ -226,7 +226,7 @@ Functions
 --------------
 
 
-The :mod:`importlib.abc` module contains all of the core abstract base classes
+The :mod:`!importlib.abc` module contains all of the core abstract base classes
 used by :keyword:`import`. Some subclasses of the core abstract base classes
 are also provided to help in implementing the core ABCs.
 
@@ -596,8 +596,8 @@ ABC hierarchy::
         itself does not end in ``__init__``.
 
 
-:mod:`importlib.machinery` -- Importers and path hooks
-------------------------------------------------------
+:mod:`!importlib.machinery` -- Importers and path hooks
+-------------------------------------------------------
 
 .. module:: importlib.machinery
     :synopsis: Importers and path hooks
@@ -1112,8 +1112,8 @@ find and load modules.
       Path to the ``.fwork`` file for the extension module.
 
 
-:mod:`importlib.util` -- Utility code for importers
----------------------------------------------------
+:mod:`!importlib.util` -- Utility code for importers
+----------------------------------------------------
 
 .. module:: importlib.util
     :synopsis: Utility code for importers