gh-105812: [PoC] add :deco: role and adapt some rst files

Doc/faq/programming.rst

@@ -1966,11 +1966,11 @@ How do I cache method calls?
 ----------------------------
 
 The two principal tools for caching methods are
-:func:`functools.cached_property` and :func:`functools.lru_cache`.  The
+:deco:`functools.cached_property` and :deco:`functools.lru_cache`.  The
 former stores results at the instance level and the latter at the class
 level.
 
-The *cached_property* approach only works with methods that do not take
+The :deco:`!cached_property` approach only works with methods that do not take
 any arguments.  It does not create a reference to the instance.  The
 cached method result will be kept only as long as the instance is alive.
 
@@ -1979,7 +1979,7 @@ method result will be released right away.  The disadvantage is that if
 instances accumulate, so too will the accumulated method results.  They
 can grow without bound.
 
-The *lru_cache* approach works with methods that have :term:`hashable`
+The :deco:`!lru_cache` approach works with methods that have :term:`hashable`
 arguments.  It creates a reference to the instance unless special
 efforts are made to pass in weak references.
 
@@ -2017,7 +2017,7 @@ relevant instance attributes are mutable, the *cached_property* approach
 can't be made to work because it cannot detect changes to the
 attributes.
 
-To make the *lru_cache* approach work when the *station_id* is mutable,
+To make the :deco:`~functools.lru_cache` approach work when the *station_id* is mutable,
 the class needs to define the :meth:`~object.__eq__` and :meth:`~object.__hash__`
 methods so that the cache can detect relevant attribute updates::
 

Doc/howto/annotations.rst

@@ -149,7 +149,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

Doc/howto/enum.rst

@@ -506,7 +506,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::

Doc/library/abc.rst

@@ -170,17 +170,17 @@ The :mod:`!abc` module also provides the following decorator:
    or is derived from it.  A class that has a metaclass derived from
    :class:`!ABCMeta` cannot be instantiated unless all of its abstract methods
    and properties are overridden.  The abstract methods can be called using any
-   of the normal 'super' call mechanisms.  :func:`!abstractmethod` may be used
+   of the normal 'super' call mechanisms.  :deco:`!abstractmethod` may be used
    to declare abstract methods for properties and descriptors.
 
    Dynamically adding abstract methods to a class, or attempting to modify the
    abstraction status of a method or class once it is created, are only
    supported using the :func:`update_abstractmethods` function.  The
-   :func:`!abstractmethod` only affects subclasses derived using regular
+   :deco:`!abstractmethod` only affects subclasses derived using regular
    inheritance; "virtual subclasses" registered with the ABC's
    :meth:`~ABCMeta.register` method are not affected.
 
-   When :func:`!abstractmethod` is applied in combination with other method
+   When :deco:`!abstractmethod` is applied in combination with other method
    descriptors, it should be applied as the innermost decorator, as shown in
    the following usage examples::
 
@@ -242,13 +242,13 @@ The :mod:`!abc` module also supports the following legacy decorators:
 
    .. versionadded:: 3.2
    .. deprecated:: 3.3
-       It is now possible to use :class:`classmethod` with
-       :func:`abstractmethod`, making this decorator redundant.
+       It is now possible to use :deco:`!classmethod` with
+       :deco:`!abstractmethod`, making this decorator redundant.
 
-   A subclass of the built-in :func:`classmethod`, indicating an abstract
-   classmethod. Otherwise it is similar to :func:`abstractmethod`.
+   A subclass of the built-in :deco:`classmethod`, indicating an abstract
+   classmethod. Otherwise it is similar to :deco:`abstractmethod`.
 
-   This special case is deprecated, as the :func:`classmethod` decorator
+   This special case is deprecated, as the :deco:`!classmethod` decorator
    is now correctly identified as abstract when applied to an abstract
    method::
 
@@ -263,13 +263,13 @@ The :mod:`!abc` module also supports the following legacy decorators:
 
    .. versionadded:: 3.2
    .. deprecated:: 3.3
-       It is now possible to use :class:`staticmethod` with
-       :func:`abstractmethod`, making this decorator redundant.
+       It is now possible to use :deco:`!staticmethod` with
+       :deco:`!abstractmethod`, making this decorator redundant.
 
-   A subclass of the built-in :func:`staticmethod`, indicating an abstract
-   staticmethod. Otherwise it is similar to :func:`abstractmethod`.
+   A subclass of the built-in :deco:`staticmethod`, indicating an abstract
+   staticmethod. Otherwise it is similar to :deco:`abstractmethod`.
 
-   This special case is deprecated, as the :func:`staticmethod` decorator
+   This special case is deprecated, as the :deco:`!staticmethod` decorator
    is now correctly identified as abstract when applied to an abstract
    method::
 
@@ -283,14 +283,14 @@ The :mod:`!abc` module also supports the following legacy decorators:
 .. decorator:: abstractproperty
 
    .. deprecated:: 3.3
-       It is now possible to use :class:`property`, :meth:`property.getter`,
-       :meth:`property.setter` and :meth:`property.deleter` with
-       :func:`abstractmethod`, making this decorator redundant.
+       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 :func:`property`, indicating an abstract
+   A subclass of the built-in :deco:`!property`, indicating an abstract
    property.
 
-   This special case is deprecated, as the :func:`property` decorator
+   This special case is deprecated, as the :deco:`!property` decorator
    is now correctly identified as abstract when applied to an abstract
    method::
 

Doc/library/collections.rst

@@ -1205,7 +1205,7 @@ original insertion position is changed and moved to the end::
             self.move_to_end(key)
 
 An :class:`OrderedDict` would also be useful for implementing
-variants of :func:`functools.lru_cache`:
+variants of :deco:`functools.lru_cache`:
 
 .. testcode::
 

Doc/library/contextlib.rst

@@ -88,11 +88,11 @@ Functions and classes provided:
    the exception has been handled, and execution will resume with the statement
    immediately following the :keyword:`!with` statement.
 
-   :func:`contextmanager` uses :class:`ContextDecorator` so the context managers
+   :deco:`!contextmanager` uses :class:`ContextDecorator` so the context managers
    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.
 
 
@@ -397,7 +397,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``::
@@ -649,7 +649,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())
@@ -907,7 +907,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::
 

Doc/library/dataclasses.rst

@@ -51,24 +51,24 @@ Module contents
    This function is a :term:`decorator` that is used to add generated
    :term:`special methods <special method>` to classes, as described below.
 
-   The ``@dataclass`` decorator examines the class to find
+   The :deco:`!dataclass` decorator examines the class to find
    ``field``\s.  A ``field`` is defined as a class variable that has a
    :term:`type annotation <variable annotation>`.  With two
-   exceptions described below, nothing in ``@dataclass``
+   exceptions described below, nothing in :deco:`!dataclass`
    examines the type specified in the variable annotation.
 
    The order of the fields in all of the generated methods is the
    order in which they appear in the class definition.
 
-   The ``@dataclass`` decorator will add various "dunder" methods to
+   The :deco:`!dataclass` decorator will add various "dunder" methods to
    the class, described below.  If any of the added methods already
    exist in the class, the behavior depends on the parameter, as documented
    below. The decorator returns the same class that it is called on; no new
    class is created.
 
-   If ``@dataclass`` is used just as a simple decorator with no parameters,
+   If :deco:`!dataclass` is used just as a simple decorator with no parameters,
    it acts as if it has the default values documented in this
-   signature.  That is, these three uses of ``@dataclass`` are
+   signature.  That is, these three uses of :deco:`!dataclass` are
    equivalent::
 
      @dataclass
@@ -84,7 +84,7 @@ Module contents
      class C:
          ...
 
-   The parameters to ``@dataclass`` are:
+   The parameters to :deco:`!dataclass` are:
 
    - *init*: If true (the default), a :meth:`~object.__init__` method will be
      generated.
@@ -129,17 +129,17 @@ Module contents
      :meth:`!__hash__` implies that instances of the class are immutable.
      Mutability is a complicated property that depends on the programmer's
      intent, the existence and behavior of :meth:`!__eq__`, and the values of
-     the *eq* and *frozen* flags in the ``@dataclass`` decorator.
+     the *eq* and *frozen* flags in the :deco:`!dataclass` decorator.
 
-     By default, ``@dataclass`` will not implicitly add a :meth:`~object.__hash__`
+     By default, :deco:`!dataclass` will not implicitly add a :meth:`~object.__hash__`
      method unless it is safe to do so.  Neither will it add or change an
      existing explicitly defined :meth:`!__hash__` method.  Setting the class
      attribute ``__hash__ = None`` has a specific meaning to Python, as
      described in the :meth:`!__hash__` documentation.
 
      If :meth:`!__hash__` is not explicitly defined, or if it is set to ``None``,
-     then ``@dataclass`` *may* add an implicit :meth:`!__hash__` method.
-     Although not recommended, you can force ``@dataclass`` to create a
+     then :deco:`!dataclass` *may* add an implicit :meth:`!__hash__` method.
+     Although not recommended, you can force :deco:`!dataclass` to create a
      :meth:`!__hash__` method with ``unsafe_hash=True``. This might be the case
      if your class is logically immutable but can still be mutated.
      This is a specialized use case and should be considered carefully.
@@ -149,7 +149,7 @@ Module contents
      method in your dataclass and set ``unsafe_hash=True``; this will result
      in a :exc:`TypeError`.
 
-     If *eq* and *frozen* are both true, by default ``@dataclass`` will
+     If *eq* and *frozen* are both true, by default :deco:`!dataclass` will
      generate a :meth:`!__hash__` method for you.  If *eq* is true and
      *frozen* is false, :meth:`!__hash__` will be set to ``None``, marking it
      unhashable (which it is, since it is mutable).  If *eq* is false,
@@ -299,7 +299,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::
@@ -400,15 +400,15 @@ 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.
    By default, it is set to the module name of the caller.
 
    This function is not strictly required, because any Python
    mechanism for creating a new class with :attr:`!__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::
 
@@ -534,7 +534,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::
@@ -564,7 +564,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
@@ -577,7 +577,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 ``dataclasses.InitVar``.  If a field
 is an ``InitVar``, it is considered a pseudo-field called an init-only
@@ -611,7 +611,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.
@@ -627,7 +627,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.
@@ -751,7 +751,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.
@@ -785,7 +785,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