gh-105812: Make use of the Sphinx deco role in documentation, part final

Viicos · Viicos · commit d05bf63f967f · 2025-10-25T16:30:11.000+02:00
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
@@ -954,7 +954,7 @@ Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requ
 special recursion handling.  In addition to protecting the stack,
 :c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles.  The
 following two functions facilitate this functionality.  Effectively,
-these are the C equivalent to :func:`reprlib.recursive_repr`.
+these are the C equivalent to :deco:`reprlib.recursive_repr`.
 
 .. c:function:: int Py_ReprEnter(PyObject *object)
 
diff --git a/Doc/deprecations/pending-removal-in-3.15.rst b/Doc/deprecations/pending-removal-in-3.15.rst
@@ -92,7 +92,7 @@ Pending removal in Python 3.15
     Use ``class TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``
     to create a TypedDict with zero field.
 
-  * The :func:`!typing.no_type_check_decorator` decorator function
+  * The :deco:`!typing.no_type_check_decorator` decorator function
     has been deprecated since Python 3.13.
     After eight years in the :mod:`typing` module,
     it has yet to be supported by any major type checker.
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
@@ -622,7 +622,7 @@ Glossary
       determined by the dispatch algorithm.
 
       See also the :term:`single dispatch` glossary entry, the
-      :func:`functools.singledispatch` decorator, and :pep:`443`.
+      :deco:`functools.singledispatch` decorator, and :pep:`443`.
 
    generic type
       A :term:`type` that can be parameterized; typically a
diff --git a/Doc/howto/annotations.rst b/Doc/howto/annotations.rst
@@ -154,7 +154,7 @@ on an arbitrary object ``o``:
   as the ``globals``, and ``dict(vars(o))`` as the ``locals``,
   when calling :func:`eval`.
 * If ``o`` is a wrapped callable using :func:`functools.update_wrapper`,
-  :func:`functools.wraps`, or :func:`functools.partial`, iteratively
+  :deco:`functools.wraps`, or :func:`functools.partial`, iteratively
   unwrap it by accessing either ``o.__wrapped__`` or ``o.func`` as
   appropriate, until you have found the root unwrapped function.
 * If ``o`` is a callable (but not a class), use
diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst
@@ -509,7 +509,7 @@ to use the standard :func:`repr`.
 
 .. note::
 
-   Adding :func:`~dataclasses.dataclass` decorator to :class:`Enum`
+   Adding :deco:`~dataclasses.dataclass` decorator to :class:`Enum`
    and its subclasses is not supported. It will not raise any errors,
    but it will produce very strange results at runtime, such as members
    being equal to each other::
diff --git a/Doc/howto/sorting.rst b/Doc/howto/sorting.rst
@@ -375,7 +375,7 @@ Odds and Ends
   :meth:`~object.__lt__` is not implemented (see :func:`object.__lt__`
   for details on the mechanics).  To avoid surprises, :pep:`8`
   recommends that all six comparison methods be implemented.
-  The :func:`~functools.total_ordering` decorator is provided to make that
+  The :deco:`~functools.total_ordering` decorator is provided to make that
   task easier.
 
 * Key functions need not depend directly on the objects being sorted. A key
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
@@ -283,8 +283,8 @@ The :mod:`!abc` module also supports the following legacy decorators:
 .. decorator:: abstractproperty
 
    .. deprecated:: 3.3
-       It is now possible to use :deco:`property`, :meth:`property.getter`,
-       :meth:`property.setter` and :meth:`property.deleter` with
+       It is now possible to use :deco:`property`, :deco:`property.getter`,
+       :deco:`property.setter` and :deco:`property.deleter` with
        :deco:`abstractmethod`, making this decorator redundant.
 
    A subclass of the built-in :class:`property`, indicating an abstract
diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
@@ -92,7 +92,7 @@ Functions and classes provided:
    it creates can be used as decorators as well as in :keyword:`with` statements.
    When used as a decorator, a new generator instance is implicitly created on
    each function call (this allows the otherwise "one-shot" context managers
-   created by :func:`contextmanager` to meet the requirement that context
+   created by :deco:`contextmanager` to meet the requirement that context
    managers support multiple invocations in order to be used as decorators).
 
    .. versionchanged:: 3.2
@@ -101,7 +101,7 @@ Functions and classes provided:
 
 .. decorator:: asynccontextmanager
 
-   Similar to :func:`~contextlib.contextmanager`, but creates an
+   Similar to :deco:`~contextlib.contextmanager`, but creates an
    :ref:`asynchronous context manager <async-context-managers>`.
 
    This function is a :term:`decorator` that can be used to define a factory
@@ -128,7 +128,7 @@ Functions and classes provided:
 
    .. versionadded:: 3.7
 
-   Context managers defined with :func:`asynccontextmanager` can be used
+   Context managers defined with :deco:`asynccontextmanager` can be used
    either as decorators or with :keyword:`async with` statements::
 
      import time
@@ -148,11 +148,11 @@ Functions and classes provided:
 
    When used as a decorator, a new generator instance is implicitly created on
    each function call. This allows the otherwise "one-shot" context managers
-   created by :func:`asynccontextmanager` to meet the requirement that context
+   created by :deco:`asynccontextmanager` to meet the requirement that context
    managers support multiple invocations in order to be used as decorators.
 
    .. versionchanged:: 3.10
-      Async context managers created with :func:`asynccontextmanager` can
+      Async context managers created with :deco:`asynccontextmanager` can
       be used as decorators.
 
 
@@ -399,7 +399,7 @@ Functions and classes provided:
    ``__enter__`` and ``__exit__`` as normal. ``__exit__`` retains its optional
    exception handling even when used as a decorator.
 
-   ``ContextDecorator`` is used by :func:`contextmanager`, so you get this
+   ``ContextDecorator`` is used by :deco:`contextmanager`, so you get this
    functionality automatically.
 
    Example of ``ContextDecorator``::
@@ -653,7 +653,7 @@ Functions and classes provided:
 
       Similar to :meth:`ExitStack.close` but properly handles awaitables.
 
-   Continuing the example for :func:`asynccontextmanager`::
+   Continuing the example for :deco:`asynccontextmanager`::
 
       async with AsyncExitStack() as stack:
           connections = [await stack.enter_async_context(get_connection())
@@ -911,7 +911,7 @@ Files are an example of effectively single use context managers, since
 the first :keyword:`with` statement will close the file, preventing any
 further IO operations using that file object.
 
-Context managers created using :func:`contextmanager` are also single use
+Context managers created using :deco:`contextmanager` are also single use
 context managers, and will complain about the underlying generator failing
 to yield if an attempt is made to use them a second time::
 
diff --git a/Doc/library/test.rst b/Doc/library/test.rst
@@ -714,7 +714,7 @@ The :mod:`test.support` module defines the following functions:
 .. decorator:: anticipate_failure(condition)
 
    A decorator to conditionally mark tests with
-   :func:`unittest.expectedFailure`. Any use of this decorator should
+   :deco:`unittest.expectedFailure`. Any use of this decorator should
    have an associated comment identifying the relevant tracker issue.
 
 
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
@@ -2501,7 +2501,7 @@ types.
       func(C())  # Passes static type check
 
    See :pep:`544` for more details. Protocol classes decorated with
-   :func:`runtime_checkable` (described later) act as simple-minded runtime
+   :deco:`runtime_checkable` (described later) act as simple-minded runtime
    protocols that check only the presence of given attributes, ignoring their
    type signatures. Protocol classes without this decorator cannot be used
    as the second argument to :func:`isinstance` or :func:`issubclass`.
@@ -2548,7 +2548,7 @@ types.
 
    .. note::
 
-        :func:`!runtime_checkable` will check only the presence of the required
+        :deco:`!runtime_checkable` will check only the presence of the required
         methods or attributes, not their type signatures or types.
         For example, :class:`ssl.SSLObject`
         is a class, therefore it passes an :func:`issubclass`
@@ -3005,7 +3005,7 @@ Functions and decorators
    Decorator to mark an object as providing
    :func:`dataclass <dataclasses.dataclass>`-like behavior.
 
-   ``dataclass_transform`` may be used to
+   ``@dataclass_transform`` may be used to
    decorate a class, metaclass, or a function that is itself a decorator.
    The presence of ``@dataclass_transform()`` tells a static type checker that the
    decorated object performs runtime "magic" that
@@ -3060,7 +3060,7 @@ Functions and decorators
    ``kw_only``, and ``slots``. It must be possible for the value of these
    arguments (``True`` or ``False``) to be statically evaluated.
 
-   The arguments to the ``dataclass_transform`` decorator can be used to
+   The arguments to the ``@dataclass_transform`` decorator can be used to
    customize the default behaviors of the decorated class, metaclass, or
    function:
 
@@ -3124,8 +3124,8 @@ Functions and decorators
           keyword-only. If ``True``, the field will be keyword-only. If
           ``False``, it will not be keyword-only. If unspecified, the value of
           the ``kw_only`` parameter on the object decorated with
-          ``dataclass_transform`` will be used, or if that is unspecified, the
-          value of ``kw_only_default`` on ``dataclass_transform`` will be used.
+          ``@dataclass_transform`` will be used, or if that is unspecified, the
+          value of ``kw_only_default`` on ``@dataclass_transform`` will be used.
       * - ``alias``
         - Provides an alternative name for the field. This alternative
           name is used in the synthesized ``__init__`` method.
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
@@ -535,7 +535,7 @@ tests.  In addition, it supports marking a test as an "expected failure," a test
 that is broken and will fail, but shouldn't be counted as a failure on a
 :class:`TestResult`.
 
-Skipping a test is simply a matter of using the :func:`skip` :term:`decorator`
+Skipping a test is simply a matter of using the :deco:`skip` :term:`decorator`
 or one of its conditional variants, calling :meth:`TestCase.skipTest` within a
 :meth:`~TestCase.setUp` or test method, or raising :exc:`SkipTest` directly.
 
@@ -586,7 +586,7 @@ Classes can be skipped just like methods::
 :meth:`TestCase.setUp` can also skip the test.  This is useful when a resource
 that needs to be set up is not available.
 
-Expected failures use the :func:`expectedFailure` decorator. ::
+Expected failures use the :deco:`expectedFailure` decorator. ::
 
    class ExpectedFailureTestCase(unittest.TestCase):
        @unittest.expectedFailure
@@ -2138,7 +2138,7 @@ Loading and running tests
 
       .. versionchanged:: 3.4
          Returns ``False`` if there were any :attr:`unexpectedSuccesses`
-         from tests marked with the :func:`expectedFailure` decorator.
+         from tests marked with the :deco:`expectedFailure` decorator.
 
    .. method:: stop()
 
@@ -2221,7 +2221,7 @@ Loading and running tests
    .. method:: addExpectedFailure(test, err)
 
       Called when the test case *test* fails or errors, but was marked with
-      the :func:`expectedFailure` decorator.
+      the :deco:`expectedFailure` decorator.
 
       The default implementation appends a tuple ``(test, formatted_err)`` to
       the instance's :attr:`expectedFailures` attribute, where *formatted_err*
@@ -2231,7 +2231,7 @@ Loading and running tests
    .. method:: addUnexpectedSuccess(test)
 
       Called when the test case *test* was marked with the
-      :func:`expectedFailure` decorator, but succeeded.
+      :deco:`expectedFailure` decorator, but succeeded.
 
       The default implementation appends the test to the instance's
       :attr:`unexpectedSuccesses` attribute.
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
@@ -2006,7 +2006,7 @@ Annotations are conventionally used for :term:`type hints <type hint>`, but this
 is not enforced by the language, and in general annotations may contain arbitrary
 expressions. The presence of annotations does not change the runtime semantics of
 the code, except if some mechanism is used that introspects and uses the annotations
-(such as :mod:`dataclasses` or :func:`functools.singledispatch`).
+(such as :mod:`dataclasses` or :deco:`functools.singledispatch`).
 
 By default, annotations are lazily evaluated in an :ref:`annotation scope <annotation-scopes>`.
 This means that they are not evaluated when the code containing the annotation is evaluated.
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
@@ -2143,7 +2143,7 @@ Basic customization
    :data:`!NotImplemented`.  There are no other implied relationships among the
    comparison operators or default implementations; for example, the truth of
    ``(x<y or x==y)`` does not imply ``x<=y``. To automatically generate ordering
-   operations from a single root operation, see :func:`functools.total_ordering`.
+   operations from a single root operation, see :deco:`functools.total_ordering`.
 
    By default, the :class:`object` class provides implementations consistent
    with :ref:`expressions-value-comparisons`: equality compares according to
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
@@ -1756,7 +1756,7 @@ some consistency rules, if possible:
 
   The last two expressions apply to totally ordered collections (e.g. to
   sequences, but not to sets or mappings). See also the
-  :func:`~functools.total_ordering` decorator.
+  :deco:`~functools.total_ordering` decorator.
 
 * The :func:`hash` result should be consistent with equality.
   Objects that are equal should either have the same hash value,
diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst
@@ -745,7 +745,7 @@ The contextlib module
 The new :mod:`contextlib` module provides some functions and a decorator that
 are useful for writing objects for use with the ':keyword:`with`' statement.
 
-The decorator is called :func:`contextmanager`, and lets you write a single
+The decorator is called :deco:`contextmanager`, and lets you write a single
 generator function instead of defining a new class.  The generator should yield
 exactly one value.  The code up to the :keyword:`yield` will be executed as the
 :meth:`~object.__enter__` method, and the value yielded will be the method's return
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
@@ -431,7 +431,7 @@ The contextlib module
 The :mod:`contextlib` module provides some functions and a decorator that
 are useful when writing objects for use with the ':keyword:`with`' statement.
 
-The decorator is called :func:`~contextlib.contextmanager`, and lets you write
+The decorator is called :deco:`~contextlib.contextmanager`, and lets you write
 a single generator function instead of defining a new class.  The generator
 should yield exactly one value.  The code up to the :keyword:`yield` will be
 executed as the :meth:`~object.__enter__` method, and the value yielded will
@@ -1557,8 +1557,9 @@ Some smaller changes made to the core Python language are:
 
   .. Revision 57619
 
-* Properties now have three attributes, :attr:`getter`, :attr:`setter`
-  and :attr:`deleter`, that are decorators providing useful shortcuts
+* Properties now have three decorators, :deco:`~property.getter`,
+  :deco:`~property.setter` and :deco:`~property.deleter`, that are
+  decorators providing useful shortcuts
   for adding a getter, setter or deleter function to an existing
   property. You would use them like this::
 
diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
@@ -1267,7 +1267,7 @@ changes, or look through the Subversion logs for all the details.
   uploads thanks to an added *rest* parameter (patch by Pablo Mouzo;
   :issue:`6845`.)
 
-* New class decorator: :func:`~functools.total_ordering` in the :mod:`functools`
+* New class decorator: :deco:`~functools.total_ordering` in the :mod:`functools`
   module takes a class that defines an :meth:`~object.__eq__` method and one of
   :meth:`~object.__lt__`, :meth:`~object.__le__`, :meth:`~object.__gt__`, or :meth:`~object.__ge__`,
   and generates the missing comparison methods.  Since the
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
@@ -996,7 +996,7 @@ dataclasses
 __slots__
 ~~~~~~~~~
 
-Added ``slots`` parameter in :func:`dataclasses.dataclass` decorator.
+Added ``slots`` parameter in :deco:`dataclasses.dataclass` decorator.
 (Contributed by Yurii Karabas in :issue:`42269`)
 
 Keyword-only fields
@@ -1485,9 +1485,9 @@ is a :class:`typing.TypedDict`.
 
 Subclasses of ``typing.Protocol`` which only have data variables declared
 will now raise a ``TypeError`` when checked with ``isinstance`` unless they
-are decorated with :func:`~typing.runtime_checkable`.  Previously, these checks
+are decorated with :deco:`~typing.runtime_checkable`.  Previously, these checks
 passed silently.  Users should decorate their
-subclasses with the :func:`!runtime_checkable` decorator
+subclasses with the :deco:`!runtime_checkable` decorator
 if they want runtime protocols.
 (Contributed by Yurii Karabas in :issue:`38908`.)
 
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
@@ -388,7 +388,7 @@ Kumar Srinivasan and Graham Bleaney.)
 PEP 681: Data class transforms
 ------------------------------
 
-:data:`~typing.dataclass_transform` may be used to
+:deco:`~typing.dataclass_transform` may be used to
 decorate a class, metaclass, or a function that is itself a decorator.
 The presence of ``@dataclass_transform()`` tells a static type checker that the
 decorated object performs runtime "magic" that transforms a class,
@@ -740,7 +740,7 @@ fractions
 functools
 ---------
 
-* :func:`functools.singledispatch` now supports :class:`types.UnionType`
+* :deco:`functools.singledispatch` now supports :class:`types.UnionType`
   and :class:`typing.Union` as annotations to the dispatch argument.::
 
     >>> from functools import singledispatch
@@ -1164,7 +1164,7 @@ For major changes, see :ref:`new-feat-related-type-hints-311`.
   type checker errors related to highly dynamic class, such as mocks.
   (Contributed by Shantanu Jain in :gh:`91154`.)
 
-* The :func:`typing.final` decorator now sets the ``__final__`` attributed on
+* The :deco:`typing.final` decorator now sets the ``__final__`` attributed on
   the decorated object.
   (Contributed by Jelle Zijlstra in :gh:`90500`.)
 
@@ -1197,7 +1197,7 @@ For major changes, see :ref:`new-feat-related-type-hints-311`.
   :data:`~typing.ClassVar` annotations. (Contributed by Gregory Beauregard
   in :gh:`90711`.)
 
-* :func:`typing.no_type_check` no longer modifies external classes and functions.
+* :deco:`typing.no_type_check` no longer modifies external classes and functions.
   It also now correctly marks classmethods as not to be type checked. (Contributed
   by Nikita Sobolev in :gh:`90729`.)
 
diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
@@ -146,7 +146,7 @@ New typing features:
 
 * :ref:`PEP 692 <whatsnew312-pep692>`, using :class:`~typing.TypedDict` to
   annotate :term:`**kwargs <argument>`
-* :ref:`PEP 698 <whatsnew312-pep698>`, :func:`typing.override` decorator
+* :ref:`PEP 698 <whatsnew312-pep698>`, :deco:`typing.override` decorator
 
 Important deprecations, removals or restrictions:
 
@@ -511,7 +511,7 @@ See :pep:`692` for more details.
 PEP 698: Override Decorator for Static Typing
 ---------------------------------------------
 
-A new decorator :func:`typing.override` has been added to the :mod:`typing`
+A new decorator :deco:`typing.override` has been added to the :mod:`typing`
 module. It indicates to type checkers that the method is intended to override
 a method in a superclass. This allows type checkers to catch mistakes where
 a method that is intended to override something in a base class
@@ -1021,7 +1021,7 @@ typing
   ``__orig_bases__`` attribute. (Contributed by Adrian Garcia Badaracco in
   :gh:`103699`.)
 
-* Add ``frozen_default`` parameter to :func:`typing.dataclass_transform`.
+* Add ``frozen_default`` parameter to :deco:`typing.dataclass_transform`.
   (Contributed by Erik De Bonte in :gh:`99957`.)
 
 unicodedata
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
@@ -1993,7 +1993,7 @@ New Deprecations
     use ``class TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``.
     (Contributed by Alex Waygood in :gh:`105566` and :gh:`105570`.)
 
-  * Deprecate the :func:`!typing.no_type_check_decorator` decorator function,
+  * Deprecate the :deco:`!typing.no_type_check_decorator` decorator function,
     to be removed in Python 3.15.
     After eight years in the :mod:`typing` module,
     it has yet to be supported by any major type checker.
diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
