Merge branch 'main' into nitpick_ignore

.github/workflows/reusable-docs.yml

@@ -28,35 +28,28 @@ jobs:
         cache-dependency-path: 'Doc/requirements.txt'
     - name: 'Install build dependencies'
       run: make -C Doc/ venv
-    - name: 'Build HTML documentation'
-      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
 
-    # Add pull request annotations for Sphinx nitpicks (missing references)
+    # To annotate PRs with Sphinx nitpicks (missing references)
     - name: 'Get list of changed files'
       if: github.event_name == 'pull_request'
       id: changed_files
       uses: Ana06/get-changed-files@v2.2.0
       with:
         filter: "Doc/**"
         format: csv  # works for paths with spaces
-    - name: 'Build changed files in nit-picky mode'
-      if: github.event_name == 'pull_request'
+    - name: 'Build HTML documentation'
       continue-on-error: true
       run: |
         set -Eeuo pipefail
-        # Mark files the pull request modified
-        python Doc/tools/touch-clean-files.py --clean '${{ steps.changed_files.outputs.added_modified }}'
-        # Build docs with the '-n' (nit-picky) option; convert warnings to annotations
-        make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n --keep-going" html 2>&1 |
-            python Doc/tools/warnings-to-gh-actions.py
-
-    # Ensure some files always pass Sphinx nit-picky mode (no missing references)
-    - name: 'Build known-good files in nit-picky mode'
+        # Build docs with the '-n' (nit-picky) option; write warnings to file
+        make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going -w sphinx-warnings.txt" html
+    - name: 'Check warnings'
+      if: github.event_name == 'pull_request'
       run: |
-        # Mark files that must pass nit-picky
-        python Doc/tools/touch-clean-files.py
-        # Build docs with the '-n' (nit-picky) option, convert warnings to errors (-W)
-        make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going" html 2>&1
+        python Doc/tools/check-warnings.py \
+          --check-and-annotate '${{ steps.changed_files.outputs.added_modified }}' \
+          --fail-if-regression \
+          --fail-if-improved
 
   # This build doesn't use problem matchers or check annotations
   build_doc_oldest_supported_sphinx:

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
         types_or: [c, python, rst]
 
   - repo: https://github.com/sphinx-contrib/sphinx-lint
-    rev: v0.6.7
+    rev: v0.6.8
     hooks:
       - id: sphinx-lint
         args: [--enable=default-role]

Doc/c-api/dict.rst

@@ -93,10 +93,26 @@ Dictionary Objects
    Return ``0`` on success or ``-1`` on failure.
 
 
+.. c:function:: int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)
+
+   Return a new :term:`strong reference` to the object from dictionary *p*
+   which has a key *key*:
+
+   * If the key is present, set *\*result* to a new :term:`strong reference`
+     to the value and return ``1``.
+   * If the key is missing, set *\*result* to ``NULL`` and return ``0``.
+   * On error, raise an exception and return ``-1``.
+
+   .. versionadded:: 3.13
+
+   See also the :c:func:`PyObject_GetItem` function.
+
+
 .. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
 
-   Return the object from dictionary *p* which has a key *key*.  Return ``NULL``
-   if the key *key* is not present, but *without* setting an exception.
+   Return a :term:`borrowed reference` to the object from dictionary *p* which
+   has a key *key*.  Return ``NULL`` if the key *key* is missing *without*
+   setting an exception.
 
    .. note::
 
@@ -131,6 +147,14 @@ Dictionary Objects
       :c:func:`PyUnicode_FromString` *key* instead.
 
 
+.. c:function:: int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)
+
+   Similar than :c:func:`PyDict_GetItemRef`, but *key* is specified as a
+   :c:expr:`const char*`, rather than a :c:expr:`PyObject*`.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
 
    This is the same as the Python-level :meth:`dict.setdefault`.  If present, it

Doc/c-api/exceptions.rst

@@ -666,7 +666,7 @@ Signal Handling
    to interrupt an operation).
 
    If the given signal isn't handled by Python (it was set to
-   :data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), it will be ignored.
+   :py:const:`signal.SIG_DFL` or :py:const:`signal.SIG_IGN`), it will be ignored.
 
    If *signum* is outside of the allowed range of signal numbers, ``-1``
    is returned.  Otherwise, ``0`` is returned.  The error indicator is

Doc/c-api/import.rst

@@ -142,9 +142,9 @@ Importing Modules
    read from a Python bytecode file or obtained from the built-in function
    :func:`compile`, load the module.  Return a new reference to the module object,
    or ``NULL`` with an exception set if an error occurred.  *name*
-   is removed from :attr:`sys.modules` in error cases, even if *name* was already
-   in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`.  Leaving
-   incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
+   is removed from :data:`sys.modules` in error cases, even if *name* was already
+   in :data:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`.  Leaving
+   incompletely initialized modules in :data:`sys.modules` is dangerous, as imports of
    such modules have no way to know that the module object is an unknown (and
    probably damaged with respect to the module author's intents) state.
 

Doc/faq/library.rst

@@ -566,7 +566,7 @@ use ``p.read(n)``.
    Note on a bug in popen2: unless your program calls ``wait()`` or
    ``waitpid()``, finished child processes are never removed, and eventually
    calls to popen2 will fail because of a limit on the number of child
-   processes.  Calling :func:`os.waitpid` with the :data:`os.WNOHANG` option can
+   processes.  Calling :func:`os.waitpid` with the :const:`os.WNOHANG` option can
    prevent this; a good place to insert such a call would be before calling
    ``popen2`` again.
 

Doc/install/index.rst

@@ -313,9 +313,9 @@ install into it.  It is enabled with a simple option::
 
    python setup.py install --user
 
-Files will be installed into subdirectories of :data:`site.USER_BASE` (written
+Files will be installed into subdirectories of :const:`site.USER_BASE` (written
 as :file:`{userbase}` hereafter).  This scheme installs pure Python modules and
-extension modules in the same location (also known as :data:`site.USER_SITE`).
+extension modules in the same location (also known as :const:`site.USER_SITE`).
 Here are the values for UNIX, including macOS:
 
 =============== ===========================================================

Doc/library/__main__.rst

@@ -336,12 +336,12 @@ Note that importing ``__main__`` doesn't cause any issues with unintentionally
 running top-level code meant for script use which is put in the
 ``if __name__ == "__main__"`` block of the ``start`` module. Why does this work?
 
-Python inserts an empty ``__main__`` module in :attr:`sys.modules` at
+Python inserts an empty ``__main__`` module in :data:`sys.modules` at
 interpreter startup, and populates it by running top-level code. In our example
 this is the ``start`` module which runs line by line and imports ``namely``.
 In turn, ``namely`` imports ``__main__`` (which is really ``start``). That's an
 import cycle! Fortunately, since the partially populated ``__main__``
-module is present in :attr:`sys.modules`, Python passes that to ``namely``.
+module is present in :data:`sys.modules`, Python passes that to ``namely``.
 See :ref:`Special considerations for __main__ <import-dunder-main>` in the
 import system's reference for details on how this works.
 

Doc/library/_thread.rst

@@ -70,10 +70,10 @@ This module defines the following constants and functions:
    there is no guarantee that the interruption will happen immediately.
 
    If given, *signum* is the number of the signal to simulate.
-   If *signum* is not given, :data:`signal.SIGINT` is simulated.
+   If *signum* is not given, :const:`signal.SIGINT` is simulated.
 
    If the given signal isn't handled by Python (it was set to
-   :data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), this function does
+   :const:`signal.SIG_DFL` or :const:`signal.SIG_IGN`), this function does
    nothing.
 
    .. versionchanged:: 3.10

Doc/library/asyncio-dev.rst

@@ -34,7 +34,7 @@ There are several ways to enable asyncio debug mode:
 In addition to enabling the debug mode, consider also:
 
 * setting the log level of the :ref:`asyncio logger <asyncio-logger>` to
-  :py:data:`logging.DEBUG`, for example the following snippet of code
+  :py:const:`logging.DEBUG`, for example the following snippet of code
   can be run at startup of the application::
 
     logging.basicConfig(level=logging.DEBUG)
@@ -142,7 +142,7 @@ Logging
 asyncio uses the :mod:`logging` module and all logging is performed
 via the ``"asyncio"`` logger.
 
-The default log level is :py:data:`logging.INFO`, which can be easily
+The default log level is :py:const:`logging.INFO`, which can be easily
 adjusted::
 
    logging.getLogger("asyncio").setLevel(logging.WARNING)

Doc/library/asyncio-eventloop.rst

@@ -403,11 +403,11 @@ Opening network connections
    Open a streaming transport connection to a given
    address specified by *host* and *port*.
 
-   The socket family can be either :py:data:`~socket.AF_INET` or
-   :py:data:`~socket.AF_INET6` depending on *host* (or the *family*
+   The socket family can be either :py:const:`~socket.AF_INET` or
+   :py:const:`~socket.AF_INET6` depending on *host* (or the *family*
    argument, if provided).
 
-   The socket type will be :py:data:`~socket.SOCK_STREAM`.
+   The socket type will be :py:const:`~socket.SOCK_STREAM`.
 
    *protocol_factory* must be a callable returning an
    :ref:`asyncio protocol <asyncio-protocol>` implementation.
@@ -509,7 +509,7 @@ Opening network connections
 
    .. versionchanged:: 3.6
 
-      The socket option :py:data:`~socket.TCP_NODELAY` is set by default
+      The socket option :py:const:`~socket.TCP_NODELAY` is set by default
       for all TCP connections.
 
    .. versionchanged:: 3.7
@@ -552,11 +552,11 @@ Opening network connections
 
    Create a datagram connection.
 
-   The socket family can be either :py:data:`~socket.AF_INET`,
-   :py:data:`~socket.AF_INET6`, or :py:data:`~socket.AF_UNIX`,
+   The socket family can be either :py:const:`~socket.AF_INET`,
+   :py:const:`~socket.AF_INET6`, or :py:const:`~socket.AF_UNIX`,
    depending on *host* (or the *family* argument, if provided).
 
-   The socket type will be :py:data:`~socket.SOCK_DGRAM`.
+   The socket type will be :py:const:`~socket.SOCK_DGRAM`.
 
    *protocol_factory* must be a callable returning a
    :ref:`protocol <asyncio-protocol>` implementation.
@@ -581,7 +581,7 @@ Opening network connections
    * *reuse_port* tells the kernel to allow this endpoint to be bound to the
      same port as other existing endpoints are bound to, so long as they all
      set this flag when being created. This option is not supported on Windows
-     and some Unixes. If the :py:data:`~socket.SO_REUSEPORT` constant is not
+     and some Unixes. If the :py:const:`~socket.SO_REUSEPORT` constant is not
      defined then this capability is unsupported.
 
    * *allow_broadcast* tells the kernel to allow this endpoint to send
@@ -607,7 +607,7 @@ Opening network connections
 
    .. versionchanged:: 3.8.1
       The *reuse_address* parameter is no longer supported, as using
-      :py:data:`~sockets.SO_REUSEADDR` poses a significant security concern for
+      :py:const:`~sockets.SO_REUSEADDR` poses a significant security concern for
       UDP. Explicitly passing ``reuse_address=True`` will raise an exception.
 
       When multiple processes with differing UIDs assign sockets to an
@@ -616,7 +616,7 @@ Opening network connections
 
       For supported platforms, *reuse_port* can be used as a replacement for
       similar functionality. With *reuse_port*,
-      :py:data:`~sockets.SO_REUSEPORT` is used instead, which specifically
+      :py:const:`~sockets.SO_REUSEPORT` is used instead, which specifically
       prevents processes with differing UIDs from assigning sockets to the same
       socket address.
 
@@ -634,8 +634,8 @@ Opening network connections
 
    Create a Unix connection.
 
-   The socket family will be :py:data:`~socket.AF_UNIX`; socket
-   type will be :py:data:`~socket.SOCK_STREAM`.
+   The socket family will be :py:const:`~socket.AF_UNIX`; socket
+   type will be :py:const:`~socket.SOCK_STREAM`.
 
    A tuple of ``(transport, protocol)`` is returned on success.
 
@@ -671,7 +671,7 @@ Creating network servers
                         ssl_shutdown_timeout=None, \
                         start_serving=True)
 
-   Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) listening
+   Create a TCP server (socket type :const:`~socket.SOCK_STREAM`) listening
    on *port* of the *host* address.
 
    Returns a :class:`Server` object.
@@ -699,10 +699,10 @@ Creating network servers
      be selected (note that if *host* resolves to multiple network interfaces,
      a different random port will be selected for each interface).
 
-   * *family* can be set to either :data:`socket.AF_INET` or
-     :data:`~socket.AF_INET6` to force the socket to use IPv4 or IPv6.
+   * *family* can be set to either :const:`socket.AF_INET` or
+     :const:`~socket.AF_INET6` to force the socket to use IPv4 or IPv6.
      If not set, the *family* will be determined from host name
-     (defaults to :data:`~socket.AF_UNSPEC`).
+     (defaults to :const:`~socket.AF_UNSPEC`).
 
    * *flags* is a bitmask for :meth:`getaddrinfo`.
 
@@ -756,7 +756,7 @@ Creating network servers
    .. versionchanged:: 3.6
 
       Added *ssl_handshake_timeout* and *start_serving* parameters.
-      The socket option :py:data:`~socket.TCP_NODELAY` is set by default
+      The socket option :py:const:`~socket.TCP_NODELAY` is set by default
       for all TCP connections.
 
    .. versionchanged:: 3.11
@@ -777,7 +777,7 @@ Creating network servers
                           start_serving=True)
 
    Similar to :meth:`loop.create_server` but works with the
-   :py:data:`~socket.AF_UNIX` socket family.
+   :py:const:`~socket.AF_UNIX` socket family.
 
    *path* is the name of a Unix domain socket, and is required,
    unless a *sock* argument is provided.  Abstract Unix sockets,

Doc/library/asyncio-platforms.rst

@@ -37,7 +37,7 @@ All event loops on Windows do not support the following methods:
 
 * :meth:`loop.create_unix_connection` and
   :meth:`loop.create_unix_server` are not supported.
-  The :data:`socket.AF_UNIX` socket family is specific to Unix.
+  The :const:`socket.AF_UNIX` socket family is specific to Unix.
 
 * :meth:`loop.add_signal_handler` and
   :meth:`loop.remove_signal_handler` are not supported.

Doc/library/asyncio-subprocess.rst

@@ -68,7 +68,7 @@ Creating Subprocesses
 
    The *limit* argument sets the buffer limit for :class:`StreamReader`
    wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
-   (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
+   (if :const:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
 
    Return a :class:`~asyncio.subprocess.Process` instance.
 
@@ -86,7 +86,7 @@ Creating Subprocesses
 
    The *limit* argument sets the buffer limit for :class:`StreamReader`
    wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
-   (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
+   (if :const:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
 
    Return a :class:`~asyncio.subprocess.Process` instance.
 
@@ -249,7 +249,7 @@ their completion.
 
       Stop the child process.
 
-      On POSIX systems this method sends :py:data:`signal.SIGTERM` to the
+      On POSIX systems this method sends :py:const:`signal.SIGTERM` to the
       child process.
 
       On Windows the Win32 API function :c:func:`TerminateProcess` is

Doc/library/compileall.rst

@@ -141,9 +141,9 @@ There is no command-line option to control the optimization level used by the
 :func:`compile` function, because the Python interpreter itself already
 provides the option: :program:`python -O -m compileall`.
 
-Similarly, the :func:`compile` function respects the :attr:`sys.pycache_prefix`
+Similarly, the :func:`compile` function respects the :data:`sys.pycache_prefix`
 setting. The generated bytecode cache will only be useful if :func:`compile` is
-run with the same :attr:`sys.pycache_prefix` (if any) that will be used at
+run with the same :data:`sys.pycache_prefix` (if any) that will be used at
 runtime.
 
 Public functions

Doc/library/devmode.rst

@@ -81,7 +81,7 @@ Effects of the Python Development Mode:
   ignored for empty strings.
 
 * The :class:`io.IOBase` destructor logs ``close()`` exceptions.
-* Set the :attr:`~sys.flags.dev_mode` attribute of :attr:`sys.flags` to
+* Set the :attr:`~sys.flags.dev_mode` attribute of :data:`sys.flags` to
   ``True``.
 
 The Python Development Mode does not enable the :mod:`tracemalloc` module by