https://github.com/python/cpython/commit/3195da0b1a5dc8a03faa5142d4ab4a1549797e53
commit: 3195da0b1a5dc8a03faa5142d4ab4a1549797e53
branch: main
author: Adam Turner <[email protected]>
committer: AA-Turner <[email protected]>
date: 2025-10-05T21:15:36+01:00
summary:
gh-105812: Use the ``:deco:`` role in place of manual decorator markup (#139619)
files:
M Doc/library/collections.abc.rst
M Doc/library/dataclasses.rst
M Doc/library/functools.rst
M Doc/library/typing.rst
M Doc/library/warnings.rst
M Doc/reference/datamodel.rst
M Doc/whatsnew/2.7.rst
M Doc/whatsnew/3.10.rst
M Misc/NEWS.d/3.10.0b1.rst
M Misc/NEWS.d/3.11.0a1.rst
M Misc/NEWS.d/3.11.0b1.rst
M Misc/NEWS.d/3.14.0a1.rst
M Misc/NEWS.d/next/Library/2025-08-27-17-05-36.gh-issue-138010.ZZJmPL.rst
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 3d126bc83f5842..e6daccb91f2b4e 100644
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -336,7 +336,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
.. note::
In CPython, generator-based coroutines (:term:`generators <generator>`
- decorated with :func:`@types.coroutine <types.coroutine>`) are
+ decorated with :deco:`types.coroutine`) are
*awaitables*, even though they do not have an :meth:`~object.__await__`
method.
Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``.
Use :func:`inspect.isawaitable` to detect them.
@@ -354,7 +354,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
.. note::
In CPython, generator-based coroutines (:term:`generators <generator>`
- decorated with :func:`@types.coroutine <types.coroutine>`) are
+ decorated with :deco:`types.coroutine`) are
*awaitables*, even though they do not have an :meth:`~object.__await__`
method.
Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``.
Use :func:`inspect.isawaitable` to detect them.
diff --git a/Doc/library/dataclasses.rst b/Doc/library/dataclasses.rst
index ca432f2768a127..cff36e258224d3 100644
--- a/Doc/library/dataclasses.rst
+++ b/Doc/library/dataclasses.rst
@@ -317,7 +317,7 @@ Module contents
:func:`!field`, then the class attribute for this field will be
replaced by the specified *default* value. If *default* is not
provided, then the class attribute will be deleted. The intent is
- that after the :func:`@dataclass <dataclass>` decorator runs, the class
+ that after the :deco:`dataclass` decorator runs, the class
attributes will all contain the default values for the fields, just
as if the default value itself were specified. For example,
after::
@@ -427,7 +427,7 @@ Module contents
:data:`typing.Any` is used for ``type``. The values of *init*,
*repr*, *eq*, *order*, *unsafe_hash*, *frozen*,
*match_args*, *kw_only*, *slots*, and *weakref_slot* have
- the same meaning as they do in :func:`@dataclass <dataclass>`.
+ the same meaning as they do in :deco:`dataclass`.
If *module* is defined, the :attr:`!__module__` attribute
of the dataclass is set to that value.
@@ -435,12 +435,12 @@ Module contents
The *decorator* parameter is a callable that will be used to create the
dataclass.
It should take the class object as a first argument and the same keyword
arguments
- as :func:`@dataclass <dataclass>`. By default, the :func:`@dataclass
<dataclass>`
+ as :deco:`dataclass`. By default, the :deco:`dataclass`
function is used.
This function is not strictly required, because any Python
mechanism for creating a new class with :attr:`~object.__annotations__` can
- then apply the :func:`@dataclass <dataclass>` function to convert that
class to
+ then apply the :deco:`dataclass` function to convert that class to
a dataclass. This function is provided as a convenience. For
example::
@@ -569,7 +569,7 @@ Post-init processing
def __post_init__(self):
self.c = self.a + self.b
-The :meth:`~object.__init__` method generated by :func:`@dataclass
<dataclass>` does not call base
+The :meth:`~object.__init__` method generated by :deco:`dataclass` does not
call base
class :meth:`!__init__` methods. If the base class has an :meth:`!__init__`
method
that has to be called, it is common to call this method in a
:meth:`__post_init__` method::
@@ -599,7 +599,7 @@ parameters to :meth:`!__post_init__`. Also see the warning
about how
Class variables
---------------
-One of the few places where :func:`@dataclass <dataclass>` actually inspects
the type
+One of the few places where :deco:`dataclass` actually inspects the type
of a field is to determine if a field is a class variable as defined
in :pep:`526`. It does this by checking if the type of the field is
:data:`typing.ClassVar`. If a field is a ``ClassVar``, it is excluded
@@ -612,7 +612,7 @@ module-level :func:`fields` function.
Init-only variables
-------------------
-Another place where :func:`@dataclass <dataclass>` inspects a type annotation
is to
+Another place where :deco:`dataclass` inspects a type annotation is to
determine if a field is an init-only variable. It does this by seeing
if the type of a field is of type :class:`InitVar`. If a field
is an :class:`InitVar`, it is considered a pseudo-field called an init-only
@@ -646,7 +646,7 @@ Frozen instances
----------------
It is not possible to create truly immutable Python objects. However,
-by passing ``frozen=True`` to the :func:`@dataclass <dataclass>` decorator you
can
+by passing ``frozen=True`` to the :deco:`dataclass` decorator you can
emulate immutability. In that case, dataclasses will add
:meth:`~object.__setattr__` and :meth:`~object.__delattr__` methods to the
class. These
methods will raise a :exc:`FrozenInstanceError` when invoked.
@@ -662,7 +662,7 @@ must use :meth:`!object.__setattr__`.
Inheritance
-----------
-When the dataclass is being created by the :func:`@dataclass <dataclass>`
decorator,
+When the dataclass is being created by the :deco:`dataclass` decorator,
it looks through all of the class's base classes in reverse MRO (that
is, starting at :class:`object`) and, for each dataclass that it finds,
adds the fields from that base class to an ordered mapping of fields.
@@ -786,7 +786,7 @@ for :attr:`!x` when creating a class instance will share
the same copy
of :attr:`!x`. Because dataclasses just use normal Python class
creation they also share this behavior. There is no general way
for Data Classes to detect this condition. Instead, the
-:func:`@dataclass <dataclass>` decorator will raise a :exc:`ValueError` if it
+:deco:`dataclass` decorator will raise a :exc:`ValueError` if it
detects an unhashable default parameter. The assumption is that if
a value is unhashable, it is mutable. This is a partial solution,
but it does protect against many common errors.
@@ -820,7 +820,7 @@ default value have the following special behaviors:
:meth:`~object.__get__` or :meth:`!__set__` method is called rather than
returning or
overwriting the descriptor object.
-* To determine whether a field contains a default value, :func:`@dataclass
<dataclass>`
+* To determine whether a field contains a default value, :deco:`dataclass`
will call the descriptor's :meth:`!__get__` method using its class access
form: ``descriptor.__get__(obj=None, type=cls)``. If the
descriptor returns a value in this case, it will be used as the
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index beec9b942afc0f..f8ffb3f41d1210 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -690,7 +690,7 @@ The :mod:`functools` module defines the following functions:
return not arg
``@singledispatchmethod`` supports nesting with other decorators such as
- :func:`@classmethod<classmethod>`. Note that to allow for
+ :deco:`classmethod`. Note that to allow for
``dispatcher.register``, ``singledispatchmethod`` must be the *outer most*
decorator. Here is the ``Negator`` class with the ``neg`` methods bound to
the class, rather than an instance of the class::
@@ -712,8 +712,7 @@ The :mod:`functools` module defines the following functions:
return not arg
The same pattern can be used for other similar decorators:
- :func:`@staticmethod<staticmethod>`,
- :func:`@abstractmethod<abc.abstractmethod>`, and others.
+ :deco:`staticmethod`, :deco:`~abc.abstractmethod`, and others.
.. versionadded:: 3.8
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index e0122986e9ba3a..cfeeb19efbdf83 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -1390,7 +1390,7 @@ These can be used as types in annotations. They all
support subscription using
Using ``Annotated[T, x]`` as an annotation still allows for static
typechecking of ``T``, as type checkers will simply ignore the metadata
``x``.
In this way, ``Annotated`` differs from the
- :func:`@no_type_check <no_type_check>` decorator, which can also be used for
+ :deco:`no_type_check` decorator, which can also be used for
adding annotations outside the scope of the typing system, but
completely disables typechecking for a function or class.
@@ -2815,7 +2815,7 @@ Protocols
---------
The following protocols are provided by the :mod:`!typing` module. All are
decorated
-with :func:`@runtime_checkable <runtime_checkable>`.
+with :deco:`runtime_checkable`.
.. class:: SupportsAbs
@@ -2996,7 +2996,7 @@ Functions and decorators
The presence of ``@dataclass_transform()`` tells a static type checker that
the
decorated object performs runtime "magic" that
transforms a class in a similar way to
- :func:`@dataclasses.dataclass <dataclasses.dataclass>`.
+ :deco:`dataclasses.dataclass`.
Example usage with a decorator function:
@@ -3034,14 +3034,14 @@ Functions and decorators
The ``CustomerModel`` classes defined above will
be treated by type checkers similarly to classes created with
- :func:`@dataclasses.dataclass <dataclasses.dataclass>`.
+ :deco:`dataclasses.dataclass`.
For example, type checkers will assume these classes have
``__init__`` methods that accept ``id`` and ``name``.
The decorated class, metaclass, or function may accept the following bool
arguments which type checkers will assume have the same effect as they
would have on the
- :func:`@dataclasses.dataclass<dataclasses.dataclass>` decorator: ``init``,
+ :deco:`dataclasses.dataclass` decorator: ``init``,
``eq``, ``order``, ``unsafe_hash``, ``frozen``, ``match_args``,
``kw_only``, and ``slots``. It must be possible for the value of these
arguments (``True`` or ``False``) to be statically evaluated.
@@ -3169,12 +3169,12 @@ Functions and decorators
.. function:: get_overloads(func)
- Return a sequence of :func:`@overload <overload>`-decorated definitions for
+ Return a sequence of :deco:`overload`-decorated definitions for
*func*.
*func* is the function object for the implementation of the
overloaded function. For example, given the definition of ``process`` in
- the documentation for :func:`@overload <overload>`,
+ the documentation for :deco:`overload`,
``get_overloads(process)`` will return a sequence of three function objects
for the three defined overloads. If called on a function with no overloads,
``get_overloads()`` returns an empty sequence.
@@ -3331,7 +3331,7 @@ Introspection helpers
If *globalns* or *localns* is not given, appropriate namespace
dictionaries are inferred from *obj*.
* ``None`` is replaced with :class:`types.NoneType`.
- * If :func:`@no_type_check <no_type_check>` has been applied to *obj*, an
+ * If :deco:`no_type_check` has been applied to *obj*, an
empty dictionary is returned.
* If *obj* is a class ``C``, the function returns a dictionary that merges
annotations from ``C``'s base classes with those on ``C`` directly. This
diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index 5b17bd009b36e7..f9c8c4fc3a804e 100644
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -590,7 +590,7 @@ Available Functions
The deprecation message passed to the decorator is saved in the
``__deprecated__`` attribute on the decorated object.
If applied to an overload, the decorator
- must be after the :func:`@overload <typing.overload>` decorator
+ must be after the :deco:`~typing.overload` decorator
for the attribute to exist on the overload as returned by
:func:`typing.get_overloads`.
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 7185d68c5cca4a..29f82fc12da1cc 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -2558,7 +2558,7 @@ instance dictionary. In contrast, non-data descriptors
can be overridden by
instances.
Python methods (including those decorated with
-:func:`@staticmethod <staticmethod>` and :func:`@classmethod <classmethod>`)
are
+:deco:`staticmethod` and :deco:`classmethod`) are
implemented as non-data descriptors. Accordingly, instances can redefine and
override methods. This allows individual instances to acquire behaviors that
differ from other instances of the same class.
@@ -2993,7 +2993,7 @@ class method ``__class_getitem__()``.
When defined on a class, ``__class_getitem__()`` is automatically a class
method. As such, there is no need for it to be decorated with
- :func:`@classmethod<classmethod>` when it is defined.
+ :deco:`classmethod` when it is defined.
The purpose of *__class_getitem__*
diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
index bcc5a3d56903d2..09feb185b82ea7 100644
--- a/Doc/whatsnew/2.7.rst
+++ b/Doc/whatsnew/2.7.rst
@@ -858,8 +858,8 @@ Some smaller changes made to the core Python language are:
.. XXX bytearray doesn't seem to be documented
-* When using :class:`@classmethod <classmethod>` and
- :class:`@staticmethod <staticmethod>` to wrap
+* When using :deco:`classmethod` and
+ :deco:`staticmethod` to wrap
methods as class or static methods, the wrapper object now
exposes the wrapped function as their :attr:`~method.__func__`
attribute.
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index 8db57f6f22fc8d..d8251185fa7f4b 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -847,8 +847,8 @@ Other Language Changes
respectively.
(Contributed by Joshua Bronson, Daniel Pope, and Justin Wang in
:issue:`31861`.)
-* Static methods (:func:`@staticmethod <staticmethod>`) and class methods
- (:func:`@classmethod <classmethod>`) now inherit the method attributes
+* Static methods (:deco:`staticmethod`) and class methods
+ (:deco:`classmethod`) now inherit the method attributes
(``__module__``, ``__name__``, ``__qualname__``, ``__doc__``,
``__annotations__``) and have a new ``__wrapped__`` attribute.
Moreover, static methods are now callable as regular functions.
diff --git a/Misc/NEWS.d/3.10.0b1.rst b/Misc/NEWS.d/3.10.0b1.rst
index 406a5d7853edc0..5bc78b9007afa8 100644
--- a/Misc/NEWS.d/3.10.0b1.rst
+++ b/Misc/NEWS.d/3.10.0b1.rst
@@ -402,8 +402,8 @@ the heap. Should speed up dispatch in the interpreter.
.. nonce: eUn4p5
.. section: Core and Builtins
-Static methods (:func:`@staticmethod <staticmethod>`) and class methods
-(:func:`@classmethod <classmethod>`) now inherit the method attributes
+Static methods (:deco:`staticmethod`) and class methods
+(:deco:`classmethod`) now inherit the method attributes
(``__module__``, ``__name__``, ``__qualname__``, ``__doc__``,
``__annotations__``) and have a new ``__wrapped__`` attribute. Patch by
Victor Stinner.
@@ -454,7 +454,7 @@ file locations.
.. nonce: VSF3vg
.. section: Core and Builtins
-Static methods (:func:`@staticmethod <staticmethod>`) are now callable as
+Static methods (:deco:`staticmethod`) are now callable as
regular functions. Patch by Victor Stinner.
..
diff --git a/Misc/NEWS.d/3.11.0a1.rst b/Misc/NEWS.d/3.11.0a1.rst
index 94e4868eb29cf3..c7e57754ee3341 100644
--- a/Misc/NEWS.d/3.11.0a1.rst
+++ b/Misc/NEWS.d/3.11.0a1.rst
@@ -2953,7 +2953,7 @@ support for Metadata 2.2.
.. nonce: xTUyyX
.. section: Library
-Remove the :func:`@asyncio.coroutine <asyncio.coroutine>` :term:`decorator`
+Remove the :deco:`asyncio.coroutine` :term:`decorator`
enabling legacy generator-based coroutines to be compatible with async/await
code; remove :class:`asyncio.coroutines.CoroWrapper` used for wrapping
legacy coroutine objects in the debug mode. The decorator has been
diff --git a/Misc/NEWS.d/3.11.0b1.rst b/Misc/NEWS.d/3.11.0b1.rst
index c3a1942b881ad4..7b8b983ebf951e 100644
--- a/Misc/NEWS.d/3.11.0b1.rst
+++ b/Misc/NEWS.d/3.11.0b1.rst
@@ -664,7 +664,7 @@ for :func:`os.fcopyfile` available in macOs.
.. nonce: l1p7CJ
.. section: Library
-For :func:`@dataclass <dataclasses.dataclass>`, add *weakref_slot*.
+For :deco:`~dataclasses.dataclass`, add *weakref_slot*.
The new parameter defaults to ``False``. If true, and if
``slots=True``, add a slot named ``"__weakref__"``, which will allow instances
to be
weakref'd. Contributed by Eric V. Smith
diff --git a/Misc/NEWS.d/3.14.0a1.rst b/Misc/NEWS.d/3.14.0a1.rst
index 07f2f521ece5b9..305a0b65b98e6a 100644
--- a/Misc/NEWS.d/3.14.0a1.rst
+++ b/Misc/NEWS.d/3.14.0a1.rst
@@ -1999,7 +1999,7 @@ with an escape character.
.. nonce: vi2bP-
.. section: Library
-:func:`@warnings.deprecated <warnings.deprecated>` now copies the coroutine
+:deco:`warnings.deprecated` now copies the coroutine
status of functions and methods so that :func:`inspect.iscoroutinefunction`
returns the correct result.
diff --git
a/Misc/NEWS.d/next/Library/2025-08-27-17-05-36.gh-issue-138010.ZZJmPL.rst
b/Misc/NEWS.d/next/Library/2025-08-27-17-05-36.gh-issue-138010.ZZJmPL.rst
index 117f3ad6c6761b..1cc031a8bf5287 100644
--- a/Misc/NEWS.d/next/Library/2025-08-27-17-05-36.gh-issue-138010.ZZJmPL.rst
+++ b/Misc/NEWS.d/next/Library/2025-08-27-17-05-36.gh-issue-138010.ZZJmPL.rst
@@ -1,4 +1,4 @@
-Fix an issue where defining a class with an :func:`@warnings.deprecated
-<warnings.deprecated>`-decorated base class may not invoke the correct
+Fix an issue where defining a class with a
:deco:`warnings.deprecated`-decorated
+base class may not invoke the correct
:meth:`~object.__init_subclass__` method in cases involving multiple
inheritance. Patch by Brian Schubert.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
