NewType
=======
-Use the :class:`NewType` helper class to create distinct types::
+Use the :class:`NewType` helper to create distinct types::
from typing import NewType
Note that these checks are enforced only by the static type checker. At runtime,
the statement ``Derived = NewType('Derived', Base)`` will make ``Derived`` a
-class that immediately returns whatever parameter you pass it. That means
+callable that immediately returns whatever parameter you pass it. That means
the expression ``Derived(some_value)`` does not create a new class or introduce
much overhead beyond that of a regular function call.
See :pep:`612` for more information.
.. seealso::
- The documentation for :class:`ParamSpec` and :class:`Concatenate` provide
+ The documentation for :class:`ParamSpec` and :class:`Concatenate` provides
examples of usage in ``Callable``.
.. _generics:
Furthermore, a generic with only one parameter specification variable will accept
parameter lists in the forms ``X[[Type1, Type2, ...]]`` and also
``X[Type1, Type2, ...]`` for aesthetic reasons. Internally, the latter is converted
-to the former and are thus equivalent::
+to the former, so the following are equivalent::
>>> class X(Generic[P]): ...
...
Nominal vs structural subtyping
===============================
-Initially :pep:`484` defined Python static type system as using
+Initially :pep:`484` defined the Python static type system as using
*nominal subtyping*. This means that a class ``A`` is allowed where
a class ``B`` is expected if and only if ``A`` is a subclass of ``B``.
* Every type is compatible with :data:`Any`.
* :data:`Any` is compatible with every type.
- .. versionchanged:: 3.11
- :data:`Any` can now be used as a base class. This can be useful for
- avoiding type checker errors with classes that can duck type anywhere or
- are highly dynamic.
+ .. versionchanged:: 3.11
+ :data:`Any` can now be used as a base class. This can be useful for
+ avoiding type checker errors with classes that can duck type anywhere or
+ are highly dynamic.
.. data:: LiteralString
Other common use cases include:
- - :class:`classmethod`\s that are used as alternative constructors and return instances
- of the ``cls`` parameter.
- - Annotating an :meth:`object.__enter__` method which returns self.
+ - :class:`classmethod`\s that are used as alternative constructors and return instances
+ of the ``cls`` parameter.
+ - Annotating an :meth:`~object.__enter__` method which returns self.
For more information, see :pep:`673`.
def with_lock(f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
'''A type-safe decorator which provides a lock.'''
- global my_lock
def inner(*args: P.args, **kwargs: P.kwargs) -> R:
# Provide the lock as the first argument.
return f(my_lock, *args, **kwargs)
``no_type_check`` functionality that currently exists in the ``typing``
module which completely disables typechecking annotations on a function
or a class, the ``Annotated`` type allows for both static typechecking
- of ``T`` (e.g., via mypy or Pyre, which can safely ignore ``x``)
+ of ``T`` (which can safely ignore ``x``)
together with runtime access to ``x`` within a specific application.
Ultimately, the responsibility of how to interpret the annotations (if
2. If the return value is ``True``, the type of its argument
is the type inside ``TypeGuard``.
- For example::
+ For example::
def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
'''Determines whether all objects in the list are strings'''
.. class:: TypeVarTuple
- Type variable tuple. A specialized form of :class:`Type variable <TypeVar>`
+ Type variable tuple. A specialized form of :class:`type variable <TypeVar>`
that enables *variadic* generics.
A normal type variable enables parameterization with a single type. A type
use a :class:`TypeVar` with bound ``Callable[..., Any]``. However this
causes two problems:
- 1. The type checker can't type check the ``inner`` function because
- ``*args`` and ``**kwargs`` have to be typed :data:`Any`.
- 2. :func:`~cast` may be required in the body of the ``add_logging``
- decorator when returning the ``inner`` function, or the static type
- checker must be told to ignore the ``return inner``.
+ 1. The type checker can't type check the ``inner`` function because
+ ``*args`` and ``**kwargs`` have to be typed :data:`Any`.
+ 2. :func:`~cast` may be required in the body of the ``add_logging``
+ decorator when returning the ``inner`` function, or the static type
+ checker must be told to ignore the ``return inner``.
.. attribute:: args
.. attribute:: kwargs
The resulting class has an extra attribute ``__annotations__`` giving a
dict that maps the field names to the field types. (The field names are in
the ``_fields`` attribute and the default values are in the
- ``_field_defaults`` attribute both of which are part of the namedtuple
+ ``_field_defaults`` attribute, both of which are part of the :func:`~collections.namedtuple`
API.)
``NamedTuple`` subclasses can also have docstrings and methods::
in 3.13. It may also be unsupported by static type checkers.
The functional syntax should also be used when any of the keys are not valid
- :ref:`identifiers`, for example because they are keywords or contain hyphens.
+ :ref:`identifiers <identifiers>`, for example because they are keywords or contain hyphens.
Example::
# raises SyntaxError
y: int
z: int
- A ``TypedDict`` cannot inherit from a non-TypedDict class,
+ A ``TypedDict`` cannot inherit from a non-\ ``TypedDict`` class,
except for :class:`Generic`. For example::
class X(TypedDict):
.. class:: Hashable
- An alias to :class:`collections.abc.Hashable`
+ An alias to :class:`collections.abc.Hashable`.
.. class:: Reversible(Iterable[T_co])
.. class:: Sized
- An alias to :class:`collections.abc.Sized`
+ An alias to :class:`collections.abc.Sized`.
Asynchronous programming
""""""""""""""""""""""""
.. seealso::
`Unreachable Code and Exhaustiveness Checking
- <https://typing.readthedocs.io/en/latest/source/unreachable.html>_` has more
+ <https://typing.readthedocs.io/en/latest/source/unreachable.html>`__ has more
information about exhaustiveness checking with static typing.
.. versionadded:: 3.11
-.. function:: reveal_type(obj)
+.. function:: reveal_type(obj, /)
Reveal the inferred static type of an expression.
the documentation for :func:`@overload <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.
+ ``get_overloads()`` returns an empty sequence.
- ``get_overloads`` can be used for introspecting an overloaded function at
+ ``get_overloads()`` can be used for introspecting an overloaded function at
runtime.
.. versionadded:: 3.11
...
class Sub(Base):
def done(self) -> None: # Error reported by type checker
- ...
+ ...
@final
class Leaf:
.. class:: ForwardRef
A class used for internal typing representation of string forward references.
- For example, ``list["SomeClass"]`` is implicitly transformed into
- ``list[ForwardRef("SomeClass")]``. This class should not be instantiated by
+ For example, ``List["SomeClass"]`` is implicitly transformed into
+ ``List[ForwardRef("SomeClass")]``. This class should not be instantiated by
a user, but may be used by introspection tools.
.. note::
If ``from __future__ import annotations`` is used in Python 3.7 or later,
annotations are not evaluated at function definition time.
Instead, they are stored as strings in ``__annotations__``.
- This makes it unnecessary to use quotes around the annotation.
+ This makes it unnecessary to use quotes around the annotation
(see :pep:`563`).
.. versionadded:: 3.5.2
projects / thirdparty / Python / cpython.git / commitdiff
