You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1746 lines
55 KiB
1746 lines
55 KiB
========================================
|
|
:mod:`typing` --- Support for type hints
|
|
========================================
|
|
|
|
.. module:: typing
|
|
:synopsis: Support for type hints (see :pep:`484`).
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
**Source code:** :source:`Lib/typing.py`
|
|
|
|
.. note::
|
|
|
|
The Python runtime does not enforce function and variable type annotations.
|
|
They can be used by third party tools such as type checkers, IDEs, linters,
|
|
etc.
|
|
|
|
--------------
|
|
|
|
This module provides runtime support for type hints as specified by
|
|
:pep:`484`, :pep:`526`, :pep:`544`, :pep:`586`, :pep:`589`, and :pep:`591`.
|
|
The most fundamental support consists of the types :data:`Any`, :data:`Union`,
|
|
:data:`Tuple`, :data:`Callable`, :class:`TypeVar`, and
|
|
:class:`Generic`. For full specification please see :pep:`484`. For
|
|
a simplified introduction to type hints see :pep:`483`.
|
|
|
|
|
|
The function below takes and returns a string and is annotated as follows::
|
|
|
|
def greeting(name: str) -> str:
|
|
return 'Hello ' + name
|
|
|
|
In the function ``greeting``, the argument ``name`` is expected to be of type
|
|
:class:`str` and the return type :class:`str`. Subtypes are accepted as
|
|
arguments.
|
|
|
|
Type aliases
|
|
============
|
|
|
|
A type alias is defined by assigning the type to the alias. In this example,
|
|
``Vector`` and ``list[float]`` will be treated as interchangeable synonyms::
|
|
|
|
Vector = list[float]
|
|
|
|
def scale(scalar: float, vector: Vector) -> Vector:
|
|
return [scalar * num for num in vector]
|
|
|
|
# typechecks; a list of floats qualifies as a Vector.
|
|
new_vector = scale(2.0, [1.0, -4.2, 5.4])
|
|
|
|
Type aliases are useful for simplifying complex type signatures. For example::
|
|
|
|
from collections.abc import Sequence
|
|
|
|
ConnectionOptions = dict[str, str]
|
|
Address = tuple[str, int]
|
|
Server = tuple[Address, ConnectionOptions]
|
|
|
|
def broadcast_message(message: str, servers: Sequence[Server]) -> None:
|
|
...
|
|
|
|
# The static type checker will treat the previous type signature as
|
|
# being exactly equivalent to this one.
|
|
def broadcast_message(
|
|
message: str,
|
|
servers: Sequence[tuple[tuple[str, int], dict[str, str]]]) -> None:
|
|
...
|
|
|
|
Note that ``None`` as a type hint is a special case and is replaced by
|
|
``type(None)``.
|
|
|
|
.. _distinct:
|
|
|
|
NewType
|
|
=======
|
|
|
|
Use the :func:`NewType` helper function to create distinct types::
|
|
|
|
from typing import NewType
|
|
|
|
UserId = NewType('UserId', int)
|
|
some_id = UserId(524313)
|
|
|
|
The static type checker will treat the new type as if it were a subclass
|
|
of the original type. This is useful in helping catch logical errors::
|
|
|
|
def get_user_name(user_id: UserId) -> str:
|
|
...
|
|
|
|
# typechecks
|
|
user_a = get_user_name(UserId(42351))
|
|
|
|
# does not typecheck; an int is not a UserId
|
|
user_b = get_user_name(-1)
|
|
|
|
You may still perform all ``int`` operations on a variable of type ``UserId``,
|
|
but the result will always be of type ``int``. This lets you pass in a
|
|
``UserId`` wherever an ``int`` might be expected, but will prevent you from
|
|
accidentally creating a ``UserId`` in an invalid way::
|
|
|
|
# 'output' is of type 'int', not 'UserId'
|
|
output = UserId(23413) + UserId(54341)
|
|
|
|
Note that these checks are enforced only by the static type checker. At runtime,
|
|
the statement ``Derived = NewType('Derived', Base)`` will make ``Derived`` a
|
|
function that immediately returns whatever parameter you pass it. That means
|
|
the expression ``Derived(some_value)`` does not create a new class or introduce
|
|
any overhead beyond that of a regular function call.
|
|
|
|
More precisely, the expression ``some_value is Derived(some_value)`` is always
|
|
true at runtime.
|
|
|
|
This also means that it is not possible to create a subtype of ``Derived``
|
|
since it is an identity function at runtime, not an actual type::
|
|
|
|
from typing import NewType
|
|
|
|
UserId = NewType('UserId', int)
|
|
|
|
# Fails at runtime and does not typecheck
|
|
class AdminUserId(UserId): pass
|
|
|
|
However, it is possible to create a :func:`NewType` based on a 'derived' ``NewType``::
|
|
|
|
from typing import NewType
|
|
|
|
UserId = NewType('UserId', int)
|
|
|
|
ProUserId = NewType('ProUserId', UserId)
|
|
|
|
and typechecking for ``ProUserId`` will work as expected.
|
|
|
|
See :pep:`484` for more details.
|
|
|
|
.. note::
|
|
|
|
Recall that the use of a type alias declares two types to be *equivalent* to
|
|
one another. Doing ``Alias = Original`` will make the static type checker
|
|
treat ``Alias`` as being *exactly equivalent* to ``Original`` in all cases.
|
|
This is useful when you want to simplify complex type signatures.
|
|
|
|
In contrast, ``NewType`` declares one type to be a *subtype* of another.
|
|
Doing ``Derived = NewType('Derived', Original)`` will make the static type
|
|
checker treat ``Derived`` as a *subclass* of ``Original``, which means a
|
|
value of type ``Original`` cannot be used in places where a value of type
|
|
``Derived`` is expected. This is useful when you want to prevent logic
|
|
errors with minimal runtime cost.
|
|
|
|
.. versionadded:: 3.5.2
|
|
|
|
Callable
|
|
========
|
|
|
|
Frameworks expecting callback functions of specific signatures might be
|
|
type hinted using ``Callable[[Arg1Type, Arg2Type], ReturnType]``.
|
|
|
|
For example::
|
|
|
|
from collections.abc import Callable
|
|
|
|
def feeder(get_next_item: Callable[[], str]) -> None:
|
|
# Body
|
|
|
|
def async_query(on_success: Callable[[int], None],
|
|
on_error: Callable[[int, Exception], None]) -> None:
|
|
# Body
|
|
|
|
It is possible to declare the return type of a callable without specifying
|
|
the call signature by substituting a literal ellipsis
|
|
for the list of arguments in the type hint: ``Callable[..., ReturnType]``.
|
|
|
|
.. _generics:
|
|
|
|
Generics
|
|
========
|
|
|
|
Since type information about objects kept in containers cannot be statically
|
|
inferred in a generic way, abstract base classes have been extended to support
|
|
subscription to denote expected types for container elements.
|
|
|
|
::
|
|
|
|
from collections.abc import Mapping, Sequence
|
|
|
|
def notify_by_email(employees: Sequence[Employee],
|
|
overrides: Mapping[str, str]) -> None: ...
|
|
|
|
Generics can be parameterized by using a new factory available in typing
|
|
called :class:`TypeVar`.
|
|
|
|
::
|
|
|
|
from collections.abc import Sequence
|
|
from typing import TypeVar
|
|
|
|
T = TypeVar('T') # Declare type variable
|
|
|
|
def first(l: Sequence[T]) -> T: # Generic function
|
|
return l[0]
|
|
|
|
|
|
User-defined generic types
|
|
==========================
|
|
|
|
A user-defined class can be defined as a generic class.
|
|
|
|
::
|
|
|
|
from typing import TypeVar, Generic
|
|
from logging import Logger
|
|
|
|
T = TypeVar('T')
|
|
|
|
class LoggedVar(Generic[T]):
|
|
def __init__(self, value: T, name: str, logger: Logger) -> None:
|
|
self.name = name
|
|
self.logger = logger
|
|
self.value = value
|
|
|
|
def set(self, new: T) -> None:
|
|
self.log('Set ' + repr(self.value))
|
|
self.value = new
|
|
|
|
def get(self) -> T:
|
|
self.log('Get ' + repr(self.value))
|
|
return self.value
|
|
|
|
def log(self, message: str) -> None:
|
|
self.logger.info('%s: %s', self.name, message)
|
|
|
|
``Generic[T]`` as a base class defines that the class ``LoggedVar`` takes a
|
|
single type parameter ``T`` . This also makes ``T`` valid as a type within the
|
|
class body.
|
|
|
|
The :class:`Generic` base class defines :meth:`__class_getitem__` so that
|
|
``LoggedVar[t]`` is valid as a type::
|
|
|
|
from collections.abc import Iterable
|
|
|
|
def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
|
|
for var in vars:
|
|
var.set(0)
|
|
|
|
A generic type can have any number of type variables, and type variables may
|
|
be constrained::
|
|
|
|
from typing import TypeVar, Generic
|
|
...
|
|
|
|
T = TypeVar('T')
|
|
S = TypeVar('S', int, str)
|
|
|
|
class StrangePair(Generic[T, S]):
|
|
...
|
|
|
|
Each type variable argument to :class:`Generic` must be distinct.
|
|
This is thus invalid::
|
|
|
|
from typing import TypeVar, Generic
|
|
...
|
|
|
|
T = TypeVar('T')
|
|
|
|
class Pair(Generic[T, T]): # INVALID
|
|
...
|
|
|
|
You can use multiple inheritance with :class:`Generic`::
|
|
|
|
from collections.abc import Sized
|
|
from typing import TypeVar, Generic
|
|
|
|
T = TypeVar('T')
|
|
|
|
class LinkedList(Sized, Generic[T]):
|
|
...
|
|
|
|
When inheriting from generic classes, some type variables could be fixed::
|
|
|
|
from collections.abc import Mapping
|
|
from typing import TypeVar
|
|
|
|
T = TypeVar('T')
|
|
|
|
class MyDict(Mapping[str, T]):
|
|
...
|
|
|
|
In this case ``MyDict`` has a single parameter, ``T``.
|
|
|
|
Using a generic class without specifying type parameters assumes
|
|
:data:`Any` for each position. In the following example, ``MyIterable`` is
|
|
not generic but implicitly inherits from ``Iterable[Any]``::
|
|
|
|
from collections.abc import Iterable
|
|
|
|
class MyIterable(Iterable): # Same as Iterable[Any]
|
|
|
|
User defined generic type aliases are also supported. Examples::
|
|
|
|
from collections.abc import Iterable
|
|
from typing import TypeVar, Union
|
|
S = TypeVar('S')
|
|
Response = Union[Iterable[S], int]
|
|
|
|
# Return type here is same as Union[Iterable[str], int]
|
|
def response(query: str) -> Response[str]:
|
|
...
|
|
|
|
T = TypeVar('T', int, float, complex)
|
|
Vec = Iterable[tuple[T, T]]
|
|
|
|
def inproduct(v: Vec[T]) -> T: # Same as Iterable[tuple[T, T]]
|
|
return sum(x*y for x, y in v)
|
|
|
|
.. versionchanged:: 3.7
|
|
:class:`Generic` no longer has a custom metaclass.
|
|
|
|
A user-defined generic class can have ABCs as base classes without a metaclass
|
|
conflict. Generic metaclasses are not supported. The outcome of parameterizing
|
|
generics is cached, and most types in the typing module are hashable and
|
|
comparable for equality.
|
|
|
|
|
|
The :data:`Any` type
|
|
====================
|
|
|
|
A special kind of type is :data:`Any`. A static type checker will treat
|
|
every type as being compatible with :data:`Any` and :data:`Any` as being
|
|
compatible with every type.
|
|
|
|
This means that it is possible to perform any operation or method call on a
|
|
value of type :data:`Any` and assign it to any variable::
|
|
|
|
from typing import Any
|
|
|
|
a = None # type: Any
|
|
a = [] # OK
|
|
a = 2 # OK
|
|
|
|
s = '' # type: str
|
|
s = a # OK
|
|
|
|
def foo(item: Any) -> int:
|
|
# Typechecks; 'item' could be any type,
|
|
# and that type might have a 'bar' method
|
|
item.bar()
|
|
...
|
|
|
|
Notice that no typechecking is performed when assigning a value of type
|
|
:data:`Any` to a more precise type. For example, the static type checker did
|
|
not report an error when assigning ``a`` to ``s`` even though ``s`` was
|
|
declared to be of type :class:`str` and receives an :class:`int` value at
|
|
runtime!
|
|
|
|
Furthermore, all functions without a return type or parameter types will
|
|
implicitly default to using :data:`Any`::
|
|
|
|
def legacy_parser(text):
|
|
...
|
|
return data
|
|
|
|
# A static type checker will treat the above
|
|
# as having the same signature as:
|
|
def legacy_parser(text: Any) -> Any:
|
|
...
|
|
return data
|
|
|
|
This behavior allows :data:`Any` to be used as an *escape hatch* when you
|
|
need to mix dynamically and statically typed code.
|
|
|
|
Contrast the behavior of :data:`Any` with the behavior of :class:`object`.
|
|
Similar to :data:`Any`, every type is a subtype of :class:`object`. However,
|
|
unlike :data:`Any`, the reverse is not true: :class:`object` is *not* a
|
|
subtype of every other type.
|
|
|
|
That means when the type of a value is :class:`object`, a type checker will
|
|
reject almost all operations on it, and assigning it to a variable (or using
|
|
it as a return value) of a more specialized type is a type error. For example::
|
|
|
|
def hash_a(item: object) -> int:
|
|
# Fails; an object does not have a 'magic' method.
|
|
item.magic()
|
|
...
|
|
|
|
def hash_b(item: Any) -> int:
|
|
# Typechecks
|
|
item.magic()
|
|
...
|
|
|
|
# Typechecks, since ints and strs are subclasses of object
|
|
hash_a(42)
|
|
hash_a("foo")
|
|
|
|
# Typechecks, since Any is compatible with all types
|
|
hash_b(42)
|
|
hash_b("foo")
|
|
|
|
Use :class:`object` to indicate that a value could be any type in a typesafe
|
|
manner. Use :data:`Any` to indicate that a value is dynamically typed.
|
|
|
|
|
|
Nominal vs structural subtyping
|
|
===============================
|
|
|
|
Initially :pep:`484` defined 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``.
|
|
|
|
This requirement previously also applied to abstract base classes, such as
|
|
:class:`~collections.abc.Iterable`. The problem with this approach is that a class had
|
|
to be explicitly marked to support them, which is unpythonic and unlike
|
|
what one would normally do in idiomatic dynamically typed Python code.
|
|
For example, this conforms to :pep:`484`::
|
|
|
|
from collections.abc import Sized, Iterable, Iterator
|
|
|
|
class Bucket(Sized, Iterable[int]):
|
|
...
|
|
def __len__(self) -> int: ...
|
|
def __iter__(self) -> Iterator[int]: ...
|
|
|
|
:pep:`544` allows to solve this problem by allowing users to write
|
|
the above code without explicit base classes in the class definition,
|
|
allowing ``Bucket`` to be implicitly considered a subtype of both ``Sized``
|
|
and ``Iterable[int]`` by static type checkers. This is known as
|
|
*structural subtyping* (or static duck-typing)::
|
|
|
|
from collections.abc import Iterator, Iterable
|
|
|
|
class Bucket: # Note: no base classes
|
|
...
|
|
def __len__(self) -> int: ...
|
|
def __iter__(self) -> Iterator[int]: ...
|
|
|
|
def collect(items: Iterable[int]) -> int: ...
|
|
result = collect(Bucket()) # Passes type check
|
|
|
|
Moreover, by subclassing a special class :class:`Protocol`, a user
|
|
can define new custom protocols to fully enjoy structural subtyping
|
|
(see examples below).
|
|
|
|
Module contents
|
|
===============
|
|
|
|
The module defines the following classes, functions and decorators.
|
|
|
|
.. note::
|
|
|
|
This module defines several types that are subclasses of pre-existing
|
|
standard library classes which also extend :class:`Generic`
|
|
to support type variables inside ``[]``.
|
|
These types became redundant in Python 3.9 when the
|
|
corresponding pre-existing classes were enhanced to support ``[]``.
|
|
|
|
The redundant types are deprecated as of Python 3.9 but no
|
|
deprecation warnings will be issued by the interpreter.
|
|
It is expected that type checkers will flag the deprecated types
|
|
when the checked program targets Python 3.9 or newer.
|
|
|
|
The deprecated types will be removed from the :mod:`typing` module
|
|
in the first Python version released 5 years after the release of Python 3.9.0.
|
|
See details in :pep:`585`—*Type Hinting Generics In Standard Collections*.
|
|
|
|
|
|
Special typing primitives
|
|
-------------------------
|
|
|
|
Special types
|
|
"""""""""""""
|
|
|
|
These can be used as types in annotations and do not support ``[]``.
|
|
|
|
.. data:: Any
|
|
|
|
Special type indicating an unconstrained type.
|
|
|
|
* Every type is compatible with :data:`Any`.
|
|
* :data:`Any` is compatible with every type.
|
|
|
|
.. data:: NoReturn
|
|
|
|
Special type indicating that a function never returns.
|
|
For example::
|
|
|
|
from typing import NoReturn
|
|
|
|
def stop() -> NoReturn:
|
|
raise RuntimeError('no way')
|
|
|
|
.. versionadded:: 3.5.4
|
|
.. versionadded:: 3.6.2
|
|
|
|
Special forms
|
|
"""""""""""""
|
|
|
|
These can be used as types in annotations using ``[]``, each having a unique syntax.
|
|
|
|
.. data:: Tuple
|
|
|
|
Tuple type; ``Tuple[X, Y]`` is the type of a tuple of two items
|
|
with the first item of type X and the second of type Y. The type of
|
|
the empty tuple can be written as ``Tuple[()]``.
|
|
|
|
Example: ``Tuple[T1, T2]`` is a tuple of two elements corresponding
|
|
to type variables T1 and T2. ``Tuple[int, float, str]`` is a tuple
|
|
of an int, a float and a string.
|
|
|
|
To specify a variable-length tuple of homogeneous type,
|
|
use literal ellipsis, e.g. ``Tuple[int, ...]``. A plain :data:`Tuple`
|
|
is equivalent to ``Tuple[Any, ...]``, and in turn to :class:`tuple`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`builtins.tuple <tuple>` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. data:: Union
|
|
|
|
Union type; ``Union[X, Y]`` means either X or Y.
|
|
|
|
To define a union, use e.g. ``Union[int, str]``. Details:
|
|
|
|
* The arguments must be types and there must be at least one.
|
|
|
|
* Unions of unions are flattened, e.g.::
|
|
|
|
Union[Union[int, str], float] == Union[int, str, float]
|
|
|
|
* Unions of a single argument vanish, e.g.::
|
|
|
|
Union[int] == int # The constructor actually returns int
|
|
|
|
* Redundant arguments are skipped, e.g.::
|
|
|
|
Union[int, str, int] == Union[int, str]
|
|
|
|
* When comparing unions, the argument order is ignored, e.g.::
|
|
|
|
Union[int, str] == Union[str, int]
|
|
|
|
* You cannot subclass or instantiate a union.
|
|
|
|
* You cannot write ``Union[X][Y]``.
|
|
|
|
* You can use ``Optional[X]`` as a shorthand for ``Union[X, None]``.
|
|
|
|
.. versionchanged:: 3.7
|
|
Don't remove explicit subclasses from unions at runtime.
|
|
|
|
.. data:: Optional
|
|
|
|
Optional type.
|
|
|
|
``Optional[X]`` is equivalent to ``Union[X, None]``.
|
|
|
|
Note that this is not the same concept as an optional argument,
|
|
which is one that has a default. An optional argument with a
|
|
default does not require the ``Optional`` qualifier on its type
|
|
annotation just because it is optional. For example::
|
|
|
|
def foo(arg: int = 0) -> None:
|
|
...
|
|
|
|
On the other hand, if an explicit value of ``None`` is allowed, the
|
|
use of ``Optional`` is appropriate, whether the argument is optional
|
|
or not. For example::
|
|
|
|
def foo(arg: Optional[int] = None) -> None:
|
|
...
|
|
|
|
.. data:: Callable
|
|
|
|
Callable type; ``Callable[[int], str]`` is a function of (int) -> str.
|
|
|
|
The subscription syntax must always be used with exactly two
|
|
values: the argument list and the return type. The argument list
|
|
must be a list of types or an ellipsis; the return type must be
|
|
a single type.
|
|
|
|
There is no syntax to indicate optional or keyword arguments;
|
|
such function types are rarely used as callback types.
|
|
``Callable[..., ReturnType]`` (literal ellipsis) can be used to
|
|
type hint a callable taking any number of arguments and returning
|
|
``ReturnType``. A plain :data:`Callable` is equivalent to
|
|
``Callable[..., Any]``, and in turn to
|
|
:class:`collections.abc.Callable`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Callable` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. class:: Type(Generic[CT_co])
|
|
|
|
A variable annotated with ``C`` may accept a value of type ``C``. In
|
|
contrast, a variable annotated with ``Type[C]`` may accept values that are
|
|
classes themselves -- specifically, it will accept the *class object* of
|
|
``C``. For example::
|
|
|
|
a = 3 # Has type 'int'
|
|
b = int # Has type 'Type[int]'
|
|
c = type(a) # Also has type 'Type[int]'
|
|
|
|
Note that ``Type[C]`` is covariant::
|
|
|
|
class User: ...
|
|
class BasicUser(User): ...
|
|
class ProUser(User): ...
|
|
class TeamUser(User): ...
|
|
|
|
# Accepts User, BasicUser, ProUser, TeamUser, ...
|
|
def make_new_user(user_class: Type[User]) -> User:
|
|
# ...
|
|
return user_class()
|
|
|
|
The fact that ``Type[C]`` is covariant implies that all subclasses of
|
|
``C`` should implement the same constructor signature and class method
|
|
signatures as ``C``. The type checker should flag violations of this,
|
|
but should also allow constructor calls in subclasses that match the
|
|
constructor calls in the indicated base class. How the type checker is
|
|
required to handle this particular case may change in future revisions of
|
|
:pep:`484`.
|
|
|
|
The only legal parameters for :class:`Type` are classes, :data:`Any`,
|
|
:ref:`type variables <generics>`, and unions of any of these types.
|
|
For example::
|
|
|
|
def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]): ...
|
|
|
|
``Type[Any]`` is equivalent to ``Type`` which in turn is equivalent
|
|
to ``type``, which is the root of Python's metaclass hierarchy.
|
|
|
|
.. versionadded:: 3.5.2
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`builtins.type <type>` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. data:: Literal
|
|
|
|
A type that can be used to indicate to type checkers that the
|
|
corresponding variable or function parameter has a value equivalent to
|
|
the provided literal (or one of several literals). For example::
|
|
|
|
def validate_simple(data: Any) -> Literal[True]: # always returns True
|
|
...
|
|
|
|
MODE = Literal['r', 'rb', 'w', 'wb']
|
|
def open_helper(file: str, mode: MODE) -> str:
|
|
...
|
|
|
|
open_helper('/some/path', 'r') # Passes type check
|
|
open_helper('/other/path', 'typo') # Error in type checker
|
|
|
|
``Literal[...]`` cannot be subclassed. At runtime, an arbitrary value
|
|
is allowed as type argument to ``Literal[...]``, but type checkers may
|
|
impose restrictions. See :pep:`586` for more details about literal types.
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
.. versionchanged:: 3.9.1
|
|
``Literal`` now de-duplicates parameters. Equality comparison of
|
|
``Literal`` objects are no longer order dependent. ``Literal`` objects
|
|
will now raise a :exc:`TypeError` exception during equality comparisons
|
|
if one of their parameters are not :term:`immutable`.
|
|
|
|
.. data:: ClassVar
|
|
|
|
Special type construct to mark class variables.
|
|
|
|
As introduced in :pep:`526`, a variable annotation wrapped in ClassVar
|
|
indicates that a given attribute is intended to be used as a class variable
|
|
and should not be set on instances of that class. Usage::
|
|
|
|
class Starship:
|
|
stats: ClassVar[dict[str, int]] = {} # class variable
|
|
damage: int = 10 # instance variable
|
|
|
|
:data:`ClassVar` accepts only types and cannot be further subscribed.
|
|
|
|
:data:`ClassVar` is not a class itself, and should not
|
|
be used with :func:`isinstance` or :func:`issubclass`.
|
|
:data:`ClassVar` does not change Python runtime behavior, but
|
|
it can be used by third-party type checkers. For example, a type checker
|
|
might flag the following code as an error::
|
|
|
|
enterprise_d = Starship(3000)
|
|
enterprise_d.stats = {} # Error, setting class variable on instance
|
|
Starship.stats = {} # This is OK
|
|
|
|
.. versionadded:: 3.5.3
|
|
|
|
.. data:: Final
|
|
|
|
A special typing construct to indicate to type checkers that a name
|
|
cannot be re-assigned or overridden in a subclass. For example::
|
|
|
|
MAX_SIZE: Final = 9000
|
|
MAX_SIZE += 1 # Error reported by type checker
|
|
|
|
class Connection:
|
|
TIMEOUT: Final[int] = 10
|
|
|
|
class FastConnector(Connection):
|
|
TIMEOUT = 1 # Error reported by type checker
|
|
|
|
There is no runtime checking of these properties. See :pep:`591` for
|
|
more details.
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
.. data:: Annotated
|
|
|
|
A type, introduced in :pep:`593` (``Flexible function and variable
|
|
annotations``), to decorate existing types with context-specific metadata
|
|
(possibly multiple pieces of it, as ``Annotated`` is variadic).
|
|
Specifically, a type ``T`` can be annotated with metadata ``x`` via the
|
|
typehint ``Annotated[T, x]``. This metadata can be used for either static
|
|
analysis or at runtime. If a library (or tool) encounters a typehint
|
|
``Annotated[T, x]`` and has no special logic for metadata ``x``, it
|
|
should ignore it and simply treat the type as ``T``. Unlike the
|
|
``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``)
|
|
together with runtime access to ``x`` within a specific application.
|
|
|
|
Ultimately, the responsibility of how to interpret the annotations (if
|
|
at all) is the responsibility of the tool or library encountering the
|
|
``Annotated`` type. A tool or library encountering an ``Annotated`` type
|
|
can scan through the annotations to determine if they are of interest
|
|
(e.g., using ``isinstance()``).
|
|
|
|
When a tool or a library does not support annotations or encounters an
|
|
unknown annotation it should just ignore it and treat annotated type as
|
|
the underlying type.
|
|
|
|
It's up to the tool consuming the annotations to decide whether the
|
|
client is allowed to have several annotations on one type and how to
|
|
merge those annotations.
|
|
|
|
Since the ``Annotated`` type allows you to put several annotations of
|
|
the same (or different) type(s) on any node, the tools or libraries
|
|
consuming those annotations are in charge of dealing with potential
|
|
duplicates. For example, if you are doing value range analysis you might
|
|
allow this::
|
|
|
|
T1 = Annotated[int, ValueRange(-10, 5)]
|
|
T2 = Annotated[T1, ValueRange(-20, 3)]
|
|
|
|
Passing ``include_extras=True`` to :func:`get_type_hints` lets one
|
|
access the extra annotations at runtime.
|
|
|
|
The details of the syntax:
|
|
|
|
* The first argument to ``Annotated`` must be a valid type
|
|
|
|
* Multiple type annotations are supported (``Annotated`` supports variadic
|
|
arguments)::
|
|
|
|
Annotated[int, ValueRange(3, 10), ctype("char")]
|
|
|
|
* ``Annotated`` must be called with at least two arguments (
|
|
``Annotated[int]`` is not valid)
|
|
|
|
* The order of the annotations is preserved and matters for equality
|
|
checks::
|
|
|
|
Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
|
|
int, ctype("char"), ValueRange(3, 10)
|
|
]
|
|
|
|
* Nested ``Annotated`` types are flattened, with metadata ordered
|
|
starting with the innermost annotation::
|
|
|
|
Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
|
|
int, ValueRange(3, 10), ctype("char")
|
|
]
|
|
|
|
* Duplicated annotations are not removed::
|
|
|
|
Annotated[int, ValueRange(3, 10)] != Annotated[
|
|
int, ValueRange(3, 10), ValueRange(3, 10)
|
|
]
|
|
|
|
* ``Annotated`` can be used with nested and generic aliases::
|
|
|
|
T = TypeVar('T')
|
|
Vec = Annotated[list[tuple[T, T]], MaxLen(10)]
|
|
V = Vec[int]
|
|
|
|
V == Annotated[list[tuple[int, int]], MaxLen(10)]
|
|
|
|
.. versionadded:: 3.9
|
|
|
|
Building generic types
|
|
""""""""""""""""""""""
|
|
|
|
These are not used in annotations. They are building blocks for creating generic types.
|
|
|
|
.. class:: Generic
|
|
|
|
Abstract base class for generic types.
|
|
|
|
A generic type is typically declared by inheriting from an
|
|
instantiation of this class with one or more type variables.
|
|
For example, a generic mapping type might be defined as::
|
|
|
|
class Mapping(Generic[KT, VT]):
|
|
def __getitem__(self, key: KT) -> VT:
|
|
...
|
|
# Etc.
|
|
|
|
This class can then be used as follows::
|
|
|
|
X = TypeVar('X')
|
|
Y = TypeVar('Y')
|
|
|
|
def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:
|
|
try:
|
|
return mapping[key]
|
|
except KeyError:
|
|
return default
|
|
|
|
.. class:: TypeVar
|
|
|
|
Type variable.
|
|
|
|
Usage::
|
|
|
|
T = TypeVar('T') # Can be anything
|
|
A = TypeVar('A', str, bytes) # Must be str or bytes
|
|
|
|
Type variables exist primarily for the benefit of static type
|
|
checkers. They serve as the parameters for generic types as well
|
|
as for generic function definitions. See :class:`Generic` for more
|
|
information on generic types. Generic functions work as follows::
|
|
|
|
def repeat(x: T, n: int) -> Sequence[T]:
|
|
"""Return a list containing n references to x."""
|
|
return [x]*n
|
|
|
|
def longest(x: A, y: A) -> A:
|
|
"""Return the longest of two strings."""
|
|
return x if len(x) >= len(y) else y
|
|
|
|
The latter example's signature is essentially the overloading
|
|
of ``(str, str) -> str`` and ``(bytes, bytes) -> bytes``. Also note
|
|
that if the arguments are instances of some subclass of :class:`str`,
|
|
the return type is still plain :class:`str`.
|
|
|
|
At runtime, ``isinstance(x, T)`` will raise :exc:`TypeError`. In general,
|
|
:func:`isinstance` and :func:`issubclass` should not be used with types.
|
|
|
|
Type variables may be marked covariant or contravariant by passing
|
|
``covariant=True`` or ``contravariant=True``. See :pep:`484` for more
|
|
details. By default type variables are invariant. Alternatively,
|
|
a type variable may specify an upper bound using ``bound=<type>``.
|
|
This means that an actual type substituted (explicitly or implicitly)
|
|
for the type variable must be a subclass of the boundary type,
|
|
see :pep:`484`.
|
|
|
|
.. data:: AnyStr
|
|
|
|
``AnyStr`` is a type variable defined as
|
|
``AnyStr = TypeVar('AnyStr', str, bytes)``.
|
|
|
|
It is meant to be used for functions that may accept any kind of string
|
|
without allowing different kinds of strings to mix. For example::
|
|
|
|
def concat(a: AnyStr, b: AnyStr) -> AnyStr:
|
|
return a + b
|
|
|
|
concat(u"foo", u"bar") # Ok, output has type 'unicode'
|
|
concat(b"foo", b"bar") # Ok, output has type 'bytes'
|
|
concat(u"foo", b"bar") # Error, cannot mix unicode and bytes
|
|
|
|
.. class:: Protocol(Generic)
|
|
|
|
Base class for protocol classes. Protocol classes are defined like this::
|
|
|
|
class Proto(Protocol):
|
|
def meth(self) -> int:
|
|
...
|
|
|
|
Such classes are primarily used with static type checkers that recognize
|
|
structural subtyping (static duck-typing), for example::
|
|
|
|
class C:
|
|
def meth(self) -> int:
|
|
return 0
|
|
|
|
def func(x: Proto) -> int:
|
|
return x.meth()
|
|
|
|
func(C()) # Passes static type check
|
|
|
|
See :pep:`544` for details. Protocol classes decorated with
|
|
:func:`runtime_checkable` (described later) act as simple-minded runtime
|
|
protocols that check only the presence of given attributes, ignoring their
|
|
type signatures.
|
|
|
|
Protocol classes can be generic, for example::
|
|
|
|
class GenProto(Protocol[T]):
|
|
def meth(self) -> T:
|
|
...
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
.. decorator:: runtime_checkable
|
|
|
|
Mark a protocol class as a runtime protocol.
|
|
|
|
Such a protocol can be used with :func:`isinstance` and :func:`issubclass`.
|
|
This raises :exc:`TypeError` when applied to a non-protocol class. This
|
|
allows a simple-minded structural check, very similar to "one trick ponies"
|
|
in :mod:`collections.abc` such as :class:`~collections.abc.Iterable`. For example::
|
|
|
|
@runtime_checkable
|
|
class Closable(Protocol):
|
|
def close(self): ...
|
|
|
|
assert isinstance(open('/some/file'), Closable)
|
|
|
|
.. note::
|
|
|
|
:func:`runtime_checkable` will check only the presence of the required methods,
|
|
not their type signatures! For example, :class:`builtins.complex <complex>`
|
|
implements :func:`__float__`, therefore it passes an :func:`issubclass` check
|
|
against :class:`SupportsFloat`. However, the ``complex.__float__`` method
|
|
exists only to raise a :class:`TypeError` with a more informative message.
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
Other special directives
|
|
""""""""""""""""""""""""
|
|
|
|
These are not used in annotations. They are building blocks for declaring types.
|
|
|
|
.. class:: NamedTuple
|
|
|
|
Typed version of :func:`collections.namedtuple`.
|
|
|
|
Usage::
|
|
|
|
class Employee(NamedTuple):
|
|
name: str
|
|
id: int
|
|
|
|
This is equivalent to::
|
|
|
|
Employee = collections.namedtuple('Employee', ['name', 'id'])
|
|
|
|
To give a field a default value, you can assign to it in the class body::
|
|
|
|
class Employee(NamedTuple):
|
|
name: str
|
|
id: int = 3
|
|
|
|
employee = Employee('Guido')
|
|
assert employee.id == 3
|
|
|
|
Fields with a default value must come after any fields without a default.
|
|
|
|
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
|
|
API.)
|
|
|
|
``NamedTuple`` subclasses can also have docstrings and methods::
|
|
|
|
class Employee(NamedTuple):
|
|
"""Represents an employee."""
|
|
name: str
|
|
id: int = 3
|
|
|
|
def __repr__(self) -> str:
|
|
return f'<Employee {self.name}, id={self.id}>'
|
|
|
|
Backward-compatible usage::
|
|
|
|
Employee = NamedTuple('Employee', [('name', str), ('id', int)])
|
|
|
|
.. versionchanged:: 3.6
|
|
Added support for :pep:`526` variable annotation syntax.
|
|
|
|
.. versionchanged:: 3.6.1
|
|
Added support for default values, methods, and docstrings.
|
|
|
|
.. versionchanged:: 3.8
|
|
The ``_field_types`` and ``__annotations__`` attributes are
|
|
now regular dictionaries instead of instances of ``OrderedDict``.
|
|
|
|
.. versionchanged:: 3.9
|
|
Removed the ``_field_types`` attribute in favor of the more
|
|
standard ``__annotations__`` attribute which has the same information.
|
|
|
|
.. function:: NewType(name, tp)
|
|
|
|
A helper function to indicate a distinct type to a typechecker,
|
|
see :ref:`distinct`. At runtime it returns a function that returns
|
|
its argument. Usage::
|
|
|
|
UserId = NewType('UserId', int)
|
|
first_user = UserId(1)
|
|
|
|
.. versionadded:: 3.5.2
|
|
|
|
.. class:: TypedDict(dict)
|
|
|
|
Special construct to add type hints to a dictionary.
|
|
At runtime it is a plain :class:`dict`.
|
|
|
|
``TypedDict`` declares a dictionary type that expects all of its
|
|
instances to have a certain set of keys, where each key is
|
|
associated with a value of a consistent type. This expectation
|
|
is not checked at runtime but is only enforced by type checkers.
|
|
Usage::
|
|
|
|
class Point2D(TypedDict):
|
|
x: int
|
|
y: int
|
|
label: str
|
|
|
|
a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK
|
|
b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check
|
|
|
|
assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
|
|
|
|
The type info for introspection can be accessed via ``Point2D.__annotations__``
|
|
and ``Point2D.__total__``. To allow using this feature with older versions
|
|
of Python that do not support :pep:`526`, ``TypedDict`` supports two additional
|
|
equivalent syntactic forms::
|
|
|
|
Point2D = TypedDict('Point2D', x=int, y=int, label=str)
|
|
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
|
|
|
|
By default, all keys must be present in a TypedDict. It is possible
|
|
to override this by specifying totality.
|
|
Usage::
|
|
|
|
class point2D(TypedDict, total=False):
|
|
x: int
|
|
y: int
|
|
|
|
This means that a point2D TypedDict can have any of the keys omitted. A type
|
|
checker is only expected to support a literal False or True as the value of
|
|
the total argument. True is the default, and makes all items defined in the
|
|
class body be required.
|
|
|
|
See :pep:`589` for more examples and detailed rules of using ``TypedDict``.
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
Generic concrete collections
|
|
----------------------------
|
|
|
|
Corresponding to built-in types
|
|
"""""""""""""""""""""""""""""""
|
|
|
|
.. class:: Dict(dict, MutableMapping[KT, VT])
|
|
|
|
A generic version of :class:`dict`.
|
|
Useful for annotating return types. To annotate arguments it is preferred
|
|
to use an abstract collection type such as :class:`Mapping`.
|
|
|
|
This type can be used as follows::
|
|
|
|
def count_words(text: str) -> Dict[str, int]:
|
|
...
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`builtins.dict <dict>` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. class:: List(list, MutableSequence[T])
|
|
|
|
Generic version of :class:`list`.
|
|
Useful for annotating return types. To annotate arguments it is preferred
|
|
to use an abstract collection type such as :class:`Sequence` or
|
|
:class:`Iterable`.
|
|
|
|
This type may be used as follows::
|
|
|
|
T = TypeVar('T', int, float)
|
|
|
|
def vec2(x: T, y: T) -> List[T]:
|
|
return [x, y]
|
|
|
|
def keep_positives(vector: Sequence[T]) -> List[T]:
|
|
return [item for item in vector if item > 0]
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`builtins.list <list>` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. class:: Set(set, MutableSet[T])
|
|
|
|
A generic version of :class:`builtins.set <set>`.
|
|
Useful for annotating return types. To annotate arguments it is preferred
|
|
to use an abstract collection type such as :class:`AbstractSet`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`builtins.set <set>` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. class:: FrozenSet(frozenset, AbstractSet[T_co])
|
|
|
|
A generic version of :class:`builtins.frozenset <frozenset>`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`builtins.frozenset <frozenset>` now supports ``[]``. See
|
|
:pep:`585` and :ref:`types-genericalias`.
|
|
|
|
.. note:: :data:`Tuple` is a special form.
|
|
|
|
Corresponding to types in :mod:`collections`
|
|
""""""""""""""""""""""""""""""""""""""""""""
|
|
|
|
.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT])
|
|
|
|
A generic version of :class:`collections.defaultdict`.
|
|
|
|
.. versionadded:: 3.5.2
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.defaultdict` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. class:: OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])
|
|
|
|
A generic version of :class:`collections.OrderedDict`.
|
|
|
|
.. versionadded:: 3.7.2
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.OrderedDict` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. class:: ChainMap(collections.ChainMap, MutableMapping[KT, VT])
|
|
|
|
A generic version of :class:`collections.ChainMap`.
|
|
|
|
.. versionadded:: 3.5.4
|
|
.. versionadded:: 3.6.1
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.ChainMap` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. class:: Counter(collections.Counter, Dict[T, int])
|
|
|
|
A generic version of :class:`collections.Counter`.
|
|
|
|
.. versionadded:: 3.5.4
|
|
.. versionadded:: 3.6.1
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.Counter` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. class:: Deque(deque, MutableSequence[T])
|
|
|
|
A generic version of :class:`collections.deque`.
|
|
|
|
.. versionadded:: 3.5.4
|
|
.. versionadded:: 3.6.1
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.deque` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
Other concrete types
|
|
""""""""""""""""""""
|
|
|
|
.. class:: IO
|
|
TextIO
|
|
BinaryIO
|
|
|
|
Generic type ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])``
|
|
and ``BinaryIO(IO[bytes])``
|
|
represent the types of I/O streams such as returned by
|
|
:func:`open`. These types are also in the ``typing.io`` namespace.
|
|
|
|
.. class:: Pattern
|
|
Match
|
|
|
|
These type aliases
|
|
correspond to the return types from :func:`re.compile` and
|
|
:func:`re.match`. These types (and the corresponding functions)
|
|
are generic in ``AnyStr`` and can be made specific by writing
|
|
``Pattern[str]``, ``Pattern[bytes]``, ``Match[str]``, or
|
|
``Match[bytes]``. These types are also in the ``typing.re`` namespace.
|
|
|
|
.. deprecated:: 3.9
|
|
Classes ``Pattern`` and ``Match`` from :mod:`re` now support ``[]``.
|
|
See :pep:`585` and :ref:`types-genericalias`.
|
|
|
|
.. class:: Text
|
|
|
|
``Text`` is an alias for ``str``. It is provided to supply a forward
|
|
compatible path for Python 2 code: in Python 2, ``Text`` is an alias for
|
|
``unicode``.
|
|
|
|
Use ``Text`` to indicate that a value must contain a unicode string in
|
|
a manner that is compatible with both Python 2 and Python 3::
|
|
|
|
def add_unicode_checkmark(text: Text) -> Text:
|
|
return text + u' \u2713'
|
|
|
|
.. versionadded:: 3.5.2
|
|
|
|
Abstract Base Classes
|
|
---------------------
|
|
|
|
Corresponding to collections in :mod:`collections.abc`
|
|
""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
|
|
.. class:: AbstractSet(Sized, Collection[T_co])
|
|
|
|
A generic version of :class:`collections.abc.Set`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Set` now supports ``[]``. See :pep:`585` and
|
|
:ref:`types-genericalias`.
|
|
|
|
.. class:: ByteString(Sequence[int])
|
|
|
|
A generic version of :class:`collections.abc.ByteString`.
|
|
|
|
This type represents the types :class:`bytes`, :class:`bytearray`,
|
|
and :class:`memoryview` of byte sequences.
|
|
|
|
As a shorthand for this type, :class:`bytes` can be used to
|
|
annotate arguments of any of the types mentioned above.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.ByteString` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: Collection(Sized, Iterable[T_co], Container[T_co])
|
|
|
|
A generic version of :class:`collections.abc.Collection`
|
|
|
|
.. versionadded:: 3.6.0
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Collection` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: Container(Generic[T_co])
|
|
|
|
A generic version of :class:`collections.abc.Container`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Container` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: ItemsView(MappingView, Generic[KT_co, VT_co])
|
|
|
|
A generic version of :class:`collections.abc.ItemsView`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.ItemsView` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: KeysView(MappingView[KT_co], AbstractSet[KT_co])
|
|
|
|
A generic version of :class:`collections.abc.KeysView`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.KeysView` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: Mapping(Sized, Collection[KT], Generic[VT_co])
|
|
|
|
A generic version of :class:`collections.abc.Mapping`.
|
|
This type can be used as follows::
|
|
|
|
def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:
|
|
return word_list[word]
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Mapping` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: MappingView(Sized, Iterable[T_co])
|
|
|
|
A generic version of :class:`collections.abc.MappingView`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.MappingView` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: MutableMapping(Mapping[KT, VT])
|
|
|
|
A generic version of :class:`collections.abc.MutableMapping`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.MutableMapping` now supports ``[]``. See
|
|
:pep:`585` and :ref:`types-genericalias`.
|
|
|
|
.. class:: MutableSequence(Sequence[T])
|
|
|
|
A generic version of :class:`collections.abc.MutableSequence`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.MutableSequence` now supports ``[]``. See
|
|
:pep:`585` and :ref:`types-genericalias`.
|
|
|
|
.. class:: MutableSet(AbstractSet[T])
|
|
|
|
A generic version of :class:`collections.abc.MutableSet`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.MutableSet` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: Sequence(Reversible[T_co], Collection[T_co])
|
|
|
|
A generic version of :class:`collections.abc.Sequence`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Sequence` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: ValuesView(MappingView[VT_co])
|
|
|
|
A generic version of :class:`collections.abc.ValuesView`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.ValuesView` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
Corresponding to other types in :mod:`collections.abc`
|
|
""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
|
|
.. class:: Iterable(Generic[T_co])
|
|
|
|
A generic version of :class:`collections.abc.Iterable`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Iterable` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: Iterator(Iterable[T_co])
|
|
|
|
A generic version of :class:`collections.abc.Iterator`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Iterator` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])
|
|
|
|
A generator can be annotated by the generic type
|
|
``Generator[YieldType, SendType, ReturnType]``. For example::
|
|
|
|
def echo_round() -> Generator[int, float, str]:
|
|
sent = yield 0
|
|
while sent >= 0:
|
|
sent = yield round(sent)
|
|
return 'Done'
|
|
|
|
Note that unlike many other generics in the typing module, the ``SendType``
|
|
of :class:`Generator` behaves contravariantly, not covariantly or
|
|
invariantly.
|
|
|
|
If your generator will only yield values, set the ``SendType`` and
|
|
``ReturnType`` to ``None``::
|
|
|
|
def infinite_stream(start: int) -> Generator[int, None, None]:
|
|
while True:
|
|
yield start
|
|
start += 1
|
|
|
|
Alternatively, annotate your generator as having a return type of
|
|
either ``Iterable[YieldType]`` or ``Iterator[YieldType]``::
|
|
|
|
def infinite_stream(start: int) -> Iterator[int]:
|
|
while True:
|
|
yield start
|
|
start += 1
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Generator` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: Hashable
|
|
|
|
An alias to :class:`collections.abc.Hashable`
|
|
|
|
.. class:: Reversible(Iterable[T_co])
|
|
|
|
A generic version of :class:`collections.abc.Reversible`.
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Reversible` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: Sized
|
|
|
|
An alias to :class:`collections.abc.Sized`
|
|
|
|
Asynchronous programming
|
|
""""""""""""""""""""""""
|
|
|
|
.. class:: Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co])
|
|
|
|
A generic version of :class:`collections.abc.Coroutine`.
|
|
The variance and order of type variables
|
|
correspond to those of :class:`Generator`, for example::
|
|
|
|
from collections.abc import Coroutine
|
|
c = None # type: Coroutine[list[str], str, int]
|
|
...
|
|
x = c.send('hi') # type: list[str]
|
|
async def bar() -> None:
|
|
x = await c # type: int
|
|
|
|
.. versionadded:: 3.5.3
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Coroutine` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])
|
|
|
|
An async generator can be annotated by the generic type
|
|
``AsyncGenerator[YieldType, SendType]``. For example::
|
|
|
|
async def echo_round() -> AsyncGenerator[int, float]:
|
|
sent = yield 0
|
|
while sent >= 0.0:
|
|
rounded = await round(sent)
|
|
sent = yield rounded
|
|
|
|
Unlike normal generators, async generators cannot return a value, so there
|
|
is no ``ReturnType`` type parameter. As with :class:`Generator`, the
|
|
``SendType`` behaves contravariantly.
|
|
|
|
If your generator will only yield values, set the ``SendType`` to
|
|
``None``::
|
|
|
|
async def infinite_stream(start: int) -> AsyncGenerator[int, None]:
|
|
while True:
|
|
yield start
|
|
start = await increment(start)
|
|
|
|
Alternatively, annotate your generator as having a return type of
|
|
either ``AsyncIterable[YieldType]`` or ``AsyncIterator[YieldType]``::
|
|
|
|
async def infinite_stream(start: int) -> AsyncIterator[int]:
|
|
while True:
|
|
yield start
|
|
start = await increment(start)
|
|
|
|
.. versionadded:: 3.6.1
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.AsyncGenerator` now supports ``[]``. See
|
|
:pep:`585` and :ref:`types-genericalias`.
|
|
|
|
.. class:: AsyncIterable(Generic[T_co])
|
|
|
|
A generic version of :class:`collections.abc.AsyncIterable`.
|
|
|
|
.. versionadded:: 3.5.2
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.AsyncIterable` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: AsyncIterator(AsyncIterable[T_co])
|
|
|
|
A generic version of :class:`collections.abc.AsyncIterator`.
|
|
|
|
.. versionadded:: 3.5.2
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.AsyncIterator` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
.. class:: Awaitable(Generic[T_co])
|
|
|
|
A generic version of :class:`collections.abc.Awaitable`.
|
|
|
|
.. versionadded:: 3.5.2
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`collections.abc.Awaitable` now supports ``[]``. See :pep:`585`
|
|
and :ref:`types-genericalias`.
|
|
|
|
|
|
Context manager types
|
|
"""""""""""""""""""""
|
|
|
|
.. class:: ContextManager(Generic[T_co])
|
|
|
|
A generic version of :class:`contextlib.AbstractContextManager`.
|
|
|
|
.. versionadded:: 3.5.4
|
|
.. versionadded:: 3.6.0
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`contextlib.AbstractContextManager` now supports ``[]``. See
|
|
:pep:`585` and :ref:`types-genericalias`.
|
|
|
|
.. class:: AsyncContextManager(Generic[T_co])
|
|
|
|
A generic version of :class:`contextlib.AbstractAsyncContextManager`.
|
|
|
|
.. versionadded:: 3.5.4
|
|
.. versionadded:: 3.6.2
|
|
|
|
.. deprecated:: 3.9
|
|
:class:`contextlib.AbstractAsyncContextManager` now supports ``[]``. See
|
|
:pep:`585` and :ref:`types-genericalias`.
|
|
|
|
Protocols
|
|
---------
|
|
|
|
These protocols are decorated with :func:`runtime_checkable`.
|
|
|
|
.. class:: SupportsAbs
|
|
|
|
An ABC with one abstract method ``__abs__`` that is covariant
|
|
in its return type.
|
|
|
|
.. class:: SupportsBytes
|
|
|
|
An ABC with one abstract method ``__bytes__``.
|
|
|
|
.. class:: SupportsComplex
|
|
|
|
An ABC with one abstract method ``__complex__``.
|
|
|
|
.. class:: SupportsFloat
|
|
|
|
An ABC with one abstract method ``__float__``.
|
|
|
|
.. class:: SupportsIndex
|
|
|
|
An ABC with one abstract method ``__index__``.
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
.. class:: SupportsInt
|
|
|
|
An ABC with one abstract method ``__int__``.
|
|
|
|
.. class:: SupportsRound
|
|
|
|
An ABC with one abstract method ``__round__``
|
|
that is covariant in its return type.
|
|
|
|
Functions and decorators
|
|
------------------------
|
|
|
|
.. function:: cast(typ, val)
|
|
|
|
Cast a value to a type.
|
|
|
|
This returns the value unchanged. To the type checker this
|
|
signals that the return value has the designated type, but at
|
|
runtime we intentionally don't check anything (we want this
|
|
to be as fast as possible).
|
|
|
|
.. decorator:: overload
|
|
|
|
The ``@overload`` decorator allows describing functions and methods
|
|
that support multiple different combinations of argument types. A series
|
|
of ``@overload``-decorated definitions must be followed by exactly one
|
|
non-``@overload``-decorated definition (for the same function/method).
|
|
The ``@overload``-decorated definitions are for the benefit of the
|
|
type checker only, since they will be overwritten by the
|
|
non-``@overload``-decorated definition, while the latter is used at
|
|
runtime but should be ignored by a type checker. At runtime, calling
|
|
a ``@overload``-decorated function directly will raise
|
|
:exc:`NotImplementedError`. An example of overload that gives a more
|
|
precise type than can be expressed using a union or a type variable::
|
|
|
|
@overload
|
|
def process(response: None) -> None:
|
|
...
|
|
@overload
|
|
def process(response: int) -> tuple[int, str]:
|
|
...
|
|
@overload
|
|
def process(response: bytes) -> str:
|
|
...
|
|
def process(response):
|
|
<actual implementation>
|
|
|
|
See :pep:`484` for details and comparison with other typing semantics.
|
|
|
|
.. decorator:: final
|
|
|
|
A decorator to indicate to type checkers that the decorated method
|
|
cannot be overridden, and the decorated class cannot be subclassed.
|
|
For example::
|
|
|
|
class Base:
|
|
@final
|
|
def done(self) -> None:
|
|
...
|
|
class Sub(Base):
|
|
def done(self) -> None: # Error reported by type checker
|
|
...
|
|
|
|
@final
|
|
class Leaf:
|
|
...
|
|
class Other(Leaf): # Error reported by type checker
|
|
...
|
|
|
|
There is no runtime checking of these properties. See :pep:`591` for
|
|
more details.
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
.. decorator:: no_type_check
|
|
|
|
Decorator to indicate that annotations are not type hints.
|
|
|
|
This works as class or function :term:`decorator`. With a class, it
|
|
applies recursively to all methods defined in that class (but not
|
|
to methods defined in its superclasses or subclasses).
|
|
|
|
This mutates the function(s) in place.
|
|
|
|
.. decorator:: no_type_check_decorator
|
|
|
|
Decorator to give another decorator the :func:`no_type_check` effect.
|
|
|
|
This wraps the decorator with something that wraps the decorated
|
|
function in :func:`no_type_check`.
|
|
|
|
.. decorator:: type_check_only
|
|
|
|
Decorator to mark a class or function to be unavailable at runtime.
|
|
|
|
This decorator is itself not available at runtime. It is mainly
|
|
intended to mark classes that are defined in type stub files if
|
|
an implementation returns an instance of a private class::
|
|
|
|
@type_check_only
|
|
class Response: # private or not available at runtime
|
|
code: int
|
|
def get_header(self, name: str) -> str: ...
|
|
|
|
def fetch_response() -> Response: ...
|
|
|
|
Note that returning instances of private classes is not recommended.
|
|
It is usually preferable to make such classes public.
|
|
|
|
Introspection helpers
|
|
---------------------
|
|
|
|
.. function:: get_type_hints(obj, globalns=None, localns=None, include_extras=False)
|
|
|
|
Return a dictionary containing type hints for a function, method, module
|
|
or class object.
|
|
|
|
This is often the same as ``obj.__annotations__``. In addition,
|
|
forward references encoded as string literals are handled by evaluating
|
|
them in ``globals`` and ``locals`` namespaces. If necessary,
|
|
``Optional[t]`` is added for function and method annotations if a default
|
|
value equal to ``None`` is set. For a class ``C``, return
|
|
a dictionary constructed by merging all the ``__annotations__`` along
|
|
``C.__mro__`` in reverse order.
|
|
|
|
The function recursively replaces all ``Annotated[T, ...]`` with ``T``,
|
|
unless ``include_extras`` is set to ``True`` (see :class:`Annotated` for
|
|
more information). For example::
|
|
|
|
class Student(NamedTuple):
|
|
name: Annotated[str, 'some marker']
|
|
|
|
get_type_hints(Student) == {'name': str}
|
|
get_type_hints(Student, include_extras=False) == {'name': str}
|
|
get_type_hints(Student, include_extras=True) == {
|
|
'name': Annotated[str, 'some marker']
|
|
}
|
|
|
|
.. versionchanged:: 3.9
|
|
Added ``include_extras`` parameter as part of :pep:`593`.
|
|
|
|
.. function:: get_args(tp)
|
|
.. function:: get_origin(tp)
|
|
|
|
Provide basic introspection for generic types and special typing forms.
|
|
|
|
For a typing object of the form ``X[Y, Z, ...]`` these functions return
|
|
``X`` and ``(Y, Z, ...)``. If ``X`` is a generic alias for a builtin or
|
|
:mod:`collections` class, it gets normalized to the original class.
|
|
If ``X`` is a :class:`Union` or :class:`Literal` contained in another
|
|
generic type, the order of ``(Y, Z, ...)`` may be different from the order
|
|
of the original arguments ``[Y, Z, ...]`` due to type caching.
|
|
For unsupported objects return ``None`` and ``()`` correspondingly.
|
|
Examples::
|
|
|
|
assert get_origin(Dict[str, int]) is dict
|
|
assert get_args(Dict[int, str]) == (int, str)
|
|
|
|
assert get_origin(Union[int, str]) is Union
|
|
assert get_args(Union[int, str]) == (int, str)
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
.. 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
|
|
a user, but may be used by introspection tools.
|
|
|
|
Constant
|
|
--------
|
|
|
|
.. data:: TYPE_CHECKING
|
|
|
|
A special constant that is assumed to be ``True`` by 3rd party static
|
|
type checkers. It is ``False`` at runtime. Usage::
|
|
|
|
if TYPE_CHECKING:
|
|
import expensive_mod
|
|
|
|
def fun(arg: 'expensive_mod.SomeType') -> None:
|
|
local_var: expensive_mod.AnotherType = other_fun()
|
|
|
|
The first type annotation must be enclosed in quotes, making it a
|
|
"forward reference", to hide the ``expensive_mod`` reference from the
|
|
interpreter runtime. Type annotations for local variables are not
|
|
evaluated, so the second annotation does not need to be enclosed in quotes.
|
|
|
|
.. 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.
|
|
(see :pep:`563`).
|
|
|
|
.. versionadded:: 3.5.2
|
|
|