8000 [3.11] gh-106892: Use roles :data: and :const: for referencing module… · python/cpython@cc76113 · GitHub
[go: up one dir, main page]
Skip to content

Commit cc76113

Browse files
serhiy-storchakaserhiy-storchaka
authored
[3.11] gh-106892: Use roles :data: and :const: for referencing module variables (GH-106894) (GH-106955)
(cherry picked from commit d036db7)
1 parent 6bde1b9 commit cc76113

38 files changed

+109
-109
lines changed

‎Doc/c-api/import.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -126,9 +126,9 @@ Importing Modules
126126
read from a Python bytecode file or obtained from the built-in function
127127
:func:`compile`, load the module. Return a new reference to the module object,
128128
or ``NULL`` with an exception set if an error occurred. *name*
129-
is removed from :attr:`sys.modules` in error cases, even if *name* was already
130-
in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving
131-
incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
129+
is removed from :data:`sys.modules` in error cases, even if *name* was already
130+
in :data:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving
131+
incompletely initialized modules in :data:`sys.modules` is dangerous, as imports of
132132
such modules have no way to know that the module object is an unknown (and
133133
probably damaged with respect to the module author's intents) state.
134134

‎Doc/library/__main__.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -336,12 +336,12 @@ Note that importing ``__main__`` doesn't cause any issues with unintentionally
336336
running top-level code meant for script use which is put in the
337337
``if __name__ == "__main__"`` block of the ``start`` module. Why does this work?
338338

339-
Python inserts an empty ``__main__`` module in :attr:`sys.modules` at
339+
Python inserts an empty ``__main__`` module in :data:`sys.modules` at
340340
interpreter startup, and populates it by running top-level code. In our example
341341
this is the ``start`` module which runs line by line and imports ``namely``.
342342
In turn, ``namely`` imports ``__main__`` (which is really ``start``). That's an
343343
import cycle! Fortunately, since the partially populated ``__main__``
344-
module is present in :attr:`sys.modules`, Python passes that to ``namely``.
344+
module is present in :data:`sys.modules`, Python passes that to ``namely``.
345345
See :ref:`Special considerations for __main__ <import-dunder-main>` in the
346346
import system's reference for details on how this works.
347347

‎Doc/library/asyncio-subprocess.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ Creating Subprocesses
6868

6969
The *limit* argument sets the buffer limit for :class:`StreamReader`
7070
wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
71-
(if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
71+
(if :const:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
7272

7373
Return a :class:`~asyncio.subprocess.Process` instance.
7474

@@ -86,7 +86,7 @@ Creating Subprocesses
8686

8787
The *limit* argument sets the buffer limit for :class:`StreamReader`
8888
wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
89-
(if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
89+
(if :const:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
9090

9191
Return a :class:`~asyncio.subprocess.Process` instance.
9292

‎Doc/library/compileall.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -141,9 +141,9 @@ There is no command-line option to control the optimization level used by the
141141
:func:`compile` function, because the Python interpreter itself already
142142
provides the option: :program:`python -O -m compileall`.
143143

144-
Similarly, the :func:`compile` function respects the :attr:`sys.pycache_prefix`
144+
Similarly, the :func:`compile` function respects the :data:`sys.pycache_prefix`
145145
setting. The generated bytecode cache will only be useful if :func:`compile` is
146-
run with the same :attr:`sys.pycache_prefix` (if any) that will be used at
146+
run with the same :data:`sys.pycache_prefix` (if any) that will be used at
147147
runtime.
148148

149149
Public functions

‎Doc/library/devmode.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ Effects of the Python Development Mode:
8181
ignored for empty strings.
8282

8383
* The :class:`io.IOBase` destructor logs ``close()`` exceptions.
84-
* Set the :attr:`~sys.flags.dev_mode` attribute of :attr:`sys.flags` to
84+
* Set the :attr:`~sys.flags.dev_mode` attribute of :data:`sys.flags` to
8585
``True``.
8686

8787
The Python Development Mode does not enable the :mod:`tracemalloc` module by

‎Doc/library/filecmp.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ The :class:`dircmp` class
7474

7575
Construct a new directory comparison object, to compare the directories *a*
7676
and *b*. *ignore* is a list of names to ignore, and defaults to
77-
:attr:`filecmp.DEFAULT_IGNORES`. *hide* is a list of names to hide, and
77+
:const:`filecmp.DEFAULT_IGNORES`. *hide* is a list of names to hide, and
7878
defaults to ``[os.curdir, os.pardir]``.
7979

8080
The :class:`dircmp` class compares files by doing *shallow* comparisons

‎Doc/library/ftplib.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -438,7 +438,7 @@ FTP_TLS Objects
438438

439439
.. attribute:: FTP_TLS.ssl_version
440440

441-
The SSL version to use (defaults to :attr:`ssl.PROTOCOL_SSLv23`).
441+
The SSL version to use (defaults to :data:`ssl.PROTOCOL_SSLv23`).
442442

443443
.. method:: FTP_TLS.auth()
444444

‎Doc/library/functions.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1230,7 +1230,7 @@ are always available. They are listed here in alphabetical order.
12301230

12311231
* Binary files are buffered in fixed-size chunks; the size of the buffer is
12321232
chosen using a heuristic trying to determine the underlying device's "block
1233-
size" and falling back on :attr:`io.DEFAULT_BUFFER_SIZE`. On many systems,
1233+
size" and falling back on :const:`io.DEFAULT_BUFFER_SIZE`. On many systems,
12341234
the buffer will typically be 4096 or 8192 bytes long.
12351235

12361236
* "Interactive" text files (files for which :meth:`~io.IOBase.isatty`

‎Doc/library/gc.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -260,7 +260,7 @@ values but should not rebind them):
260260

261261
.. versionchanged:: 3.4
262262
Following :pep:`442`, objects with a :meth:`__del__` method don't end
263-
up in :attr:`gc.garbage` anymore.
263+
up in :data:`gc.garbage` anymore.
264264

265265
.. data:: callbacks
266266

‎Doc/library/gzip.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -264,7 +264,7 @@ Command line options
264264

265265
.. cmdoption:: file
266266

267-
If *file* is not specified, read from :attr:`sys.stdin`.
267+
If *file* is not specified, read from :data:`sys.stdin`.
268268

269269
.. cmdoption:: --fast
270270

‎Doc/library/importlib.resources.abc.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@
124124
suitable for reading (same as :attr:`pathlib.Path.open`).
125125

126126
When opening as text, accepts encoding parameters such as those
127-
accepted by :attr:`io.TextIOWrapper`.
127+
accepted by :class:`io.TextIOWrapper`.
128128

129129
.. method:: read_bytes()
130130

‎Doc/library/importlib.rst

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -466,7 +466,7 @@ ABC hierarchy::
466466
The list of locations where the package's submodules will be found.
467467
Most of the time this is a single directory.
468468
The import system passes this attribute to ``__import__()`` and to finders
469-
in the same way as :attr:`sys.path` but just for the package.
469+
in the same way as :data:`sys.path` but just for the package.
470470
It is not set on non-package modules so it can be used
471471
as an indicator that the module is a package.
472472

@@ -717,7 +717,7 @@ ABC hierarchy::
717717
automatically.
718718

719719
When writing to the path fails because the path is read-only
720-
(:attr:`errno.EACCES`/:exc:`PermissionError`), do not propagate the
720+
(:const:`errno.EACCES`/:exc:`PermissionError`), do not propagate the
721721
exception.
722722

723723
.. versionchanged:: 3.4
@@ -965,7 +965,7 @@ find and load modules.
965965

966966
.. classmethod:: path_hook(*loader_details)
967967

968-
A class method which returns a closure for use on :attr:`sys.path_hooks`.
968+
A class method which returns a closure for use on :data:`sys.path_hooks`.
969969
An instance of :class:`FileFinder` is returned by the closure using the
970970
path argument given to the closure directly and *loader_details*
971971
indirectly.
@@ -1306,10 +1306,10 @@ an :term:`importer`.
13061306
.. function:: find_spec(name, package=None)
13071307

13081308
Find the :term:`spec <module spec>` for a module, optionally relative to
1309-
the specified **package** name. If the module is in :attr:`sys.modules`,
1309+
the specified **package** name. If the module is in :data:`sys.modules`,
13101310
then ``sys.modules[name].__spec__`` is returned (unless the spec would be
13111311
``None`` or is not set, in which case :exc:`ValueError` is raised).
1312-
Otherwise a search using :attr:`sys.meta_path` is done. ``None`` is
1312+
Otherwise a search using :data:`sys.meta_path` is done. ``None`` is
13131313
returned if no spec is found.
13141314

13151315
If **name** is for a submodule (contains a dot), the parent module is
@@ -1442,7 +1442,7 @@ an :term:`importer`.
14421442
:meth:`~importlib.abc.Loader.create_module` method must return ``None`` or a
14431443
type for which its ``__class__`` attribute can be mutated along with not
14441444
using :term:`slots <__slots__>`. Finally, modules which substitute the object
1445-
placed into :attr:`sys.modules` will not work as there is no way to properly
1445+
placed into :data:`sys.modules` will not work as there is no way to properly
14461446
replace the module references throughout the interpreter safely;
14471447
:exc:`ValueError` is raised if such a substitution is detected.
14481448

@@ -1566,9 +1566,9 @@ For deep customizations of import, you typically want to implement an
15661566
:term:`importer`. This means managing both the :term:`finder` and :term:`loader`
15671567
side of things. For finders there are two flavours to choose from depending on
15681568
your needs: a :term:`meta path finder` or a :term:`path entry finder`. The
1569-
former is what you would put on :attr:`sys.meta_path` while the latter is what
1570-
you create using a :term:`path entry hook` on :attr:`sys.path_hooks` which works
1571-
with :attr:`sys.path` entries to potentially create a finder. This example will
1569+
former is what you would put on :data:`sys.meta_path` while the latter is what
1570+
you create using a :term:`path entry hook` on :data:`sys.path_hooks` which works
1571+
with :data:`sys.path` entries to potentially create a finder. This example will
15721572
show you how to register your own importers so that import will use them (for
15731573
creating an importer for yourself, read the documentation for the appropriate
15741574
classes defined within this package)::

‎Doc/library/json.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -683,7 +683,7 @@ The :mod:`json.tool` module provides a simple command line interface to validate
683683
and pretty-print JSON objects.
684684

685685
If the optional ``infile`` and ``outfile`` arguments are not
686-
specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively:
686+
specified, :data:`sys.stdin` and :data:`sys.stdout` will be used respectively:
687687

688688
.. code-block:: shell-session
689689
@@ -721,12 +721,12 @@ Command line options
721721
}
722722
]
723723
724-
If *infile* is not specified, read from :attr:`sys.stdin`.
724+
If *infile* is not specified, read from :data:`sys.stdin`.
725725

726726
.. cmdoption:: outfile
727727

728728
Write the output of the *infile* to the given *outfile*. Otherwise, write it
729-
to :attr:`sys.stdout`.
729+
to :data:`sys.stdout`.
730730

731731
.. cmdoption:: --sort-keys
732732

‎Doc/library/logging.handlers.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1051,8 +1051,8 @@ possible, while any potentially slow operations (such as sending an email via
10511051
occur (e.g. because a bounded queue has filled up), the
10521052
:meth:`~logging.Handler.handleError` method is called to handle the
10531053
error. This can result in the record silently being dropped (if
1054-
:attr:`logging.raiseExceptions` is ``False``) or a message printed to
1055-
``sys.stderr`` (if :attr:`logging.raiseExceptions` is ``True``).
1054+
:data:`logging.raiseExceptions` is ``False``) or a message printed to
1055+
``sys.stderr`` (if :data:`logging.raiseExceptions` is ``True``).
10561056

10571057
.. method:: prepare(record)
10581058

‎Doc/library/os.path.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -383,7 +383,7 @@ the :mod:`glob` module.)
383383
*start*. On Windows, :exc:`ValueError` is raised when *path* and *start*
384384
are on different drives.
385385

386-
*start* defaults to :attr:`os.curdir`.
386+
*start* defaults to :data:`os.curdir`.
387387

388388
.. availability:: Unix, Windows.
389389

‎Doc/library/os.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ Notes on the availability of these functions:
6060
``'java'``.
6161

6262
.. seealso::
63-
:attr:`sys.platform` has a finer granularity. :func:`os.uname` gives
63+
:data:`sys.platform` has a finer granularity. :func:`os.uname` gives
6464
system-dependent version information.
6565

6666
The :mod:`platform` module provides detailed checks for the

‎Doc/library/platform.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Cross Platform
4646
universal files containing multiple architectures.
4747

4848
To get at the "64-bitness" of the current interpreter, it is more
49-
reliable to query the :attr:`sys.maxsize` attribute::
49+
reliable to query the :data:`sys.maxsize` attribute::
5050

5151
is_64bits = sys.maxsize > 2**32
5252

‎Doc/library/shutil.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -425,7 +425,7 @@ Directory and files operations
425425
determining if the file exists and executable.
426426

427427
When no *path* is specified, the results of :func:`os.environ` are used,
428-
returning either the "PATH" value or a fallback of :attr:`os.defpath`.
428+
returning either the "PATH" value or a fallback of :data:`os.defpath`.
429429

430430
On Windows, the current directory is always prepended to the *path* whether
431431
or not you use the default or provide your own, which is the behavior the

‎Doc/library/stdtypes.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5591,7 +5591,7 @@ From code, you can inspect the current limit and set a new one using these
55915591
a getter and setter for the interpreter-wide limit. Subinterpreters have
55925592
their own limit.
55935593

5594-
Information about the default and minimum can be found in :attr:`sys.int_info`:
5594+
Information about the default and minimum can be found in :data:`sys.int_info`:
55955595

55965596
* :data:`sys.int_info.default_max_str_digits <sys.int_info>` is the compiled-in
55975597
default limit.

‎Doc/library/subprocess.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1609,15 +1609,15 @@ improves performance.
16091609

16101610
If you ever encounter a presumed highly unusual situation where you need to
16111611
prevent ``vfork()`` from being used by Python, you can set the
1612-
:attr:`subprocess._USE_VFORK` attribute to a false value.
1612+
:const:`subprocess._USE_VFORK` attribute to a false value.
16131613

16141614
::
16151615

16161616
subprocess._USE_VFORK = False # See CPython issue gh-NNNNNN.
16171617

16181618
Setting this has no impact on use of ``posix_spawn()`` which could use
16191619
``vfork()`` internally within its libc implementation. There is a similar
1620-
:attr:`subprocess._USE_POSIX_SPAWN` attribute if you need to prevent use of
1620+
:const:`subprocess._USE_POSIX_SPAWN` attribute if you need to prevent use of
16211621
that.
16221622

16231623
::

‎Doc/library/sys.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ always available.
166166
Python interpreter. (This information is not available in any other way ---
167167
``modules.keys()`` only lists the imported modules.)
168168

169-
See also the :attr:`sys.stdlib_module_names` list.
169+
See also the :data:`sys.stdlib_module_names` list.
170170

171171

172172
.. function:: call_tracing(func, args)
@@ -1261,20 +1261,20 @@ always available.
12611261
================ ===========================
12621262

12631263
.. versionchanged:: 3.3
1264-
On Linux, :attr:`sys.platform` doesn't contain the major version anymore.
1264+
On Linux, :data:`sys.platform` doesn't contain the major version anymore.
12651265
It is always ``'linux'``, instead of ``'linux2'`` or ``'linux3'``. Since
12661266
older Python versions include the version number, it is recommended to
12671267
always use the ``startswith`` idiom presented above.
12681268

12691269
.. versionchanged:: 3.8
1270-
On AIX, :attr:`sys.platform` doesn't contain the major version anymore.
1270+
On AIX, :data:`sys.platform` doesn't contain the major version anymore.
12711271
It is always ``'aix'``, instead of ``'aix5'`` or ``'aix7'``. Since
12721272
older Python versions include the version number, it is recommended to
12731273
always use the ``startswith`` idiom presented above.
12741274

12751275
.. seealso::
12761276

1277-
:attr:`os.name` has a coarser granularity. :func:`os.uname` gives
1277+
:data:`os.name` has a coarser granularity. :func:`os.uname` gives
12781278
system-dependent version information.
12791279

12801280
The :mod:`platform` module provides detailed checks for the
@@ -1685,7 +1685,7 @@ always available.
16851685
``email.mime`` sub-package and the ``email.message`` sub-module are not
16861686
listed.
16871687

1688-
See also the :attr:`sys.builtin_module_names` list.
1688+
See also the :data:`sys.builtin_module_names` list.
16891689

16901690
.. versionadded:: 3.10
16911691

‎Doc/library/tarfile.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -931,7 +931,7 @@ reused in custom filters:
931931

932932
Implements the ``'tar'`` filter.
933933

934-
- Strip leading slashes (``/`` and :attr:`os.sep`) from filenames.
934+
- Strip leading slashes (``/`` and :data:`os.sep`) from filenames.
935935
- :ref:`Refuse <tarfile-extraction-refuse>` to extract files with absolute
936936
paths (in case the name is absolute
937937
even after stripping slashes, e.g. ``C:/foo`` on Windows).
@@ -940,7 +940,7 @@ reused in custom filters:
940940
path (after following symlinks) would end up outside the destination.
941941
This raises :class:`~tarfile.OutsideDestinationError`.
942942
- Clear high mode bits (setuid, setgid, sticky) and group/other write bits
943-
(:attr:`~stat.S_IWGRP`|:attr:`~stat.S_IWOTH`).
943+
(:const:`~stat.S_IWGRP`|:const:`~stat.S_IWOTH`).
944944

945945
Return the modified ``TarInfo`` member.
946946

@@ -965,10 +965,10 @@ reused in custom filters:
965965
- For regular files, including hard links:
966966

967967
- Set the owner read and write permissions
968-
(:attr:`~stat.S_IRUSR`|:attr:`~stat.S_IWUSR`).
968+
(:const:`~stat.S_IRUSR`|:const:`~stat.S_IWUSR`).
969969
- Remove the group & other executable permission
970-
(:attr:`~stat.S_IXGRP`|:attr:`~stat.S_IXOTH`)
971-
if the owner doesn’t have it (:attr:`~stat.S_IXUSR`).
970+
(:const:`~stat.S_IXGRP`|:const:`~stat.S_IXOTH`)
971+
if the owner doesn’t have it (:const:`~stat.S_IXUSR`).
972972

973973
- For other files (directories), set ``mode`` to ``None``, so
974974
that extraction methods skip applying permission bits.

‎Doc/library/test.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -973,7 +973,7 @@ The :mod:`test.support` module defines the following classes:
973973
`SetErrorMode <https://msdn.microsoft.com/en-us/library/windows/desktop/ms680621.aspx>`_.
974974

975975
On UNIX, :func:`resource.setrlimit` is used to set
976-
:attr:`resource.RLIMIT_CORE`'s soft limit to 0 to prevent coredump file
976+
:const:`resource.RLIMIT_CORE`'s soft limit to 0 to prevent coredump file
977977
creation.
978978

979979
On both platforms, the old value is restored by :meth:`__exit__`.

‎Doc/library/tkinter.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,7 @@ the modern themed widget set and API::
163163
interpreter and calls :func:`exec` on the contents of
164164
:file:`.{className}.py` and :file:`.{baseName}.py`. The path for the
165165
profile files is the :envvar:`HOME` environment variable or, if that
166-
isn't defined, then :attr:`os.curdir`.
166+
isn't defined, then :data:`os.curdir`.
167167

168168
.. attribute:: tk
169169

‎Doc/library/unittest.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1128,7 +1128,7 @@ Test cases
11281128

11291129
If given, *level* should be either a numeric logging level or
11301130
its string equivalent (for example either ``"ERROR"`` or
1131-
:attr:`logging.ERROR`). The default is :attr:`logging.INFO`.
1131+
:const:`logging.ERROR`). The default is :const:`logging.INFO`.
11321132

11331133
The test passes if at least one message emitted inside the ``with``
11341134
block matches the *logger* and *level* conditions, otherwise it fails.
@@ -1169,7 +1169,7 @@ Test cases
11691169

11701170
If given, *level* should be either a numeric logging level or
11711171
its string equivalent (for example either ``"ERROR"`` or
1172-
:attr:`logging.ERROR`). The default is :attr:`logging.INFO`.
1172+
:const:`logging.ERROR`). The default is :const:`logging.INFO`.
11731173

11741174
Unlike :meth:`assertLogs`, nothing will be returned by the context
11751175
manager.

0 commit comments

Comments
 (0)
0