typing — Поддержка подсказок типов

Специальные типы

Их можно использовать в качестве типов в аннотациях. Они не поддерживают подписку с помощью [].

typing.Any

Специальный тип, указывающий на не ограниченный тип.

• Каждый тип совместим с Any.
• Any совместим с каждым типом.

Изменено в версии 3.11: Any теперь можно использовать в качестве базового класса. Это может быть полезно для предотвращения ошибок проверки типов с классами, которые могут быть совместимы с любым типом или являются высокодинамичными.

typing.AnyStr

Переменная ограниченная переменная типа.

Определение:

AnyStr = TypeVar('AnyStr', str, bytes)

AnyStr предназначен для использования в функциях, которые могут принимать аргументы типа str или bytes, но не могут допускать их смешение.

Например:

def concat(a: AnyStr, b: AnyStr) -> AnyStr:
    return a + b

concat("foo", "bar")    # OK, output has type 'str'
concat(b"foo", b"bar")  # OK, output has type 'bytes'
concat("foo", b"bar")   # Error, cannot mix str and bytes

Обратите внимание, что, несмотря на свое название, AnyStr не имеет ничего общего с типом Any, а также не означает «любой строковый тип». В частности, AnyStr и str | bytes отличаются друг от друга и имеют разные области применения:

# Invalid use of AnyStr:
# The type variable is used only once in the function signature,
# so cannot be "solved" by the type checker
def greet_bad(cond: bool) -> AnyStr:
    return "hi there!" if cond else b"greetings!"

# The better way of annotating this function:
def greet_proper(cond: bool) -> str | bytes:
    return "hi there!" if cond else b"greetings!"

typing.LiteralString

Специальный тип, включающий только строковые литералы.

Любой строковый литерал совместим с LiteralString, как и другой LiteralString. Однако объект, типизированный как только str , не совместим. Строка, созданная путем комбинирования LiteralString-типизированных объектов, также принимается в качестве LiteralString.

Пример:

def run_query(sql: LiteralString) -> None:
    ...

def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
    run_query("SELECT * FROM students")  # OK
    run_query(literal_string)  # OK
    run_query("SELECT * FROM " + literal_string)  # OK
    run_query(arbitrary_string)  # type checker error
    run_query(  # type checker error
        f"SELECT * FROM students WHERE name = {arbitrary_string}"
    )

LiteralString полезен для чувствительных API, где произвольные строки, сгенерированные пользователем, могут вызвать проблемы. Например, два указанных выше случая, которые генерируют ошибки проверки типов, могут быть уязвимы к атакам типа SQL-инъекции.

См. PEP 675 для получения дополнительной информации.

Добавлен в версии 3.11.

typing.Never

Тип «нижнего уровня» (bottom type), тип, у которого нет элементов.

Его можно использовать для определения функции, которая никогда не должна вызываться, или функции, которая никогда не возвращает значение:

from typing import Never

def never_call_me(arg: Never) -> None:
    pass

def int_or_str(arg: int | str) -> None:
    never_call_me(arg)  # type checker error
    match arg:
        case int():
            print("It's an int")
        case str():
            print("It's a str")
        case _:
            never_call_me(arg)  # OK, arg is of type Never

Добавлен в версии 3.11: В более старых версиях Python для выражения той же концепции может использоваться NoReturn. Never был добавлен для более явного выражения намерений.

typing.NoReturn

Специальный тип, указывающий, что функция никогда не возвращает значение.

Например:

from typing import NoReturn

def stop() -> NoReturn:
    raise RuntimeError('no way')

NoReturn также может использоваться как тип «нижнего уровня» (bottom type), тип, у которого нет значений. Начиная с Python 3.11, для этой концепции следует использовать тип Never. Инструменты проверки типов должны рассматривать эти два типа эквивалентными.

Добавлен в версии 3.5.4.

Добавлен в версии 3.6.2.

typing.Self

Специальный тип для представления текущего вложенного класса.

Например:

from typing import Self, reveal_type

class Foo:
    def return_self(self) -> Self:
        ...
        return self

class SubclassOfFoo(Foo): pass

reveal_type(Foo().return_self())  # Revealed type is "Foo"
reveal_type(SubclassOfFoo().return_self())  # Revealed type is "SubclassOfFoo"

Эта аннотация семантически эквивалентна следующему, хотя и более лаконична:

from typing import TypeVar

Self = TypeVar("Self", bound="Foo")

class Foo:
    def return_self(self: Self) -> Self:
        ...
        return self

В общем случае, если что-то возвращает self, как в приведенных выше примерах, вы должны использовать Self в качестве аннотации возвращаемого значения. Если Foo.return_self была аннотирована как возвращающая "Foo", то проверяющий тип вывел бы, что объект, возвращаемый из SubclassOfFoo.return_self, является типом Foo, а не SubclassOfFoo.

Другие распространенные случаи использования:

• classmethod, которые используются как альтернативные конструкторы и возвращают экземпляры параметра cls.
• Аннотация метода __enter__(), который возвращает self.

Вы не должны использовать Self в качестве аннотации возвращаемого значения, если метод не гарантированно возвращает экземпляр подкласса при наследовании от класса:

class Eggs:
    # Self would be an incorrect return annotation here,
    # as the object returned is always an instance of Eggs,
    # even in subclasses
    def returns_eggs(self) -> "Eggs":
        return Eggs()

См. PEP 673 для получения дополнительной информации.

Добавлен в версии 3.11.

typing.TypeAlias

Специальная аннотация для явного объявления псевдонима типа.

Например:

from typing import TypeAlias

Factors: TypeAlias = list[int]

TypeAlias особенно полезно для аннотирования псевдонимов, использующих прямые ссылки, так как проверяющим типам может быть сложно отличить их от обычных присваиваний переменных:

from typing import Generic, TypeAlias, TypeVar

T = TypeVar("T")

# "Box" does not exist yet,
# so we have to use quotes for the forward reference.
# Using ``TypeAlias`` tells the type checker that this is a type alias declaration,
# not a variable assignment to a string.
BoxOfStrings: TypeAlias = "Box[str]"

class Box(Generic[T]):
    @classmethod
    def make_box_of_strings(cls) -> BoxOfStrings: ...

См. PEP 613 для получения дополнительной информации.

Добавлен в версии 3.10.

Специальные формы

Их можно использовать в качестве типов в аннотациях. Все они поддерживают подписку с помощью [], но каждая имеет уникальный синтаксис.

typing.Union

Тип объединения; Union[X, Y] эквивалентен X | Y и означает либо X, либо Y.

Для определения объединения используйте, например, Union[int, str] или сокращённую запись int | str. Рекомендуется использовать сокращённую запись. Подробности:

• Аргументы должны быть типами, и их должно быть как минимум один.

• Объединения объединений сворачиваются, например:

  Union[Union[int, str], float] == Union[int, str, float]
  

• Объединения из одного аргумента исчезают, например:

  Union[int] == int  # The constructor actually returns int
  

• Избыточные аргументы пропускаются, например:

  Union[int, str, int] == Union[int, str] == int | str
  

• При сравнении объединений порядок аргументов игнорируется, например:

  Union[int, str] == Union[str, int]
  

• Нельзя создавать подклассы или экземпляры Union.
• Нельзя писать Union[X][Y].

Изменено в версии 3.7: Не удалять явные подклассы из объединений во время выполнения.

Изменено в версии 3.10: Объединения теперь можно записывать как X | Y. См. выражения типа объединения.

typing.Optional

Optional[X] эквивалентен X | None (или Union[X, None]).

Обратите внимание, что это не то же самое, что необязательный аргумент, который имеет значение по умолчанию. Для необязательного аргумента с значением по умолчанию не требуется квалификатор Optional в его аннотации типа только потому, что он необязательный. Например:

def foo(arg: int = 0) -> None:
    ...

С другой стороны, если разрешено явное значение None , использование Optional уместно, независимо от того, является ли аргумент необязательным или нет. Например:

def foo(arg: Optional[int] = None) -> None:
    ...

Изменено в версии 3.10: Optional теперь можно записывать как X | None. См. выражения типа объединения.

typing.Concatenate

Специальная форма для аннотирования функций высшего порядка.

Concatenate может использоваться совместно с Callable и ParamSpec для аннотирования вызываемого объекта высшего порядка, который добавляет, удаляет или преобразует параметры другого вызываемого объекта. Использование в форме Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]. Concatenate в настоящее время допустимо только при использовании в качестве первого аргумента Callable. Последний параметр Concatenate должен быть ParamSpec или многоточием (...).

Например, для аннотирования декоратора with_lock , который предоставляет threading.Lock декорированной функции, Concatenate можно использовать для указания того, что with_lock ожидает вызываемый объект, принимающий Lock в качестве первого аргумента и возвращающий вызываемый объект с другим сигнатурой типа. В этом случае ParamSpec указывает, что типы параметров возвращаемого вызываемого объекта зависят от типов параметров передаваемого вызываемого объекта:

from collections.abc import Callable
from threading import Lock
from typing import Concatenate, ParamSpec, TypeVar

P = ParamSpec('P')
R = TypeVar('R')

# Use this lock to ensure that only one thread is executing a function
# at any time.
my_lock = Lock()

def with_lock(f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
    '''A type-safe decorator which provides a lock.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        # Provide the lock as the first argument.
        return f(my_lock, *args, **kwargs)
    return inner

@with_lock
def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:
    '''Add a list of numbers together in a thread-safe manner.'''
    with lock:
        return sum(numbers)

# We don't need to pass in the lock ourselves thanks to the decorator.
sum_threadsafe([1.1, 2.2, 3.3])

Новое в версии 3.10.

См. также

• PEP 612 — Переменные спецификации параметров (PEP, который представил ParamSpec и Concatenate)
• ParamSpec
• Аннотирование вызываемых объектов

typing.Literal

Специальная форма типизации для определения «литеральных типов».

Literal можно использовать для указания проверяющим типам, что аннотированный объект имеет значение, эквивалентное одному из предоставленных литералов.

Например:

def validate_simple(data: Any) -> Literal[True]:  # always returns True
    ...

Mode: TypeAlias = 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[...] не может быть подклассом. Во время выполнения произвольное значение допускается в качестве аргумента типа Literal[...], но проверяющие типы могут накладывать ограничения. См. PEP 586 для получения дополнительной информации о литеральных типах.

Новое в версии 3.8.

Изменено в версии 3.9.1: Literal теперь удаляет дубликаты параметров. Сравнения на равенство объектов Literal больше не зависят от порядка. Объекты Literal теперь будут генерировать исключение TypeError во время сравнения на равенство, если один из их параметров не является хешируемым.

typing.ClassVar

Специальная конструкция типа для маркировки переменных класса.

Как введено в PEP 526, аннотация переменной, заключенная в ClassVar, указывает, что данный атрибут предназначен для использования в качестве переменной класса и не должен устанавливаться для экземпляров этого класса. Использование:

class Starship:
    stats: ClassVar[dict[str, int]] = {} # class variable
    damage: int = 10                     # instance variable

ClassVar принимает только типы и не может быть дальше подписывается.

ClassVar не является классом сам по себе и не должен использоваться с isinstance() или issubclass(). ClassVar не изменяет поведение Python во время выполнения, но может использоваться сторонними проверяющими типами. Например, проверяющий типов может пометить следующий код как ошибку:

enterprise_d = Starship(3000)
enterprise_d.stats = {} # Error, setting class variable on instance
Starship.stats = {}     # This is OK

Новое в версии 3.5.3.

typing.Final

Специальная конструкция типизации для указания конечных имён проверяющим типам.

Конечные имена не могут быть переназначены ни в одном области видимости. Конечные имена, объявленные в областях видимости классов, не могут быть переопределены в подклассах.

Например:

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

Нет проверки этих свойств во время выполнения. См. PEP 591 для получения дополнительной информации.

Новое в версии 3.8.

typing.Required

Специальная конструкция типизации для маркировки ключа TypedDict как обязательного.

Это в основном полезно для total=False TypedDicts. См. TypedDict и PEP 655 для получения дополнительной информации.

Новое в версии 3.11.

typing.NotRequired

Специальная конструкция типизации для маркировки ключа TypedDict как потенциально отсутствующего.

См. TypedDict и PEP 655 для получения дополнительной информации.

Новое в версии 3.11.

typing.Annotated

Специальная форма типизации для добавления метаданных, специфичных для контекста, в аннотацию.

Добавьте метаданные x к заданному типу T с помощью аннотации Annotated[T, x]. Метаданные, добавленные с помощью Annotated, могут использоваться инструментами статического анализа или во время выполнения. Во время выполнения метаданные хранятся в атрибуте __metadata__.

Если библиотека или инструмент сталкивается с аннотацией Annotated[T, x] и не имеет специальной логики для метаданных, она должна игнорировать метаданные и просто рассматривать аннотацию как T. Таким образом, Annotated может быть полезным для кода, который хочет использовать аннотации в целях, выходящих за рамки системы статической типизации Python.

Использование Annotated[T, x] в качестве аннотации всё ещё позволяет выполнять статическую проверку типов T, так как инструменты проверки типов просто проигнорируют метаданные x. Таким образом, Annotated отличается от декоратора @no_type_check, который также может использоваться для добавления аннотаций за пределами области системы типизации, но полностью отключает проверку типов для функции или класса.

Ответственность за интерпретацию метаданных лежит на инструменте или библиотеке, столкнувшейся с аннотацией Annotated. Инструмент или библиотека, столкнувшаяся с типом Annotated, может просмотреть элементы метаданных, чтобы определить, представляют ли они интерес (например, с использованием isinstance()).

Annotated[<type>, <metadata>]

Вот пример того, как можно использовать Annotated для добавления метаданных к аннотациям типов, если вы выполняете анализ диапазонов:

@dataclass
class ValueRange:
    lo: int
    hi: int

T1 = Annotated[int, ValueRange(-10, 5)]
T2 = Annotated[T1, ValueRange(-20, 3)]

Подробности синтаксиса:

• Первый аргумент для Annotated должен быть допустимым типом

• Можно указать несколько элементов метаданных (Annotated поддерживает аргументы с переменным числом):

  @dataclass
  class ctype:
      kind: str
  
  Annotated[int, ValueRange(3, 10), ctype("char")]
  

  Инструменту, использующему аннотации, предстоит решить, разрешено ли клиенту добавлять несколько элементов метаданных к одной аннотации, и как объединять эти аннотации.

• Annotated должен быть индексирован как минимум двумя аргументами (Annotated[int] недопустимо)

• Порядок элементов метаданных сохраняется и имеет значение для проверок на равенство:

  assert Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
      int, ctype("char"), ValueRange(3, 10)
  ]
  

• Вложенные типы Annotated сглаживаются. Порядок элементов метаданных начинается с самой внутренней аннотации:

  assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
      int, ValueRange(3, 10), ctype("char")
  ]
  

• Дублированные элементы метаданных не удаляются:

  assert Annotated[int, ValueRange(3, 10)] != Annotated[
      int, ValueRange(3, 10), ValueRange(3, 10)
  ]
  

• Annotated можно использовать со вложенными и обобщенными псевдонимами:

  @dataclass
  class MaxLen:
      value: int
  
  T = TypeVar("T")
  Vec: TypeAlias = Annotated[list[tuple[T, T]], MaxLen(10)]
  
  assert Vec[int] == Annotated[list[tuple[int, int]], MaxLen(10)]
  

• Annotated нельзя использовать с распакованным TypeVarTuple:

  Variadic: TypeAlias = Annotated[*Ts, Ann1]  # NOT valid
  

  Это эквивалентно:

  Annotated[T1, T2, T3, ..., Ann1]
  

  где T1, T2, и т. д. – TypeVars. Это будет недопустимо: в Annotated должен быть передан только один тип.

• По умолчанию get_type_hints() удаляет метаданные из аннотаций. Передайте include_extras=True для сохранения метаданных:

  >>> from typing import Annotated, get_type_hints
  >>> def func(x: Annotated[int, "metadata"]) -> None: pass
  ...
  >>> get_type_hints(func)
  {'x': <class 'int'>, 'return': <class 'NoneType'>}
  >>> get_type_hints(func, include_extras=True)
  {'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}
  

• Во время выполнения метаданные, связанные с типом Annotated, можно получить через атрибут __metadata__.

  >>> from typing import Annotated
  >>> X = Annotated[int, "very", "important", "metadata"]
  >>> X
  typing.Annotated[int, 'very', 'important', 'metadata']
  >>> X.__metadata__
  ('very', 'important', 'metadata')
  

См. также

PEP 593 – Гибкие аннотации функций и переменных

PEP, представляющий Annotated в стандартной библиотеке.

Добавлена в версии 3.9.

typing.TypeGuard

Специальная конструкция типизации для маркировки функций-фильтров типов, определенных пользователем.

TypeGuard может использоваться для аннотирования возвращаемого типа пользовательской функции-фильтра типов. TypeGuard принимает только один аргумент типа. Во время выполнения функции, помеченные таким образом, должны возвращать логическое значение.

TypeGuard направлен на получение сужения типов – техники, используемой инструментами статической типизации для определения более точного типа выражения в потоке выполнения программы. Обычно сужение типов выполняется путём анализа условного потока кода и применения сужения к блоку кода. Условное выражение в данном случае иногда называют «фильтром типа»:

def is_str(val: str | float):
    # "isinstance" type guard
    if isinstance(val, str):
        # Type of ``val`` is narrowed to ``str``
        ...
    else:
        # Else, type of ``val`` is narrowed to ``float``.
        ...

Иногда удобно использовать пользовательскую булеву функцию в качестве фильтра типов. Такая функция должна использовать TypeGuard[...] в качестве типа возвращаемого значения, чтобы уведомить инструменты статической типизации об этом намерении.

Использование -> TypeGuard указывает инструменту статической типизации, что для данной функции:

1. Возвращаемое значение имеет логический тип.
2. Если возвращаемое значение True, тип её аргумента – тип внутри TypeGuard.

Например:

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    '''Determines whether all objects in the list are strings'''
    return all(isinstance(x, str) for x in val)

def func1(val: list[object]):
    if is_str_list(val):
        # Type of ``val`` is narrowed to ``list[str]``.
        print(" ".join(val))
    else:
        # Type of ``val`` remains as ``list[object]``.
        print("Not a list of strings!")

Если is_str_list является методом класса или экземпляра, то тип в TypeGuard сопоставляется с типом второго параметра после cls или self.

Короче говоря, форма def foo(arg: TypeA) -> TypeGuard[TypeB]: ..., означает, что если foo(arg) возвращает True, то arg сужается с TypeA до TypeB.

Примечание

TypeB не обязательно должен быть более узкой формой TypeA – он может быть даже более широкой формой. Основная причина заключается в возможности сужения list[object] до list[str], даже если последний не является подтипом первого, так как list является инвариантным. Ответственность за создание безопасных фильтров типов возлагается на пользователя.

TypeGuard также работает с переменными типов. Смотрите PEP 647 для получения дополнительной информации.

Добавлена в версии 3.10.

typing.Unpack

Оператор типизации, концептуально отмечающий объект как распакованный.

Например, использование оператора распаковки * для кортежа переменной типа эквивалентно использованию Unpack для маркировки кортежа переменной типа как распакованного:

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]
# Effectively does:
tup: tuple[Unpack[Ts]]

Фактически, Unpack можно использовать взаимозаменяемо с * в контексте typing.TypeVarTuple и builtins.tuple типов. Вы могли видеть Unpack в более старых версиях Python, где * нельзя было использовать в определенных местах:

# In older versions of Python, TypeVarTuple and Unpack
# are located in the `typing_extensions` backports package.
from typing_extensions import TypeVarTuple, Unpack

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]         # Syntax error on Python <= 3.10!
tup: tuple[Unpack[Ts]]  # Semantically equivalent, and backwards-compatible

Добавлена в версии 3.11.

Создание универсальных типов

Следующие классы не должны использоваться напрямую в качестве аннотаций. Они предназначены для создания универсальных типов.

class typing.Generic

Абстрактный базовый класс для универсальных типов.

Универсальный тип обычно объявляется путем наследования от экземпляра этого класса с одной или несколькими переменными типа. Например, универсальный тип отображения может быть определен следующим образом:

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.

Этот класс затем может использоваться следующим образом:

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 typing.TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False)

Переменная типа.

Использование:

T = TypeVar('T')  # Can be anything
S = TypeVar('S', bound=str)  # Can be any subtype of str
A = TypeVar('A', str, bytes)  # Must be exactly str or bytes

Переменные типа в первую очередь предназначены для статических проверочных систем типов. Они служат параметрами для универсальных типов, а также для определения универсальных функций и псевдонимов типов. См. Generic для получения дополнительной информации об универсальных типах. Универсальные функции работают следующим образом:

def repeat(x: T, n: int) -> Sequence[T]:
    """Return a list containing n references to x."""
    return [x]*n


def print_capitalized(x: S) -> S:
    """Print x capitalized, and return x."""
    print(x.capitalize())
    return x


def concatenate(x: A, y: A) -> A:
    """Add two strings or bytes objects together."""
    return x + y

Обратите внимание, что переменные типа могут быть связаны, ограничены или ни тем, ни другим, но не могут быть одновременно связаны и ограничены.

Переменные типа могут быть помечены как ковариативные или контравариативные, передавая covariant=True или contravariant=True. См. PEP 484 для получения более подробной информации. По умолчанию переменные типа инвариантны.

Связанные переменные типа и ограниченные переменные типа имеют разную семантику по нескольким важным параметрам. Использование связанной переменной типа означает, что TypeVar будет решено с использованием наиболее специфичного типа:

x = print_capitalized('a string')
reveal_type(x)  # revealed type is str

class StringSubclass(str):
    pass

y = print_capitalized(StringSubclass('another string'))
reveal_type(y)  # revealed type is StringSubclass

z = print_capitalized(45)  # error: int is not a subtype of str

Переменные типа могут быть связаны с конкретными типами, абстрактными типами (ABC или протоколами), а также с объединением типов:

U = TypeVar('U', bound=str|bytes)  # Can be any subtype of the union str|bytes
V = TypeVar('V', bound=SupportsAbs)  # Can be anything with an __abs__ method

Использование ограниченной переменной типа, однако, означает, что TypeVar может быть решена только как один из указанных ограничений:

a = concatenate('one', 'two')
reveal_type(a)  # revealed type is str

b = concatenate(StringSubclass('one'), StringSubclass('two'))
reveal_type(b)  # revealed type is str, despite StringSubclass being passed in

c = concatenate('one', b'two')  # error: type variable 'A' can be either str or bytes in a function call, but not both

Во время выполнения isinstance(x, T) будет вызвать TypeError.

__name__

Имя переменной типа.

__covariant__

Указывает, помечена ли переменная типа как ковариативная.

__contravariant__

Указывает, помечена ли переменная типа как контравариативная.

__bound__

Связь переменной типа, если она есть.

__constraints__

Кортеж, содержащий ограничения переменной типа, если они есть.

class typing.TypeVarTuple(name)

Кортеж переменных типа. Специализированная форма переменной типа, которая позволяет создавать вариадические универсалы.

Использование:

T = TypeVar("T")
Ts = TypeVarTuple("Ts")

def move_first_element_to_last(tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

Обычная переменная типа позволяет параметризацию одним типом. В отличие от этого, кортеж переменных типа позволяет параметризацию произвольным количеством типов, действуя как произвольное количество переменных типа, заключенных в кортеж. Например:

# T is bound to int, Ts is bound to ()
# Return value is (1,), which has type tuple[int]
move_first_element_to_last(tup=(1,))

# T is bound to int, Ts is bound to (str,)
# Return value is ('spam', 1), which has type tuple[str, int]
move_first_element_to_last(tup=(1, 'spam'))

# T is bound to int, Ts is bound to (str, float)
# Return value is ('spam', 3.0, 1), which has type tuple[str, float, int]
move_first_element_to_last(tup=(1, 'spam', 3.0))

# This fails to type check (and fails at runtime)
# because tuple[()] is not compatible with tuple[T, *Ts]
# (at least one element is required)
move_first_element_to_last(tup=())

Обратите внимание на использование оператора распаковки * в tuple[T, *Ts]. Концептуально, вы можете рассматривать Ts как кортеж переменных типа (T1, T2, ...). tuple[T, *Ts] затем станет tuple[T, *(T1, T2, ...)], что эквивалентно tuple[T, T1, T2, ...]. (Обратите внимание, что в более ранних версиях Python это могло быть записано с использованием Unpack вместо, так как Unpack[Ts].)

Кортежи переменных типа всегда должны распаковываться. Это помогает отличить кортежи переменных типа от обычных переменных типа:

x: Ts          # Not valid
x: tuple[Ts]   # Not valid
x: tuple[*Ts]  # The correct way to do it

Кортежи переменных типа можно использовать в тех же контекстах, что и обычные переменные типа. Например, в определениях классов, аргументах и типах возвращаемых значений:

Shape = TypeVarTuple("Shape")
class Array(Generic[*Shape]):
    def __getitem__(self, key: tuple[*Shape]) -> float: ...
    def __abs__(self) -> "Array[*Shape]": ...
    def get_shape(self) -> tuple[*Shape]: ...

Кортежи переменных типа могут быть успешно объединены с обычными переменными типа:

DType = TypeVar('DType')
Shape = TypeVarTuple('Shape')

class Array(Generic[DType, *Shape]):  # This is fine
    pass

class Array2(Generic[*Shape, DType]):  # This would also be fine
    pass

class Height: ...
class Width: ...

float_array_1d: Array[float, Height] = Array()     # Totally fine
int_array_2d: Array[int, Height, Width] = Array()  # Yup, fine too

Однако обратите внимание, что не более одного кортежа переменных типа может появиться в одном списке аргументов типа или параметров типа:

x: tuple[*Ts, *Ts]                     # Not valid
class Array(Generic[*Shape, *Shape]):  # Not valid
    pass

Наконец, распакованный кортеж переменных типа может использоваться в качестве аннотации типа *args:

def call_soon(
         callback: Callable[[*Ts], None],
         *args: *Ts
) -> None:
    ...
    callback(*args)

В отличие от нераспакованных аннотаций *args - например, *args: int, которые бы указывали, что все аргументы int - *args: *Ts позволяет ссылаться на типы отдельных аргументов в *args. Здесь это позволяет гарантировать, что типы *args передаваемые в call_soon соответствуют типам (позиционных) аргументов callback.

См. PEP 646 для получения дополнительной информации о кортежах переменных типа.

__name__

Имя кортежа переменной типа.

Введено в версии 3.11.

class typing.ParamSpec(name, *, bound=None, covariant=False, contravariant=False)

Переменная спецификации параметра. Специализированная версия переменных типа.

Использование:

P = ParamSpec('P')

Переменные спецификации параметров в основном предназначены для статических проверочных систем типов. Они используются для передачи типов параметров одного вызываемого объекта другому вызываемому объекту – шаблон, часто встречающийся в функциях высшего порядка и декораторах. Они допустимы только при использовании в Concatenate, или в качестве первого аргумента Callable, или в качестве параметров для пользовательских универсалов. См. Generic для получения дополнительной информации об универсальных типах.

Например, чтобы добавить базовую регистрацию в функцию, можно создать декоратор add_logging для регистрации вызовов функций. Переменная спецификации параметра сообщает системе проверки типов, что вызываемый объект, передаваемый в декоратор, и новый вызываемый объект, возвращаемый им, имеют взаимозависимые параметры типа:

from collections.abc import Callable
from typing import TypeVar, ParamSpec
import logging

T = TypeVar('T')
P = ParamSpec('P')

def add_logging(f: Callable[P, T]) -> Callable[P, T]:
    '''A type-safe decorator to add logging to a function.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> T:
        logging.info(f'{f.__name__} was called')
        return f(*args, **kwargs)
    return inner

@add_logging
def add_two(x: float, y: float) -> float:
    '''Add two numbers together.'''
    return x + y

Без ParamSpec, самый простой способ аннотировать это раньше был использовать TypeVar со связанным Callable[..., Any]. Однако это вызывает две проблемы:

1. Система проверки типов не может проверить функцию inner , потому что *args и **kwargs должны иметь тип Any.
2. cast() может потребоваться в теле декоратора add_logging при возвращении функции inner, или системе проверки типов нужно сказать игнорировать return inner.

args

kwargs

Поскольку ParamSpec охватывает как позиционные, так и ключевые параметры, P.args и P.kwargs могут использоваться для разделения ParamSpec на компоненты. P.args представляет кортеж позиционных параметров в заданном вызове и должен использоваться только для аннотации *args. P.kwargs представляет отображение ключевых параметров на их значения в данном вызове и должно использоваться только для аннотации **kwargs. Оба атрибута требуют, чтобы аннотируемый параметр был в области видимости. Во время выполнения P.args и P.kwargs являются экземплярами соответственно ParamSpecArgs и ParamSpecKwargs.

__name__

Имя спецификации параметра.

Переменные спецификации параметров, созданные с помощью covariant=True или contravariant=True , могут использоваться для объявления ковариативных или контравариативных универсальных типов. Аргумент bound также принимается, аналогично TypeVar. Однако фактическая семантика этих ключевых слов еще не определена.

Введено в версии 3.10.

Примечание

Только переменные спецификации параметров, определенные в глобальной области, могут быть сериализованы.

См. также

• PEP 612 – Переменные спецификации параметров (PEP, который представил ParamSpec и Concatenate)
• Concatenate
• Аннотирование вызываемых объектов

typing.ParamSpecArgs

typing.ParamSpecKwargs

Атрибуты аргументов и ключевых аргументов ParamSpec. Атрибут P.args объекта ParamSpec является экземпляром ParamSpecArgs, а атрибут P.kwargs — экземпляром ParamSpecKwargs. Они предназначены для интроспекции во время выполнения и не имеют особого значения для статических проверок типов.

Вызов get_origin() для любого из этих объектов вернёт исходный ParamSpec.

>>> from typing import ParamSpec, get_origin
>>> P = ParamSpec("P")
>>> get_origin(P.args) is P
True
>>> get_origin(P.kwargs) is P
True

Введено в версии 3.10.

Другие специальные директивы

Эти функции и классы не должны использоваться напрямую в качестве аннотаций. Их назначение — быть строительными блоками для создания и объявления типов.

class typing.NamedTuple

Типизированный аналог collections.namedtuple().

Использование:

class Employee(NamedTuple):
    name: str
    id: int

Это эквивалентно:

Employee = collections.namedtuple('Employee', ['name', 'id'])

Для присвоения значения по умолчанию полю, его можно задать в теле класса:

class Employee(NamedTuple):
    name: str
    id: int = 3

employee = Employee('Guido')
assert employee.id == 3

Поля со значениями по умолчанию должны следовать за полями без значений по умолчанию.

Получившийся класс имеет дополнительный атрибут __annotations__ , содержащий словарь, сопоставляющий имена полей с их типами. (Имена полей находятся в атрибуте _fields, а значения по умолчанию — в атрибуте _field_defaults, оба из которых являются частью API namedtuple().)

NamedTuple подклассы также могут иметь строки документации и методы:

class Employee(NamedTuple):
    """Represents an employee."""
    name: str
    id: int = 3

    def __repr__(self) -> str:
        return f'<Employee {self.name}, id={self.id}>'

NamedTuple подклассы могут быть обобщёнными:

class Group(NamedTuple, Generic[T]):
    key: T
    group: list[T]

Обратная совместимость:

Employee = NamedTuple('Employee', [('name', str), ('id', int)])

Изменено в версии 3.6: Добавленв поддержка синтаксиса аннотаций переменных PEP 526.

Изменено в версии 3.6.1: Добавленв поддержка значений по умолчанию, методов и строк документации.

Изменено в версии 3.8: Атрибуты _field_types и __annotations__ теперь представляют собой обычные словари вместо экземпляров OrderedDict.

Изменено в версии 3.9: Удален атрибут _field_types в пользу более стандартного атрибута __annotations__, содержащего ту же информацию.

Изменено в версии 3.11: Добавлена поддержка обобщённых namedtuple.

class typing.NewType(name, tp)

Вспомогательный класс для создания типов с низкой накладной стоимостью различительных типов.

Статический проверяющий типов рассматривает NewType как отдельный тип. Однако во время выполнения вызов NewType возвращает свой аргумент без изменений.

Использование:

UserId = NewType('UserId', int)  # Declare the NewType "UserId"
first_user = UserId(1)  # "UserId" returns the argument unchanged at runtime

__module__

Модуль, в котором определён новый тип.

__name__

Имя нового типа.

__supertype__

Тип, на основе которого создан новый тип.

Введено в версии 3.5.2.

Изменено в версии 3.10: NewType теперь является классом, а не функцией.

class typing.Protocol(Generic)

Базовый класс для классов-протоколов.

Классы-протоколы определяются так:

class Proto(Protocol):
    def meth(self) -> int:
        ...

В основном такие классы используются с проверками статических типов, которые распознают структурное подтипирование (статическое «пёстрое наследование»), например:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

Подробнее см. PEP 544. Классы-протоколы, декорированные runtime_checkable() (описанные позже), действуют как простые протоколы времени выполнения, проверяющие только наличие заданных атрибутов, игнорируя их сигнатуры типов.

Классы-протоколы могут быть обобщёнными, например:

T = TypeVar("T")

class GenProto(Protocol[T]):
    def meth(self) -> T:
        ...

Введено в версии 3.8.

@typing.runtime_checkable

Отметить класс-протокол как протокол времени выполнения.

Такой протокол можно использовать с isinstance() и issubclass(). При применении к классу, не являющемуся протоколом, это вызывает TypeError. Это позволяет выполнять простую структурную проверку, очень похожую на «одного трюка» в collections.abc, например, Iterable. Например:

@runtime_checkable
class Closable(Protocol):
    def close(self): ...

assert isinstance(open('/some/file'), Closable)

@runtime_checkable
class Named(Protocol):
    name: str

import threading
assert isinstance(threading.Thread(name='Bob'), Named)

Примечание

runtime_checkable() будет проверять только наличие необходимых методов или атрибутов, а не их сигнатуры типов или типы. Например, ssl.SSLObject — это класс, поэтому он проходит проверку issubclass() на Callable. Однако метод ssl.SSLObject.__init__ существует только для повышения TypeError с более информативным сообщением, поэтому вызвать (создать экземпляр) ssl.SSLObject невозможно.

Примечание

Проверка isinstance() на протокол, отмеченный как протокол времени выполнения, может быть неожиданно медленной по сравнению с проверкой isinstance() на класс, не являющийся протоколом. Рассмотрите альтернативные методы, такие как вызовы hasattr() для структурных проверок в чувствительном к производительности коде.

Введено в версии 3.8.

class typing.TypedDict(dict)

Специальная конструкция для добавления подсказок типов к словарю. Во время выполнения это обычный dict.

TypedDict объявляет тип словаря, который ожидает, что все его экземпляры будут иметь определённый набор ключей, где каждый ключ связан со значением согласованного типа. Это ожидание не проверяется во время выполнения, но только проверяется средствами проверки типов. Пример использования:

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')

Для возможности использования этой функции с более старыми версиями Python, которые не поддерживают PEP 526, TypedDict поддерживает два дополнительных эквивалентных синтаксических формата:

• Использование литерального dict в качестве второго аргумента:

  Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
  

• Использование ключевых аргументов:

  Point2D = TypedDict('Point2D', x=int, y=int, label=str)
  

Устарело начиная с версии 3.11, будет удалено в версии 3.13: Синтаксис ключевых аргументов устарел в 3.11 и будет удалён в 3.13. Он также может быть не поддерживаемым средствами статической проверки типов.

Функциональный синтаксис также должен использоваться, когда любой из ключей не является допустимым идентификатором, например, потому что это ключевые слова или содержат дефисы. Пример:

# raises SyntaxError
class Point2D(TypedDict):
    in: int  # 'in' is a keyword
    x-y: int  # name with hyphens

# OK, functional syntax
Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})

По умолчанию все ключи должны быть присутствовать в TypedDict. Можно отметить отдельные ключи как необязательные, используя NotRequired:

class Point2D(TypedDict):
    x: int
    y: int
    label: NotRequired[str]

# Alternative syntax
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': NotRequired[str]})

Это означает, что Point2D TypedDict может иметь ключ label опущенным.

Также можно отметить все ключи как необязательные по умолчанию, указав значение False:

class Point2D(TypedDict, total=False):
    x: int
    y: int

# Alternative syntax
Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False)

Это означает, что у Point2D TypedDict могут быть опущены любые ключи. Средства проверки типов должны поддерживать только литеральное False или True в качестве значения аргумента total . True — значение по умолчанию, которое делает все элементы, определённые в теле класса, обязательными.

Отдельные ключи total=False TypedDict можно отметить как обязательные, используя Required:

class Point2D(TypedDict, total=False):
    x: Required[int]
    y: Required[int]
    label: str

# Alternative syntax
Point2D = TypedDict('Point2D', {
    'x': Required[int],
    'y': Required[int],
    'label': str
}, total=False)

Тип TypedDict может наследоваться от одного или нескольких других типов TypedDict с использованием синтаксиса на основе класса. Пример использования:

class Point3D(Point2D):
    z: int

Point3D имеет три элемента: x, y и z. Это эквивалентно следующему определению:

class Point3D(TypedDict):
    x: int
    y: int
    z: int

TypedDict не может наследоваться от класса, который не является TypedDict, за исключением Generic. Например:

class X(TypedDict):
    x: int

class Y(TypedDict):
    y: int

class Z(object): pass  # A non-TypedDict class

class XY(X, Y): pass  # OK

class XZ(X, Z): pass  # raises TypeError

TypedDict может быть обобщённым:

T = TypeVar("T")

class Group(TypedDict, Generic[T]):
    key: T
    group: list[T]

TypedDict можно получить доступ через словари аннотаций (см. Рекомендации по наилучшей практике использования аннотаций для получения дополнительной информации о наилучшей практике использования аннотаций), __total__, __required_keys__ и __optional_keys__.

__total__

Point2D.__total__ возвращает значение аргумента total. Пример:

>>> from typing import TypedDict
>>> class Point2D(TypedDict): pass
>>> Point2D.__total__
True
>>> class Point2D(TypedDict, total=False): pass
>>> Point2D.__total__
False
>>> class Point3D(Point2D): pass
>>> Point3D.__total__
True

Этот атрибут отражает только значение аргумента total для текущего класса TypedDict, а не является ли класс семантически полным. Например, TypedDict с __total__ установленным в True может иметь ключи, помеченные NotRequired, или он может наследоваться от другого TypedDict с total=False. Поэтому для интроспекции лучше использовать __required_keys__ и __optional_keys__.

__required_keys__

Введено в версии 3.9.

__optional_keys__

Point2D.__required_keys__ и Point2D.__optional_keys__ возвращают объекты frozenset, содержащие обязательные и необязательные ключи соответственно.

Ключи, помеченные Required, всегда будут отображаться в __required_keys__, а ключи, помеченные NotRequired, всегда будут отображаться в __optional_keys__.

Для обратной совместимости с Python 3.10 и ниже также можно использовать наследование для объявления как обязательных, так и необязательных ключей в одном TypedDict . Для этого объявляется TypedDict с одним значением для аргумента total и затем наследуется от него в другом TypedDict с другим значением для total:

>>> class Point2D(TypedDict, total=False):
...     x: int
...     y: int
...
>>> class Point3D(Point2D):
...     z: int
...
>>> Point3D.__required_keys__ == frozenset({'z'})
True
>>> Point3D.__optional_keys__ == frozenset({'x', 'y'})
True

Введено в версии 3.9.

Примечание

Если используется from __future__ import annotations или если аннотации задаются в виде строк, аннотации не вычисляются при определении TypedDict . Поэтому динамическая интроспекция, на которой полагаются __required_keys__ и __optional_keys__ , может работать некорректно, и значения атрибутов могут быть неверными.

См. PEP 589 для получения дополнительных примеров и подробных правил использования TypedDict.

Введено в версии 3.8.

Изменено в версии 3.11: Добавлена поддержка маркировки отдельных ключей как Required или NotRequired. См. PEP 655.

Изменено в версии 3.11: Добавлена поддержка обобщённых TypedDict.

Псевдонимы встроенных типов

class typing.Dict(dict, MutableMapping[KT, VT])

Устаревший псевдоним для dict.

Обратите внимание, что для аннотации аргументов предпочтительнее использовать абстрактный тип коллекции, такой как Mapping, а не dict или typing.Dict.

Этот тип можно использовать следующим образом:

def count_words(text: str) -> Dict[str, int]:
    ...

Устарел начиная с версии 3.9: builtins.dict теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.List(list, MutableSequence[T])

Устаревший псевдоним для list.

Обратите внимание, что для аннотации аргументов предпочтительнее использовать абстрактный тип коллекции, такой как Sequence или Iterable, а не list или typing.List.

Этот тип можно использовать следующим образом:

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]

Устарел начиная с версии 3.9: builtins.list теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.Set(set, MutableSet[T])

Устаревший псевдоним для builtins.set.

Обратите внимание, что для аннотации аргументов предпочтительнее использовать абстрактный тип коллекции, такой как AbstractSet, а не set или typing.Set.

Устарел начиная с версии 3.9: builtins.set теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.FrozenSet(frozenset, AbstractSet[T_co])

Устаревший псевдоним для builtins.frozenset.

Устарел начиная с версии 3.9: builtins.frozenset теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

typing.Tuple

Устаревший псевдоним для tuple.

tuple и Tuple являются специальными случаями в системе типов; см. Аннотирование кортежей для получения дополнительных сведений.

Устарел начиная с версии 3.9: builtins.tuple теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.Type(Generic[CT_co])

Устаревший псевдоним для type.

См. Тип объектов класса для получения подробной информации об использовании type или typing.Type в аннотациях типов.

Добавлен в версии 3.5.2.

Устарел начиная с версии 3.9: builtins.type теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

Псевдонимы типов в collections

class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])

Устаревший псевдоним для collections.defaultdict.

Новая версия 3.5.2.

Устарело с версии 3.9: collections.defaultdict теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])

Устаревший псевдоним для collections.OrderedDict.

Новая версия 3.7.2.

Устарело с версии 3.9: collections.OrderedDict теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])

Устаревший псевдоним для collections.ChainMap.

Новая версия 3.5.4.

Новая версия 3.6.1.

Устарело с версии 3.9: collections.ChainMap теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

class typing.Counter(collections.Counter, Dict[T, int])

Устаревший псевдоним для collections.Counter.

Новая версия 3.5.4.

Новая версия 3.6.1.

Устарело с версии 3.9: collections.Counter теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

class typing.Deque(deque, MutableSequence[T])

Устаревший псевдоним для collections.deque.

Новая версия 3.5.4.

Новая версия 3.6.1.

Устарело с версии 3.9: collections.deque теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

Псевдонимы других конкретных типов

class typing.Pattern

class typing.Match

Устаревшие псевдонимы, соответствующие типам возвращаемых значений re.compile() и re.match().

Эти типы (и соответствующие функции) являются обобщёнными относительно AnyStr. Pattern может быть специализирован как Pattern[str] или Pattern[bytes]; Match может быть специализирован как Match[str] или Match[bytes].

Устарело с версии 3.8, будет удалено в версии 3.13: Пространство имён typing.re устарело и будет удалено. Эти типы следует импортировать напрямую из typing.

Устарело с версии 3.9: Классы Pattern и Match из re теперь поддерживают []. См. PEP 585 и Тип обобщённого псевдонима.

class typing.Text

Устаревший псевдоним для str.

Text предоставлен для обеспечения обратной совместимости кода Python 2: в Python 2 Text является псевдонимом для unicode.

Используйте Text для указания, что значение должно содержать строку Unicode, совместимую как с Python 2, так и с Python 3:

def add_unicode_checkmark(text: Text) -> Text:
    return text + u' \u2713'

Новая версия 3.5.2.

Устарело с версии 3.11: Python 2 больше не поддерживается, и большинство проверяющих типов больше не поддерживают проверку типов кода Python 2. Удаление псевдонима в настоящее время не планируется, но пользователям рекомендуется использовать str вместо Text.

Псевдонимы контейнерных ABC в collections.abc

class typing.AbstractSet(Collection[T_co])

Устаревший псевдоним для collections.abc.Set.

Устарело начиная с версии 3.9: collections.abc.Set теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.ByteString(Sequence[int])

Этот тип представляет типы bytes, bytearray и memoryview последовательностей байтов.

Устарело начиная с версии 3.9, будет удалено в версии 3.14: Предпочтительнее typing_extensions.Buffer, или объединение, такое как bytes | bytearray | memoryview.

class typing.Collection(Sized, Iterable[T_co], Container[T_co])

Устаревший псевдоним для collections.abc.Collection.

Введено в версии 3.6.0.

Устарело начиная с версии 3.9: collections.abc.Collection теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.Container(Generic[T_co])

Устаревший псевдоним для collections.abc.Container.

Устарело начиная с версии 3.9: collections.abc.Container теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.ItemsView(MappingView, AbstractSet[tuple[KT_co, VT_co]])

Устаревший псевдоним для collections.abc.ItemsView.

Устарело начиная с версии 3.9: collections.abc.ItemsView теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.KeysView(MappingView, AbstractSet[KT_co])

Устаревший псевдоним для collections.abc.KeysView.

Устарело начиная с версии 3.9: collections.abc.KeysView теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.Mapping(Collection[KT], Generic[KT, VT_co])

Устаревший псевдоним для collections.abc.Mapping.

Этот тип можно использовать следующим образом:

def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:
    return word_list[word]

Устарело начиная с версии 3.9: collections.abc.Mapping теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.MappingView(Sized)

Устаревший псевдоним для collections.abc.MappingView.

Устарело начиная с версии 3.9: collections.abc.MappingView теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.MutableMapping(Mapping[KT, VT])

Устаревший псевдоним для collections.abc.MutableMapping.

Устарело начиная с версии 3.9: collections.abc.MutableMapping теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.MutableSequence(Sequence[T])

Устаревший псевдоним для collections.abc.MutableSequence.

Устарело начиная с версии 3.9: collections.abc.MutableSequence теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.MutableSet(AbstractSet[T])

Устаревший псевдоним для collections.abc.MutableSet.

Устарело начиная с версии 3.9: collections.abc.MutableSet теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.Sequence(Reversible[T_co], Collection[T_co])

Устаревший псевдоним для collections.abc.Sequence.

Устарело начиная с версии 3.9: collections.abc.Sequence теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.ValuesView(MappingView, Collection[_VT_co])

Устаревшее псевдоним к collections.abc.ValuesView.

Устарело начиная с версии 3.9: collections.abc.ValuesView теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

Псевдонимы асинхронных ABC в collections.abc

class typing.Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])

Устаревшее псевдоним к collections.abc.Coroutine.

Изменение типов и порядок переменных соответствуют Generator, например:

from collections.abc import Coroutine
c: Coroutine[list[str], str, int]  # Some coroutine defined elsewhere
x = c.send('hi')                   # Inferred type of 'x' is list[str]
async def bar() -> None:
    y = await c                    # Inferred type of 'y' is int

Добавлено в версии 3.5.3.

Устарело начиная с версии 3.9: collections.abc.Coroutine теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.AsyncGenerator(AsyncIterator[YieldType], Generic[YieldType, SendType])

Устаревшее псевдоним к collections.abc.AsyncGenerator.

Асинхронный генератор может быть аннотирован обобщенным типом AsyncGenerator[YieldType, SendType]. Например:

async def echo_round() -> AsyncGenerator[int, float]:
    sent = yield 0
    while sent >= 0.0:
        rounded = await round(sent)
        sent = yield rounded

В отличие от обычных генераторов, асинхронные генераторы не могут возвращать значение, поэтому нет параметра типа ReturnType. Как и в Generator, параметр SendType изменяется контравариантно.

Если ваш генератор будет только генерировать значения, задайте параметр SendType в None:

async def infinite_stream(start: int) -> AsyncGenerator[int, None]:
    while True:
        yield start
        start = await increment(start)

В качестве альтернативы, аннотируйте ваш генератор как имеющий тип возвращаемого значения AsyncIterable[YieldType] или AsyncIterator[YieldType]:

async def infinite_stream(start: int) -> AsyncIterator[int]:
    while True:
        yield start
        start = await increment(start)

Добавлено в версии 3.6.1.

Устарело начиная с версии 3.9: collections.abc.AsyncGenerator теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.AsyncIterable(Generic[T_co])

Устаревшее псевдоним к collections.abc.AsyncIterable.

Добавлено в версии 3.5.2.

Устарело начиная с версии 3.9: collections.abc.AsyncIterable теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.AsyncIterator(AsyncIterable[T_co])

Устаревшее псевдоним к collections.abc.AsyncIterator.

Добавлено в версии 3.5.2.

Устарело начиная с версии 3.9: collections.abc.AsyncIterator теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.Awaitable(Generic[T_co])

Устаревшее псевдоним к collections.abc.Awaitable.

Добавлено в версии 3.5.2.

Устарело начиная с версии 3.9: collections.abc.Awaitable теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщенного псевдонима.

Псевдонимы для других ABC в collections.abc

class typing.Iterable(Generic[T_co])

Устаревший псевдоним для collections.abc.Iterable.

Устарело начиная с версии 3.9: collections.abc.Iterable теперь поддерживает индексирование ([]). См. PEP 585 и Тип Обобщенного Псевдонима.

class typing.Iterator(Iterable[T_co])

Устаревший псевдоним для collections.abc.Iterator.

Устарело начиная с версии 3.9: collections.abc.Iterator теперь поддерживает индексирование ([]). См. PEP 585 и Тип Обобщенного Псевдонима.

typing.Callable

Устаревший псевдоним для collections.abc.Callable.

См. Аннотирование вызываемых объектов для подробностей о том, как использовать collections.abc.Callable и typing.Callable в аннотациях типов.

Устарело начиная с версии 3.9: collections.abc.Callable теперь поддерживает индексирование ([]). См. PEP 585 и Тип Обобщенного Псевдонима.

Изменено в версии 3.10: Callable теперь поддерживает ParamSpec и Concatenate. См. PEP 612 для получения дополнительной информации.

class typing.Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])

Устаревший псевдоним для collections.abc.Generator.

Генератор может быть аннотирован обобщенным типом Generator[YieldType, SendType, ReturnType]. Например:

def echo_round() -> Generator[int, float, str]:
    sent = yield 0
    while sent >= 0:
        sent = yield round(sent)
    return 'Done'

Обратите внимание, что в отличие от многих других обобщений в модуле typing, поведение SendType Generator является контравариантным, а не ковариантным или инвариантным.

Если ваш генератор будет выдавать только значения, установите SendType и ReturnType на None:

def infinite_stream(start: int) -> Generator[int, None, None]:
    while True:
        yield start
        start += 1

В качестве альтернативы, аннотируйте свой генератор как имеющий возвращаемый тип Iterable[YieldType] или Iterator[YieldType]:

def infinite_stream(start: int) -> Iterator[int]:
    while True:
        yield start
        start += 1

Устарело начиная с версии 3.9: collections.abc.Generator теперь поддерживает индексирование ([]). См. PEP 585 и Тип Обобщенного Псевдонима.

class typing.Hashable

Псевдоним для collections.abc.Hashable.

class typing.Reversible(Iterable[T_co])

Устаревший псевдоним для collections.abc.Reversible.

Устарело начиная с версии 3.9: collections.abc.Reversible теперь поддерживает индексирование ([]). См. PEP 585 и Тип Обобщенного Псевдонима.

class typing.Sized

Псевдоним для collections.abc.Sized.

Псевдонимы для contextlib ABC

class typing.ContextManager(Generic[T_co])

Устаревший псевдоним для contextlib.AbstractContextManager.

Добавлена в версии 3.5.4.

Добавлена в версии 3.6.0.

Устарело начиная с версии 3.9: contextlib.AbstractContextManager теперь поддерживает индексирование ([]). См. PEP 585 и Тип Обобщенного Псевдонима.

class typing.AsyncContextManager(Generic[T_co])

Устаревший псевдоним для contextlib.AbstractAsyncContextManager.

Добавлена в версии 3.5.4.

Добавлена в версии 3.6.2.

Устарело начиная с версии 3.9: contextlib.AbstractAsyncContextManager теперь поддерживает индексирование ([]). См. PEP 585 и Тип Обобщенного Псевдонима.