[3.12] gh-106892: Use roles :data: and :const: for referencing module variables (GH-106894) (GH-106954)

(cherry picked from commit d036db7)

Author: serhiy-storchaka

Doc/c-api/import.rst

@@ -126,9 +126,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/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/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.
 

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

Doc/library/filecmp.rst

@@ -74,7 +74,7 @@ The :class:`dircmp` class
 
    Construct a new directory comparison object, to compare the directories *a*
    and *b*.  *ignore* is a list of names to ignore, and defaults to
-   :attr:`filecmp.DEFAULT_IGNORES`.  *hide* is a list of names to hide, and
+   :const:`filecmp.DEFAULT_IGNORES`.  *hide* is a list of names to hide, and
    defaults to ``[os.curdir, os.pardir]``.
 
    The :class:`dircmp` class compares files by doing *shallow* comparisons

Doc/library/ftplib.rst

@@ -431,7 +431,7 @@ FTP_TLS Objects
 
 .. attribute:: FTP_TLS.ssl_version
 
-   The SSL version to use (defaults to :attr:`ssl.PROTOCOL_SSLv23`).
+   The SSL version to use (defaults to :data:`ssl.PROTOCOL_SSLv23`).
 
 .. method:: FTP_TLS.auth()
 

Doc/library/functions.rst

@@ -1231,7 +1231,7 @@ are always available.  They are listed here in alphabetical order.
 
    * Binary files are buffered in fixed-size chunks; the size of the buffer is
      chosen using a heuristic trying to determine the underlying device's "block
-     size" and falling back on :attr:`io.DEFAULT_BUFFER_SIZE`.  On many systems,
+     size" and falling back on :const:`io.DEFAULT_BUFFER_SIZE`.  On many systems,
      the buffer will typically be 4096 or 8192 bytes long.
 
    * "Interactive" text files (files for which :meth:`~io.IOBase.isatty`

Doc/library/gc.rst

@@ -260,7 +260,7 @@ values but should not rebind them):
 
    .. versionchanged:: 3.4
       Following :pep:`442`, objects with a :meth:`~object.__del__` method don't end
-      up in :attr:`gc.garbage` anymore.
+      up in :data:`gc.garbage` anymore.
 
 .. data:: callbacks
 

Doc/library/gzip.rst

@@ -268,7 +268,7 @@ Command line options
 
 .. cmdoption:: file
 
-   If *file* is not specified, read from :attr:`sys.stdin`.
+   If *file* is not specified, read from :data:`sys.stdin`.
 
 .. cmdoption:: --fast
 

Doc/library/importlib.resources.abc.rst

@@ -130,7 +130,7 @@
        suitable for reading (same as :attr:`pathlib.Path.open`).
 
        When opening as text, accepts encoding parameters such as those
-       accepted by :attr:`io.TextIOWrapper`.
+       accepted by :class:`io.TextIOWrapper`.
 
     .. method:: read_bytes()
 

Doc/library/importlib.rst

@@ -372,7 +372,7 @@ ABC hierarchy::
             The list of locations where the package's submodules will be found.
             Most of the time this is a single directory.
             The import system passes this attribute to ``__import__()`` and to finders
-            in the same way as :attr:`sys.path` but just for the package.
+            in the same way as :data:`sys.path` but just for the package.
             It is not set on non-package modules so it can be used
             as an indicator that the module is a package.
 
@@ -609,7 +609,7 @@ ABC hierarchy::
         automatically.
 
         When writing to the path fails because the path is read-only
-        (:attr:`errno.EACCES`/:exc:`PermissionError`), do not propagate the
+        (:const:`errno.EACCES`/:exc:`PermissionError`), do not propagate the
         exception.
 
         .. versionchanged:: 3.4
@@ -843,7 +843,7 @@ find and load modules.
 
    .. classmethod:: path_hook(*loader_details)
 
-      A class method which returns a closure for use on :attr:`sys.path_hooks`.
+      A class method which returns a closure for use on :data:`sys.path_hooks`.
       An instance of :class:`FileFinder` is returned by the closure using the
       path argument given to the closure directly and *loader_details*
       indirectly.
@@ -1184,10 +1184,10 @@ an :term:`importer`.
 .. function:: find_spec(name, package=None)
 
    Find the :term:`spec <module spec>` for a module, optionally relative to
-   the specified **package** name. If the module is in :attr:`sys.modules`,
+   the specified **package** name. If the module is in :data:`sys.modules`,
    then ``sys.modules[name].__spec__`` is returned (unless the spec would be
    ``None`` or is not set, in which case :exc:`ValueError` is raised).
-   Otherwise a search using :attr:`sys.meta_path` is done. ``None`` is
+   Otherwise a search using :data:`sys.meta_path` is done. ``None`` is
    returned if no spec is found.
 
    If **name** is for a submodule (contains a dot), the parent module is
@@ -1259,7 +1259,7 @@ an :term:`importer`.
    :meth:`~importlib.abc.Loader.create_module` method must return ``None`` or a
    type for which its ``__class__`` attribute can be mutated along with not
    using :term:`slots <__slots__>`. Finally, modules which substitute the object
-   placed into :attr:`sys.modules` will not work as there is no way to properly
+   placed into :data:`sys.modules` will not work as there is no way to properly
    replace the module references throughout the interpreter safely;
    :exc:`ValueError` is raised if such a substitution is detected.
 
@@ -1383,9 +1383,9 @@ For deep customizations of import, you typically want to implement an
 :term:`importer`. This means managing both the :term:`finder` and :term:`loader`
 side of things. For finders there are two flavours to choose from depending on
 your needs: a :term:`meta path finder` or a :term:`path entry finder`. The
-former is what you would put on :attr:`sys.meta_path` while the latter is what
-you create using a :term:`path entry hook` on :attr:`sys.path_hooks` which works
-with :attr:`sys.path` entries to potentially create a finder. This example will
+former is what you would put on :data:`sys.meta_path` while the latter is what
+you create using a :term:`path entry hook` on :data:`sys.path_hooks` which works
+with :data:`sys.path` entries to potentially create a finder. This example will
 show you how to register your own importers so that import will use them (for
 creating an importer for yourself, read the documentation for the appropriate
 classes defined within this package)::

Doc/library/json.rst

@@ -683,7 +683,7 @@ The :mod:`json.tool` module provides a simple command line interface to validate
 and pretty-print JSON objects.
 
 If the optional ``infile`` and ``outfile`` arguments are not
-specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively:
+specified, :data:`sys.stdin` and :data:`sys.stdout` will be used respectively:
 
 .. code-block:: shell-session
 
@@ -721,12 +721,12 @@ Command line options
           }
       ]
 
-   If *infile* is not specified, read from :attr:`sys.stdin`.
+   If *infile* is not specified, read from :data:`sys.stdin`.
 
 .. cmdoption:: outfile
 
    Write the output of the *infile* to the given *outfile*. Otherwise, write it
-   to :attr:`sys.stdout`.
+   to :data:`sys.stdout`.
 
 .. cmdoption:: --sort-keys
 

Doc/library/logging.handlers.rst

@@ -1051,8 +1051,8 @@ possible, while any potentially slow operations (such as sending an email via
       occur (e.g. because a bounded queue has filled up), the
       :meth:`~logging.Handler.handleError` method is called to handle the
       error. This can result in the record silently being dropped (if
-      :attr:`logging.raiseExceptions` is ``False``) or a message printed to
-      ``sys.stderr`` (if :attr:`logging.raiseExceptions` is ``True``).
+      :data:`logging.raiseExceptions` is ``False``) or a message printed to
+      ``sys.stderr`` (if :data:`logging.raiseExceptions` is ``True``).
 
    .. method:: prepare(record)
 

Doc/library/os.path.rst

@@ -410,7 +410,7 @@ the :mod:`glob` module.)
    *start*.  On Windows, :exc:`ValueError` is raised when *path* and *start*
    are on different drives.
 
-   *start* defaults to :attr:`os.curdir`.
+   *start* defaults to :data:`os.curdir`.
 
    .. availability:: Unix, Windows.
 

Doc/library/os.rst

@@ -60,7 +60,7 @@ Notes on the availability of these functions:
    ``'java'``.
 
    .. seealso::
-      :attr:`sys.platform` has a finer granularity.  :func:`os.uname` gives
+      :data:`sys.platform` has a finer granularity.  :func:`os.uname` gives
       system-dependent version information.
 
       The :mod:`platform` module provides detailed checks for the

Doc/library/platform.rst

@@ -46,7 +46,7 @@ Cross Platform
       universal files containing multiple architectures.
 
       To get at the "64-bitness" of the current interpreter, it is more
-      reliable to query the :attr:`sys.maxsize` attribute::
+      reliable to query the :data:`sys.maxsize` attribute::
 
          is_64bits = sys.maxsize > 2**32
 

Doc/library/shutil.rst

@@ -431,7 +431,7 @@ Directory and files operations
    determining if the file exists and executable.
 
    When no *path* is specified, the results of :func:`os.environ` are used,
-   returning either the "PATH" value or a fallback of :attr:`os.defpath`.
+   returning either the "PATH" value or a fallback of :data:`os.defpath`.
 
    On Windows, the current directory is prepended to the *path* if *mode* does
    not include ``os.X_OK``. When the *mode* does include ``os.X_OK``, the

Doc/library/stdtypes.rst

@@ -5629,7 +5629,7 @@ From code, you can inspect the current limit and set a new one using these
   a getter and setter for the interpreter-wide limit. Subinterpreters have
   their own limit.
 
-Information about the default and minimum can be found in :attr:`sys.int_info`:
+Information about the default and minimum can be found in :data:`sys.int_info`:
 
 * :data:`sys.int_info.default_max_str_digits <sys.int_info>` is the compiled-in
   default limit.

Doc/library/subprocess.rst

@@ -1610,15 +1610,15 @@ improves performance.
 
 If you ever encounter a presumed highly unusual situation where you need to
 prevent ``vfork()`` from being used by Python, you can set the
-:attr:`subprocess._USE_VFORK` attribute to a false value.
+:const:`subprocess._USE_VFORK` attribute to a false value.
 
 ::
 
    subprocess._USE_VFORK = False  # See CPython issue gh-NNNNNN.
 
 Setting this has no impact on use of ``posix_spawn()`` which could use
 ``vfork()`` internally within its libc implementation.  There is a similar
-:attr:`subprocess._USE_POSIX_SPAWN` attribute if you need to prevent use of
+:const:`subprocess._USE_POSIX_SPAWN` attribute if you need to prevent use of
 that.
 
 ::

Doc/library/sys.rst

@@ -166,7 +166,7 @@ always available.
    Python interpreter.  (This information is not available in any other way ---
    ``modules.keys()`` only lists the imported modules.)
 
-   See also the :attr:`sys.stdlib_module_names` list.
+   See also the :data:`sys.stdlib_module_names` list.
 
 
 .. function:: call_tracing(func, args)
@@ -1287,20 +1287,20 @@ always available.
    ================ ===========================
 
    .. versionchanged:: 3.3
-      On Linux, :attr:`sys.platform` doesn't contain the major version anymore.
+      On Linux, :data:`sys.platform` doesn't contain the major version anymore.
       It is always ``'linux'``, instead of ``'linux2'`` or ``'linux3'``.  Since
       older Python versions include the version number, it is recommended to
       always use the ``startswith`` idiom presented above.
 
    .. versionchanged:: 3.8
-      On AIX, :attr:`sys.platform` doesn't contain the major version anymore.
+      On AIX, :data:`sys.platform` doesn't contain the major version anymore.
       It is always ``'aix'``, instead of ``'aix5'`` or ``'aix7'``.  Since
       older Python versions include the version number, it is recommended to
       always use the ``startswith`` idiom presented above.
 
    .. seealso::
 
-      :attr:`os.name` has a coarser granularity.  :func:`os.uname` gives
+      :data:`os.name` has a coarser granularity.  :func:`os.uname` gives
       system-dependent version information.
 
       The :mod:`platform` module provides detailed checks for the
@@ -1743,7 +1743,7 @@ always available.
    ``email.mime`` sub-package and the ``email.message`` sub-module are not
    listed.
 
-   See also the :attr:`sys.builtin_module_names` list.
+   See also the :data:`sys.builtin_module_names` list.
 
    .. versionadded:: 3.10
 

Doc/library/tarfile.rst

@@ -933,7 +933,7 @@ reused in custom filters:
 
   Implements the ``'tar'`` filter.
 
-  - Strip leading slashes (``/`` and :attr:`os.sep`) from filenames.
+  - Strip leading slashes (``/`` and :data:`os.sep`) from filenames.
   - :ref:`Refuse <tarfile-extraction-refuse>` to extract files with absolute
     paths (in case the name is absolute
     even after stripping slashes, e.g. ``C:/foo`` on Windows).
@@ -942,7 +942,7 @@ reused in custom filters:
     path (after following symlinks) would end up outside the destination.
     This raises :class:`~tarfile.OutsideDestinationError`.
   - Clear high mode bits (setuid, setgid, sticky) and group/other write bits
-    (:attr:`~stat.S_IWGRP`|:attr:`~stat.S_IWOTH`).
+    (:const:`~stat.S_IWGRP`|:const:`~stat.S_IWOTH`).
 
   Return the modified ``TarInfo`` member.
 
@@ -967,10 +967,10 @@ reused in custom filters:
   - For regular files, including hard links:
 
     - Set the owner read and write permissions
-      (:attr:`~stat.S_IRUSR`|:attr:`~stat.S_IWUSR`).
+      (:const:`~stat.S_IRUSR`|:const:`~stat.S_IWUSR`).
     - Remove the group & other executable permission
-      (:attr:`~stat.S_IXGRP`|:attr:`~stat.S_IXOTH`)
-      if the owner doesn’t have it (:attr:`~stat.S_IXUSR`).
+      (:const:`~stat.S_IXGRP`|:const:`~stat.S_IXOTH`)
+      if the owner doesn’t have it (:const:`~stat.S_IXUSR`).
 
   - For other files (directories), set ``mode`` to ``None``, so
     that extraction methods skip applying permission bits.

Doc/library/test.rst

@@ -1040,7 +1040,7 @@ The :mod:`test.support` module defines the following classes:
    `SetErrorMode <https://msdn.microsoft.com/en-us/library/windows/desktop/ms680621.aspx>`_.
 
    On UNIX, :func:`resource.setrlimit` is used to set
-   :attr:`resource.RLIMIT_CORE`'s soft limit to 0 to prevent coredump file
+   :const:`resource.RLIMIT_CORE`'s soft limit to 0 to prevent coredump file
    creation.
 
    On both platforms, the old value is restored by :meth:`__exit__`.

Doc/library/tkinter.rst

@@ -163,7 +163,7 @@ the modern themed widget set and API::
    interpreter and calls :func:`exec` on the contents of
    :file:`.{className}.py` and :file:`.{baseName}.py`.  The path for the
    profile files is the :envvar:`HOME` environment variable or, if that
-   isn't defined, then :attr:`os.curdir`.
+   isn't defined, then :data:`os.curdir`.
 
    .. attribute:: tk
 

Doc/library/unittest.rst

@@ -1134,7 +1134,7 @@ Test cases
 
       If given, *level* should be either a numeric logging level or
       its string equivalent (for example either ``"ERROR"`` or
-      :attr:`logging.ERROR`).  The default is :attr:`logging.INFO`.
+      :const:`logging.ERROR`).  The default is :const:`logging.INFO`.
 
       The test passes if at least one message emitted inside the ``with``
       block matches the *logger* and *level* conditions, otherwise it fails.
@@ -1175,7 +1175,7 @@ Test cases
 
       If given, *level* should be either a numeric logging level or
       its string equivalent (for example either ``"ERROR"`` or
-      :attr:`logging.ERROR`).  The default is :attr:`logging.INFO`.
+      :const:`logging.ERROR`).  The default is :const:`logging.INFO`.
 
       Unlike :meth:`assertLogs`, nothing will be returned by the context
       manager.