.. 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.
.. 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.
: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::
: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.
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::
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::
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
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
----------------
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.
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.
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.
: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
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::
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
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.
---------
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
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:
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.
.. 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.
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
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`.
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.
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__*
.. 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.
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.
.. 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.
.. 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.
..
.. 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
.. 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
.. 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.
projects / thirdparty / Python / cpython.git / commitdiff
