Skip to content

Docs: module pages should not link to themselves #144505

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nedbat merged 2 commits into from
Feb 6, 2026
+688 −688
Merged

Docs: module pages should not link to themselves #144505

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f22bd48
Docs: module pages should not link to themselves
nedbat Feb 5, 2026
e393c1f
fix header punctuation
nedbat Feb 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions Doc/library/__future__.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,25 +15,25 @@ before the release in which the feature becomes standard.

While these future statements are given additional special meaning by the
Python compiler, they are still executed like any other import statement and
the :mod:`__future__` exists and is handled by the import system the same way
the :mod:`!__future__` exists and is handled by the import system the same way
any other Python module would be. This design serves three purposes:

* To avoid confusing existing tools that analyze import statements and expect to
find the modules they're importing.

* To document when incompatible changes were introduced, and when they will be
--- or were --- made mandatory. This is a form of executable documentation, and
can be inspected programmatically via importing :mod:`__future__` and examining
can be inspected programmatically via importing :mod:`!__future__` and examining
its contents.

* To ensure that :ref:`future statements <future>` run under releases prior to
Python 2.1 at least yield runtime exceptions (the import of :mod:`__future__`
Python 2.1 at least yield runtime exceptions (the import of :mod:`!__future__`
will fail, because there was no module of that name prior to 2.1).

Module Contents
---------------

No feature description will ever be deleted from :mod:`__future__`. Since its
No feature description will ever be deleted from :mod:`!__future__`. Since its
introduction in Python 2.1 the following features have found their way into the
language using this mechanism:

Expand Down
2 changes: 1 addition & 1 deletion Doc/library/argparse.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

.. note::

While :mod:`argparse` is the default recommended standard library module
While :mod:`!argparse` is the default recommended standard library module
for implementing basic command line applications, authors with more
exacting requirements for exactly how their command line applications
behave may find it doesn't provide the necessary level of control.
Expand Down
12 changes: 6 additions & 6 deletions Doc/library/ast.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

--------------

The :mod:`ast` module helps Python applications to process trees of the Python
The :mod:`!ast` module helps Python applications to process trees of the Python
abstract syntax grammar. The abstract syntax itself might change with each
Python release; this module helps to find out programmatically what the current
grammar looks like.
Expand Down Expand Up @@ -46,7 +46,7 @@ Node classes
This is the base of all AST node classes. The actual node classes are
derived from the :file:`Parser/Python.asdl` file, which is reproduced
:ref:`above <abstract-grammar>`. They are defined in the :mod:`!_ast` C
module and re-exported in :mod:`ast`.
module and re-exported in :mod:`!ast`.

There is one class defined for each left-hand side symbol in the abstract
grammar (for example, :class:`ast.stmt` or :class:`ast.expr`). In addition,
Expand Down Expand Up @@ -2200,10 +2200,10 @@ Async and await
occurrences of the same value (for example, :class:`ast.Add`).


:mod:`ast` helpers
------------------
:mod:`!ast` helpers
-------------------

Apart from the node classes, the :mod:`ast` module defines these utility functions
Apart from the node classes, the :mod:`!ast` module defines these utility functions
and classes for traversing abstract syntax trees:

.. function:: parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None, optimize=-1, module=None)
Expand Down Expand Up @@ -2576,7 +2576,7 @@ Command-line usage

.. versionadded:: 3.9

The :mod:`ast` module can be executed as a script from the command line.
The :mod:`!ast` module can be executed as a script from the command line.
It is as simple as:

.. code-block:: sh
Expand Down
12 changes: 6 additions & 6 deletions Doc/library/atexit.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@

--------------

The :mod:`atexit` module defines functions to register and unregister cleanup
The :mod:`!atexit` module defines functions to register and unregister cleanup
functions. Functions thus registered are automatically executed upon normal
interpreter termination. :mod:`atexit` runs these functions in the *reverse*
interpreter termination. :mod:`!atexit` runs these functions in the *reverse*
order in which they were registered; if you register ``A``, ``B``, and ``C``,
at interpreter termination time they will be run in the order ``C``, ``B``,
``A``.
Expand Down Expand Up @@ -64,22 +64,22 @@ a cleanup function is undefined.
Remove *func* from the list of functions to be run at interpreter shutdown.
:func:`unregister` silently does nothing if *func* was not previously
registered. If *func* has been registered more than once, every occurrence
of that function in the :mod:`atexit` call stack will be removed. Equality
of that function in the :mod:`!atexit` call stack will be removed. Equality
comparisons (``==``) are used internally during unregistration, so function
references do not need to have matching identities.


.. seealso::

Module :mod:`readline`
Useful example of :mod:`atexit` to read and write :mod:`readline` history
Useful example of :mod:`!atexit` to read and write :mod:`readline` history
files.


.. _atexit-example:

:mod:`atexit` Example
---------------------
:mod:`!atexit` Example
----------------------

The following simple example demonstrates how a module can initialize a counter
from a file when it is imported and save the counter's updated value
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/bdb.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

--------------

The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
The :mod:`!bdb` module handles basic debugger functions, like setting breakpoints
or managing execution via the debugger.

The following exception is defined:
Expand All @@ -18,7 +18,7 @@ The following exception is defined:
Exception raised by the :class:`Bdb` class for quitting the debugger.


The :mod:`bdb` module also defines two classes:
The :mod:`!bdb` module also defines two classes:

.. class:: Breakpoint(self, file, line, temporary=False, cond=None, funcname=None)

Expand Down
6 changes: 3 additions & 3 deletions Doc/library/binascii.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@

--------------

The :mod:`binascii` module contains a number of methods to convert between
The :mod:`!binascii` module contains a number of methods to convert between
binary and various ASCII-encoded binary representations. Normally, you will not
use these functions directly but use wrapper modules like
:mod:`base64` instead. The :mod:`binascii` module contains
:mod:`base64` instead. The :mod:`!binascii` module contains
low-level functions written in C for greater speed that are used by the
higher-level modules.

Expand All @@ -28,7 +28,7 @@ higher-level modules.
ASCII-only unicode strings are now accepted by the ``a2b_*`` functions.


The :mod:`binascii` module defines the following functions:
The :mod:`!binascii` module defines the following functions:


.. function:: a2b_uu(string)
Expand Down
6 changes: 3 additions & 3 deletions Doc/library/bisect.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ having to sort the list after each insertion. For long lists of items with
expensive comparison operations, this can be an improvement over
linear searches or frequent resorting.

The module is called :mod:`bisect` because it uses a basic bisection
The module is called :mod:`!bisect` because it uses a basic bisection
algorithm to do its work. Unlike other bisection tools that search for a
specific value, the functions in this module are designed to locate an
insertion point. Accordingly, the functions never call an :meth:`~object.__eq__`
Expand All @@ -27,9 +27,9 @@ point between values in an array.
.. note::

The functions in this module are not thread-safe. If multiple threads
concurrently use :mod:`bisect` functions on the same sequence, this
concurrently use :mod:`!bisect` functions on the same sequence, this
may result in undefined behaviour. Likewise, if the provided sequence
is mutated by a different thread while a :mod:`bisect` function
is mutated by a different thread while a :mod:`!bisect` function
is operating on it, the result is undefined. For example, using
:py:func:`~bisect.insort_left` on the same list from multiple threads
may result in the list becoming unsorted.
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/bz2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
This module provides a comprehensive interface for compressing and
decompressing data using the bzip2 compression algorithm.

The :mod:`bz2` module contains:
The :mod:`!bz2` module contains:

* The :func:`.open` function and :class:`BZ2File` class for reading and
writing compressed files.
Expand Down Expand Up @@ -317,7 +317,7 @@ One-shot (de)compression
Examples of usage
-----------------

Below are some examples of typical usage of the :mod:`bz2` module.
Below are some examples of typical usage of the :mod:`!bz2` module.

Using :func:`compress` and :func:`decompress` to demonstrate round-trip compression:

Expand Down
6 changes: 3 additions & 3 deletions Doc/library/calendar.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -452,7 +452,7 @@ For simple text calendars this module provides the following functions.
inverse.


The :mod:`calendar` module exports the following data attributes:
The :mod:`!calendar` module exports the following data attributes:

.. data:: day_name

Expand Down Expand Up @@ -578,7 +578,7 @@ The :mod:`calendar` module exports the following data attributes:
.. versionadded:: 3.12


The :mod:`calendar` module defines the following exceptions:
The :mod:`!calendar` module defines the following exceptions:

.. exception:: IllegalMonthError(month)

Expand Down Expand Up @@ -617,7 +617,7 @@ Command-line usage

.. versionadded:: 2.5

The :mod:`calendar` module can be executed as a script from the command line
The :mod:`!calendar` module can be executed as a script from the command line
to interactively print a calendar.

.. code-block:: shell
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/cmath.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ rectangular coordinates to polar coordinates and back.

The modulus (absolute value) of a complex number *z* can be
computed using the built-in :func:`abs` function. There is no
separate :mod:`cmath` module function for this operation.
separate :mod:`!cmath` module function for this operation.


.. function:: polar(z)
Expand Down Expand Up @@ -357,7 +357,7 @@ Note that the selection of functions is similar, but not identical, to that in
module :mod:`math`. The reason for having two modules is that some users aren't
interested in complex numbers, and perhaps don't even know what they are. They
would rather have ``math.sqrt(-1)`` raise an exception than return a complex
number. Also note that the functions defined in :mod:`cmath` always return a
number. Also note that the functions defined in :mod:`!cmath` always return a
complex number, even if the answer can be expressed as a real number (in which
case the complex number has an imaginary part of zero).

Expand Down
2 changes: 1 addition & 1 deletion Doc/library/cmd.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,7 @@ Cmd Example

.. sectionauthor:: Raymond Hettinger <python at rcn dot com>

The :mod:`cmd` module is mainly useful for building custom shells that let a
The :mod:`!cmd` module is mainly useful for building custom shells that let a
user work with a program interactively.

This section presents a simple example of how to build a shell around a few of
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/codecs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,7 +317,7 @@ and writing to platform dependent files:
Codec Base Classes
------------------

The :mod:`codecs` module defines a set of base classes which define the
The :mod:`!codecs` module defines a set of base classes which define the
interfaces for working with codec objects, and can also be used as the basis
for custom codec implementations.

Expand Down
4 changes: 2 additions & 2 deletions Doc/library/codeop.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

--------------

The :mod:`codeop` module provides utilities upon which the Python
The :mod:`!codeop` module provides utilities upon which the Python
read-eval-print loop can be emulated, as is done in the :mod:`code` module. As
a result, you probably don't want to use the module directly; if you want to
include such a loop in your program you probably want to use the :mod:`code`
Expand All @@ -25,7 +25,7 @@ There are two parts to this job:
#. Remembering which future statements the user has entered, so subsequent
input can be compiled with these in effect.

The :mod:`codeop` module provides a way of doing each of these things, and a way
The :mod:`!codeop` module provides a way of doing each of these things, and a way
of doing them both.

To do just the former:
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/colorsys.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

--------------

The :mod:`colorsys` module defines bidirectional conversions of color values
The :mod:`!colorsys` module defines bidirectional conversions of color values
between colors expressed in the RGB (Red Green Blue) color space used in
computer monitors and three other coordinate systems: YIQ, HLS (Hue Lightness
Saturation) and HSV (Hue Saturation Value). Coordinates in all of these color
Expand All @@ -24,7 +24,7 @@ spaces, the coordinates are all between 0 and 1.
https://poynton.ca/ColorFAQ.html and
https://www.cambridgeincolour.com/tutorials/color-spaces.htm.

The :mod:`colorsys` module defines the following functions:
The :mod:`!colorsys` module defines the following functions:


.. function:: rgb_to_yiq(r, g, b)
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/concurrent.futures.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ and :source:`Lib/concurrent/futures/interpreter.py`

--------------

The :mod:`concurrent.futures` module provides a high-level interface for
The :mod:`!concurrent.futures` module provides a high-level interface for
asynchronously executing callables.

The asynchronous execution can be performed with threads, using
Expand Down
18 changes: 9 additions & 9 deletions Doc/library/configparser.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ Let's take a very basic configuration file that looks like this:
The structure of INI files is described `in the following section
<#supported-ini-file-structure>`_. Essentially, the file
consists of sections, each of which contains keys with values.
:mod:`configparser` classes can read and write such files. Let's start by
:mod:`!configparser` classes can read and write such files. Let's start by
creating the above configuration file programmatically.

.. doctest::
Expand Down Expand Up @@ -449,7 +449,7 @@ Mapping Protocol Access
.. versionadded:: 3.2

Mapping protocol access is a generic name for functionality that enables using
custom objects as if they were dictionaries. In case of :mod:`configparser`,
custom objects as if they were dictionaries. In case of :mod:`!configparser`,
the mapping interface implementation is using the
``parser['section']['option']`` notation.

Expand All @@ -459,7 +459,7 @@ the original parser on demand. What's even more important is that when values
are changed on a section proxy, they are actually mutated in the original
parser.

:mod:`configparser` objects behave as close to actual dictionaries as possible.
:mod:`!configparser` objects behave as close to actual dictionaries as possible.
The mapping interface is complete and adheres to the
:class:`~collections.abc.MutableMapping` ABC.
However, there are a few differences that should be taken into account:
Expand Down Expand Up @@ -507,7 +507,7 @@ Customizing Parser Behaviour
----------------------------

There are nearly as many INI format variants as there are applications using it.
:mod:`configparser` goes a long way to provide support for the largest sensible
:mod:`!configparser` goes a long way to provide support for the largest sensible
set of INI styles available. The default functionality is mainly dictated by
historical background and it's very likely that you will want to customize some
of the features.
Expand Down Expand Up @@ -560,7 +560,7 @@ the :meth:`!__init__` options:
* *allow_no_value*, default value: ``False``

Some configuration files are known to include settings without values, but
which otherwise conform to the syntax supported by :mod:`configparser`. The
which otherwise conform to the syntax supported by :mod:`!configparser`. The
*allow_no_value* parameter to the constructor can be used to
indicate that such values should be accepted:

Expand Down Expand Up @@ -615,7 +615,7 @@ the :meth:`!__init__` options:
prefixes for whole line comments.

.. versionchanged:: 3.2
In previous versions of :mod:`configparser` behaviour matched
In previous versions of :mod:`!configparser` behaviour matched
``comment_prefixes=('#',';')`` and ``inline_comment_prefixes=(';',)``.

Please note that config parsers don't support escaping of comment prefixes so
Expand Down Expand Up @@ -672,7 +672,7 @@ the :meth:`!__init__` options:
parsers in new applications.

.. versionchanged:: 3.2
In previous versions of :mod:`configparser` behaviour matched
In previous versions of :mod:`!configparser` behaviour matched
``strict=False``.

* *empty_lines_in_values*, default value: ``True``
Expand Down Expand Up @@ -842,7 +842,7 @@ be overridden by subclasses or by attribute assignment.
Legacy API Examples
-------------------

Mainly because of backwards compatibility concerns, :mod:`configparser`
Mainly because of backwards compatibility concerns, :mod:`!configparser`
provides also a legacy API with explicit ``get``/``set`` methods. While there
are valid use cases for the methods outlined below, mapping protocol access is
preferred for new projects. The legacy API is at times more advanced,
Expand Down Expand Up @@ -1378,7 +1378,7 @@ Exceptions

.. exception:: Error

Base class for all other :mod:`configparser` exceptions.
Base class for all other :mod:`!configparser` exceptions.


.. exception:: NoSectionError
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/contextlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -681,7 +681,7 @@ Examples and Recipes
--------------------

This section describes some examples and recipes for making effective use of
the tools provided by :mod:`contextlib`.
the tools provided by :mod:`!contextlib`.


Supporting a variable number of context managers
Expand Down
Loading
Loading