typing.md

1> **Источник:** https://python-all.ru/3.9/library/typing.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`typing`](https://python-all.ru/3.9/library/typing.html#module-typing) – Поддержка аннотаций типов89Новое в версии 3.5.1011**Исходный код:** [Lib/typing.py](https://python-all.ru/src/3.9/Lib/typing.py)1213> **Примечание**14>15> Среда выполнения Python не проверяет аннотации типов функций и переменных. Они могут использоваться сторонними инструментами, такими как средства проверки типов, IDE, линтеры и т. д.1617---1819Данный модуль предоставляет поддержку аннотаций типов на уровне выполнения. Самая базовая поддержка включает типы [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), [`Union`](https://python-all.ru/3.9/library/typing.html#typing.Union), [`Callable`](https://python-all.ru/3.9/library/typing.html#typing.Callable), [`TypeVar`](https://python-all.ru/3.9/library/typing.html#typing.TypeVar) и [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic). Полную спецификацию см. в [**PEP 484**](https://python-all.ru/3.9/library/typing.html). Для упрощённого введения в аннотации типов см. [**PEP 483**](https://python-all.ru/3.9/library/typing.html).2021Функция ниже принимает и возвращает строку и аннотирована следующим образом:2223```python24def greeting(name: str) -> str:25    return 'Hello ' + name26```2728В функции `greeting` аргумент `name` ожидается типа [`str`](https://python-all.ru/3.9/library/stdtypes.html#str), а возвращаемый тип – [`str`](https://python-all.ru/3.9/library/stdtypes.html#str). Подтипы допускаются в качестве аргументов.2930Новые функции часто добавляются в модуль `typing`. Пакет [typing\_extensions](https://python-all.ru/3.9/library/typing.html) предоставляет бэкпорты этих новых функций для старых версий Python.3132## Соответствующие PEP3334С момента первого появления аннотаций типов в [**PEP 484**](https://python-all.ru/3.9/library/typing.html) и [**PEP 483**](https://python-all.ru/3.9/library/typing.html) ряд PEP изменил и расширил инфраструктуру Python для аннотаций типов. К ним относятся:3536- **[**PEP 526**](https://python-all.ru/3.9/library/typing.html): Синтаксис аннотаций переменных**3738  *Вводит* синтаксис аннотирования переменных вне определений функций, а также [`ClassVar`](https://python-all.ru/3.9/library/typing.html#typing.ClassVar)39- **[**PEP 544**](https://python-all.ru/3.9/library/typing.html): Протоколы: структурная типизация (статическая утиная типизация)**4041  *Вводит* [`Protocol`](https://python-all.ru/3.9/library/typing.html#typing.Protocol) и декоратор [`@runtime_checkable`](https://python-all.ru/3.9/library/typing.html#typing.runtime_checkable)42- **[**PEP 585**](https://python-all.ru/3.9/library/typing.html): Обобщённые типы в стандартных коллекциях**4344  *Вводит* [`types.GenericAlias`](https://python-all.ru/3.9/library/types.html#types.GenericAlias) и возможность использовать классы стандартной библиотеки как [обобщённые типы](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias)45- **[**PEP 586**](https://python-all.ru/3.9/library/typing.html): Литеральные типы**4647  *Представлен* [`Literal`](https://python-all.ru/3.9/library/typing.html#typing.Literal)48- **[**PEP 589**](https://python-all.ru/3.9/library/typing.html): TypedDict: аннотации типов для словарей с фиксированным набором ключей**4950  *Представлен* [`TypedDict`](https://python-all.ru/3.9/library/typing.html#typing.TypedDict)51- **[**PEP 591**](https://python-all.ru/3.9/library/typing.html): Добавление квалификатора final в typing**5253  *Вводит* [`Final`](https://python-all.ru/3.9/library/typing.html#typing.Final) и декоратор [`@final`](https://python-all.ru/3.9/library/typing.html#typing.final)54- **[**PEP 593**](https://python-all.ru/3.9/library/typing.html): Гибкие аннотации функций и переменных**5556  *Представлен* [`Annotated`](https://python-all.ru/3.9/library/typing.html#typing.Annotated)5758## Псевдонимы типов5960Псевдоним типа определяется присваиванием типа псевдониму. В этом примере `Vector` и `list[float]` будут рассматриваться как взаимозаменяемые синонимы:6162```python63Vector = list[float]6465def scale(scalar: float, vector: Vector) -> Vector:66    return [scalar * num for num in vector]6768# Проходит проверку типов; список чисел с плавающей запятой считается Vector.69new_vector = scale(2.0, [1.0, -4.2, 5.4])70```7172Псевдонимы типов полезны для упрощения сложных сигнатур типов. Например:7374```python75from collections.abc import Sequence7677ConnectionOptions = dict[str, str]78Address = tuple[str, int]79Server = tuple[Address, ConnectionOptions]8081def broadcast_message(message: str, servers: Sequence[Server]) -> None:82    ...8384# Статическая проверка типов будет считать предыдущую сигнатуру типа как85# полностью эквивалентную этой.86def broadcast_message(87        message: str,88        servers: Sequence[tuple[tuple[str, int], dict[str, str]]]) -> None:89    ...90```9192Обратите внимание, что `None` как аннотация типа является особым случаем и заменяется на `type(None)`.9394## NewType9596Используйте вспомогательную функцию [`NewType()`](https://python-all.ru/3.9/library/typing.html#typing.NewType) для создания отдельных типов:9798```python99from typing import NewType100101UserId = NewType('UserId', int)102some_id = UserId(524313)103```104105Статический проверщик типов будет рассматривать новый тип как подкласс исходного типа. Это полезно для выявления логических ошибок:106107```python108def get_user_name(user_id: UserId) -> str:109    ...110111# Проходит проверку типов.112user_a = get_user_name(UserId(42351))113114# Не проходит проверку типов; int не является UserId.115user_b = get_user_name(-1)116```117118Можно по-прежнему выполнять все операции `int` над переменной типа `UserId`, но результат всегда будет типа `int`. Это позволяет передавать `UserId` везде, где может ожидаться `int`, но предотвращает случайное создание `UserId` недопустимым способом:119120```python121# 'output' имеет тип 'int', а не 'UserId'122output = UserId(23413) + UserId(54341)123```124125Обратите внимание, что эти проверки выполняются только статическим проверяющим типы. Во время выполнения выражение `Derived = NewType('Derived', Base)` делает `Derived` вызываемым объектом, который немедленно возвращает любой переданный ему параметр. Это означает, что выражение `Derived(some_value)` не создаёт новый класс и не вносит никаких накладных расходов сверх обычного вызова функции.126127Точнее, выражение `some_value is Derived(some_value)` во время выполнения всегда истинно.128129Это также означает, что невозможно создать подтип `Derived`, поскольку во время выполнения это тождественная функция, а не реальный тип:130131```python132from typing import NewType133134UserId = NewType('UserId', int)135136# Завершается ошибкой во время выполнения и не проходит проверку типов.137class AdminUserId(UserId): pass138```139140Однако можно создать [`NewType()`](https://python-all.ru/3.9/library/typing.html#typing.NewType) на основе «производного» `NewType`:141142```python143from typing import NewType144145UserId = NewType('UserId', int)146147ProUserId = NewType('ProUserId', UserId)148```149150и проверка типов для `ProUserId` будет работать как ожидается.151152Подробнее см. [**PEP 484**](https://python-all.ru/3.9/library/typing.html).153154> **Примечание**155>156> Напомним, что использование псевдонима типа объявляет два типа *эквивалентными* друг другу. Использование `Alias = Original` заставит статический анализатор типов считать `Alias` *точно эквивалентным* `Original` во всех случаях. Это полезно, когда требуется упростить сложные сигнатуры типов.157>158> В отличие от этого, `NewType` объявляет один тип *подтипом* другого. Использование `Derived = NewType('Derived', Original)` заставит статический анализатор типов считать `Derived` *подклассом* `Original`, что означает, что значение типа `Original` не может использоваться там, где ожидается значение типа `Derived`. Это полезно для предотвращения логических ошибок с минимальными затратами времени выполнения.159160Новое в версии 3.5.2.161162## Callable163164Фреймворки, ожидающие функции обратного вызова с определённой сигнатурой, могут быть аннотированы с помощью `Callable[[Arg1Type, Arg2Type], ReturnType]`.165166Например:167168```python169from collections.abc import Callable170171def feeder(get_next_item: Callable[[], str]) -> None:172    # Тело173174def async_query(on_success: Callable[[int], None],175                on_error: Callable[[int, Exception], None]) -> None:176    # Тело177178async def on_update(value: str) -> None:179    # Тело180callback: Callable[[str], Awaitable[None]] = on_update181```182183Можно объявить возвращаемый тип вызываемого объекта, не указывая сигнатуру вызова, заменив список аргументов многоточием в аннотации типа: `Callable[..., ReturnType]`.184185## Обобщённые типы186187Поскольку информацию о типах объектов, хранящихся в контейнерах, нельзя статически вывести обобщённым способом, абстрактные базовые классы были расширены для поддержки параметризации типами, чтобы обозначить ожидаемые типы элементов контейнера.188189```python190from collections.abc import Mapping, Sequence191192def notify_by_email(employees: Sequence[Employee],193                    overrides: Mapping[str, str]) -> None: ...194```195196Обобщённые типы можно параметризовать с помощью фабрики, доступной в typing под названием [`TypeVar`](https://python-all.ru/3.9/library/typing.html#typing.TypeVar).197198```python199from collections.abc import Sequence200from typing import TypeVar201202T = TypeVar('T')      # Объявить переменную типа203204def first(l: Sequence[T]) -> T:   # Обобщённая функция205    return l[0]206```207208## Пользовательские обобщённые типы209210Пользовательский класс можно определить как обобщённый класс.211212```python213from typing import TypeVar, Generic214from logging import Logger215216T = TypeVar('T')217218class LoggedVar(Generic[T]):219    def __init__(self, value: T, name: str, logger: Logger) -> None:220        self.name = name221        self.logger = logger222        self.value = value223224    def set(self, new: T) -> None:225        self.log('Set ' + repr(self.value))226        self.value = new227228    def get(self) -> T:229        self.log('Get ' + repr(self.value))230        return self.value231232    def log(self, message: str) -> None:233        self.logger.info('%s: %s', self.name, message)234```235236`Generic[T]` в качестве базового класса определяет, что класс `LoggedVar` принимает один параметр типа `T`. Это также делает `T` допустимым типом внутри тела класса.237238Базовый класс [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic) определяет [`__class_getitem__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__class_getitem__) так, что `LoggedVar[t]` является допустимым типом:239240```python241from collections.abc import Iterable242243def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:244    for var in vars:245        var.set(0)246```247248Обобщённый тип может иметь любое количество переменных типа. Все разновидности [`TypeVar`](https://python-all.ru/3.9/library/typing.html#typing.TypeVar) допустимы в качестве параметров обобщённого типа:249250```python251from typing import TypeVar, Generic, Sequence252253T = TypeVar('T', contravariant=True)254B = TypeVar('B', bound=Sequence[bytes], covariant=True)255S = TypeVar('S', int, str)256257class WeirdTrio(Generic[T, B, S]):258    ...259```260261Каждый аргумент-переменная типа для [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic) должен быть уникальным. Поэтому такой код некорректен:262263```python264from typing import TypeVar, Generic265...266267T = TypeVar('T')268269class Pair(Generic[T, T]):   # НЕДОПУСТИМО270    ...271```272273Можно использовать множественное наследование с [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic):274275```python276from collections.abc import Sized277from typing import TypeVar, Generic278279T = TypeVar('T')280281class LinkedList(Sized, Generic[T]):282    ...283```284285При наследовании от обобщённых классов некоторые переменные типа могут быть зафиксированы:286287```python288from collections.abc import Mapping289from typing import TypeVar290291T = TypeVar('T')292293class MyDict(Mapping[str, T]):294    ...295```296297В этом случае `MyDict` имеет один параметр – `T`.298299Использование обобщённого класса без указания параметров типа подразумевает [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) для каждой позиции. В следующем примере `MyIterable` не является обобщённым, но неявно наследуется от `Iterable[Any]`:300301```python302from collections.abc import Iterable303304class MyIterable(Iterable): # То же, что и Iterable[Any].305```306307Пользовательские обобщённые псевдонимы типов также поддерживаются. Примеры:308309```python310from collections.abc import Iterable311from typing import TypeVar, Union312S = TypeVar('S')313Response = Union[Iterable[S], int]314315# Тип возврата здесь такой же, как Union[Iterable[str], int]316def response(query: str) -> Response[str]:317    ...318319T = TypeVar('T', int, float, complex)320Vec = Iterable[tuple[T, T]]321322def inproduct(v: Vec[T]) -> T: # То же, что и Iterable[tuple[T, T]]323    return sum(x*y for x, y in v)324```325326Изменено в версии 3.7: [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic) больше не имеет собственного метакласса.327328Пользовательский обобщённый класс может иметь ABC в качестве базовых классов без конфликта метаклассов. Обобщённые метаклассы не поддерживаются. Результат параметризации обобщений кэшируется, и большинство типов в модуле typing являются хешируемыми и сравнимыми на равенство.329330## Тип [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any)331332Особым видом типа является [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any). Статический проверяющий типов будет считать каждый тип совместимым с [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), а [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) – совместимым с каждым типом.333334Это означает, что над значением типа [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) можно выполнять любые операции или вызовы методов и присваивать его любой переменной:335336```python337from typing import Any338339a: Any = None340a = []          # ОК341a = 2           # ОК342343s: str = ''344s = a           # ОК345346def foo(item: Any) -> int:347    # Проходит проверку типов; 'item' может быть любого типа,348    # и этот тип может иметь метод 'bar'349    item.bar()350    ...351```352353Обратите внимание, что никакая проверка типов не выполняется при присваивании значения типа [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) более точному типу. Например, статический проверяющий типы не сообщил об ошибке при присваивании `a` переменной `s`, хотя `s` был объявлен как тип [`str`](https://python-all.ru/3.9/library/stdtypes.html#str) и получает значение [`int`](https://python-all.ru/3.9/library/functions.html#int) во время выполнения!354355Кроме того, все функции без указания типа возврата или типов параметров по умолчанию неявно используют [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any):356357```python358def legacy_parser(text):359    ...360    return data361362# Статический проверщик типов будет рассматривать вышеприведенное363# как имеющее ту же сигнатуру, что и:364def legacy_parser(text: Any) -> Any:365    ...366    return data367```368369Такое поведение позволяет использовать [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) в качестве *запасного выхода*, когда нужно смешивать динамически и статически типизированный код.370371Сравните поведение [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) с поведением [`object`](https://python-all.ru/3.9/library/functions.html#object). Как и [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), каждый тип является подтипом [`object`](https://python-all.ru/3.9/library/functions.html#object). Однако, в отличие от [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), обратное неверно: [`object`](https://python-all.ru/3.9/library/functions.html#object) *не* является подтипом любого другого типа.372373Это означает, что когда тип значения – [`object`](https://python-all.ru/3.9/library/functions.html#object), проверяющий типы будет отклонять почти все операции над ним, а присваивание его переменной (или использование в качестве возвращаемого значения) более специализированного типа является ошибкой типа. Например:374375```python376def hash_a(item: object) -> int:377    # Завершается ошибкой; у объекта нет метода 'magic'.378    item.magic()379    ...380381def hash_b(item: Any) -> int:382    # Проходит проверку типов.383    item.magic()384    ...385386# Проходит проверку типов, так как int и str являются подклассами object.387hash_a(42)388hash_a("foo")389390# Проходит проверку типов, так как Any совместим со всеми типами.391hash_b(42)392hash_b("foo")393```394395Используйте [`object`](https://python-all.ru/3.9/library/functions.html#object), чтобы указать, что значение может быть любого типа в типобезопасной манере. Используйте [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), чтобы указать, что значение динамически типизировано.396397## Номинальная и структурная типизация398399Изначально [**PEP 484**](https://python-all.ru/3.9/library/typing.html) определял систему статической типизации Python как использующую *номинальное подтипирование*. Это означает, что класс `A` разрешён там, где ожидается класс `B`, если и только если `A` является подклассом `B`.400401Ранее это требование также применялось к абстрактным базовым классам, таким как [`Iterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterable). Проблема такого подхода в том, что класс должен быть явно помечен для их поддержки, что непитонично и не похоже на то, что обычно делается в идиоматическом динамически типизированном коде Python. Например, следующее соответствует [**PEP 484**](https://python-all.ru/3.9/library/typing.html):402403```python404from collections.abc import Sized, Iterable, Iterator405406class Bucket(Sized, Iterable[int]):407    ...408    def __len__(self) -> int: ...409    def __iter__(self) -> Iterator[int]: ...410```411412[**PEP 544**](https://python-all.ru/3.9/library/typing.html) позволяет решить эту проблему, разрешая пользователям писать приведённый выше код без явных базовых классов в определении класса, что позволяет `Bucket` неявно считаться подтипом как `Sized`, так и `Iterable[int]` статическими проверяющими типов. Это называется *структурной подтипизацией* (или статической утиной типизацией):413414```python415from collections.abc import Iterator, Iterable416417class Bucket:  # Примечание: базовые классы отсутствуют418    ...419    def __len__(self) -> int: ...420    def __iter__(self) -> Iterator[int]: ...421422def collect(items: Iterable[int]) -> int: ...423result = collect(Bucket())  # Проходит проверку типов424```425426Более того, наследуя специальный класс [`Protocol`](https://python-all.ru/3.9/library/typing.html#typing.Protocol), пользователь может определять новые пользовательские протоколы, чтобы в полной мере использовать структурное подтипирование (см. примеры ниже).427428## Содержимое модуля429430Модуль определяет следующие классы, функции и декораторы.431432> **Примечание**433>434> Данный модуль определяет несколько типов, которые являются подклассами уже существующих классов стандартной библиотеки и которые также расширяют [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic) для поддержки переменных типа внутри `[]`. Эти типы стали избыточными в Python 3.9, когда соответствующие существовавшие классы были расширены для поддержки `[]`.435>436> Избыточные типы объявлены устаревшими начиная с Python 3.9, но интерпретатор не будет выдавать предупреждений об устаревании. Ожидается, что средства проверки типов будут помечать устаревшие типы, если проверяемая программа нацелена на Python 3.9 или новее.437>438> Устаревшие типы будут удалены из модуля [`typing`](https://python-all.ru/3.9/library/typing.html#module-typing) в первой версии Python, выпущенной через 5 лет после выхода Python 3.9.0. Подробнее см. в [**PEP 585**](https://python-all.ru/3.9/library/typing.html)–*Аннотации обобщённых типов в стандартных коллекциях*.439440### Специальные примитивы типизации441442#### Специальные типы443444Их можно использовать как типы в аннотациях, и они не поддерживают `[]`.445446#### `typing.Any`447448Специальный тип, указывающий на неограниченный тип.449450- Каждый тип совместим с [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any).451- [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) совместим с каждым типом.452453#### `typing.NoReturn`454455Специальный тип, указывающий, что функция никогда не возвращает значение. Например:456457```python458from typing import NoReturn459460def stop() -> NoReturn:461    raise RuntimeError('no way')462```463464Новое в версии 3.5.4.465466Новое в версии 3.6.2.467468#### Специальные формы469470Их можно использовать как типы в аннотациях с помощью `[]`, каждый имеет уникальный синтаксис.471472#### `typing.Tuple`473474Тип кортежа; `Tuple[X, Y]` – это тип кортежа из двух элементов, где первый элемент имеет тип X, а второй – Y. Тип пустого кортежа может быть записан как `Tuple[()]`.475476Пример: `Tuple[T1, T2]` – это кортеж из двух элементов, соответствующих переменным типа T1 и T2. `Tuple[int, float, str]` – это кортеж из int, float и строки.477478Чтобы задать кортеж переменной длины из однотипных элементов, используйте литеральное многоточие, например `Tuple[int, ...]`. Простой [`Tuple`](https://python-all.ru/3.9/library/typing.html#typing.Tuple) эквивалентен `Tuple[Any, ...]`, а тот, в свою очередь, [`tuple`](https://python-all.ru/3.9/library/stdtypes.html#tuple).479480Устарело с версии 3.9: [`builtins.tuple`](https://python-all.ru/3.9/library/stdtypes.html#tuple) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).481482#### `typing.Union`483484Тип объединения; `Union[X, Y]` означает либо X, либо Y.485486Чтобы определить объединение, используйте, например, `Union[int, str]`. Подробности:487488- Аргументы должны быть типами, и их должно быть как минимум один.489- Объединения объединений разворачиваются, например:490491  ```python492  Union[Union[int, str], float] == Union[int, str, float]493  ```494- Объединения из одного аргумента исчезают, например:495496  ```python497  Union[int] == int  # Конструктор на самом деле возвращает int498  ```499- Повторяющиеся аргументы пропускаются, например:500501  ```python502  Union[int, str, int] == Union[int, str]503  ```504- При сравнении объединений порядок аргументов игнорируется, например:505506  ```python507  Union[int, str] == Union[str, int]508  ```509- Нельзя создавать подкласс или экземпляр объединения.510- Нельзя записать `Union[X][Y]`.511- Можно использовать `Optional[X]` как сокращение для `Union[X, None]`.512513Изменено в версии 3.7: Явные подклассы не удаляются из объединений во время выполнения.514515#### `typing.Optional`516517Тип Optional.518519`Optional[X]` эквивалентно `Union[X, None]`.520521Обратите внимание, что это не то же самое, что необязательный аргумент, который имеет значение по умолчанию. Необязательный аргумент с значением по умолчанию не требует квалификатора `Optional` в своей аннотации типа только потому, что он необязателен. Например:522523```python524def foo(arg: int = 0) -> None:525    ...526```527528С другой стороны, если явное значение `None` допускается, то использование `Optional` уместно, независимо от того, является ли аргумент необязательным или нет. Например:529530```python531def foo(arg: Optional[int] = None) -> None:532    ...533```534535#### `typing.Callable`536537Тип Callable; `Callable[[int], str]` – это функция вида (int) -\> str.538539Синтаксис индексирования всегда должен использоваться ровно с двумя значениями: списком аргументов и типом возвращаемого значения. Список аргументов должен быть списком типов или многоточием; тип возвращаемого значения должен быть одним типом.540541Нет синтаксиса для указания необязательных или именованных аргументов; такие типы функций редко используются в качестве типов колбэков. `Callable[..., ReturnType]` (буквальное многоточие) можно использовать для аннотации вызываемого объекта, принимающего любое количество аргументов и возвращающего `ReturnType`. Обычное [`Callable`](https://python-all.ru/3.9/library/typing.html#typing.Callable) эквивалентно `Callable[..., Any]`, а в свою очередь – [`collections.abc.Callable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Callable).542543Устарело с версии 3.9: [`collections.abc.Callable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Callable) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).544545#### `class typing.Type(Generic[CT_co])`546547Переменная, аннотированная `C`, может принимать значение типа `C`. Напротив, переменная, аннотированная `Type[C]`, может принимать значения, которые сами являются классами – а именно, она принимает *объект класса* `C`. Например:548549```python550a = 3         # Имеет тип 'int'551b = int       # Имеет тип 'Type[int]'552c = type(a)   # Также имеет тип 'Type[int]'553```554555Обратите внимание, что `Type[C]` ковариантен:556557```python558class User: ...559class BasicUser(User): ...560class ProUser(User): ...561class TeamUser(User): ...562563# Принимает User, BasicUser, ProUser, TeamUser, ...564def make_new_user(user_class: Type[User]) -> User:565    # ...566    return user_class()567```568569Тот факт, что `Type[C]` ковариантен, подразумевает, что все подклассы `C` должны реализовывать те же сигнатуры конструктора и методов класса, что и `C`. Средство проверки типов должно отмечать нарушения этого, но также должно разрешать вызовы конструкторов в подклассах, которые соответствуют вызовам конструктора в указанном базовом классе. То, как средство проверки типов должно обрабатывать этот конкретный случай, может измениться в будущих версиях [**PEP 484**](https://python-all.ru/3.9/library/typing.html).570571Единственными допустимыми параметрами для [`Type`](https://python-all.ru/3.9/library/typing.html#typing.Type) являются классы, [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), [переменные типа](https://python-all.ru/3.9/library/typing.html#generics) и объединения любых из этих типов. Например:572573```python574def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]): ...575```576577`Type[Any]` эквивалентен `Type`, который в свою очередь эквивалентен `type`, корню метаклассовой иерархии Python.578579Новое в версии 3.5.2.580581Устарело с версии 3.9: [`builtins.type`](https://python-all.ru/3.9/library/functions.html#type) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).582583#### `typing.Literal`584585Тип, который можно использовать для указания средствам проверки типов, что соответствующая переменная или параметр функции имеет значение, эквивалентное предоставленному литералу (или одному из нескольких литералов). Например:586587```python588def validate_simple(data: Any) -> Literal[True]:  # всегда возвращает True589    ...590591MODE = Literal['r', 'rb', 'w', 'wb']592def open_helper(file: str, mode: MODE) -> str:593    ...594595open_helper('/some/path', 'r')  # Проходит проверку типов596open_helper('/other/path', 'typo')  # Ошибка в тайпчекере597```598599`Literal[...]` нельзя наследовать. Во время выполнения произвольное значение допускается в качестве аргумента типа для `Literal[...]`, но проверяющие типа могут накладывать ограничения. См. [**PEP 586**](https://python-all.ru/3.9/library/typing.html) для получения дополнительных сведений о литеральных типах.600601Новое в версии 3.8.602603Изменено в версии 3.9.1: `Literal` теперь дедуплицирует параметры. Сравнения на равенство объектов `Literal` больше не зависят от порядка. Объекты `Literal` теперь будут вызывать исключение [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError) при сравнении на равенство, если один из их параметров не является [хешируемым](https://python-all.ru/3.9/glossary.html#term-hashable).604605#### `typing.ClassVar`606607Специальная конструкция типа для пометки переменных класса.608609Как представлено в [**PEP 526**](https://python-all.ru/3.9/library/typing.html), аннотация переменной, обёрнутая в ClassVar, указывает, что данный атрибут предназначен для использования в качестве переменной класса и не должен устанавливаться на экземплярах этого класса. Использование:610611```python612class Starship:613    stats: ClassVar[dict[str, int]] = {} # переменная класса614    damage: int = 10                     # переменная экземпляра615```616617[`ClassVar`](https://python-all.ru/3.9/library/typing.html#typing.ClassVar) принимает только типы и не может быть дополнительно индексирован.618619[`ClassVar`](https://python-all.ru/3.9/library/typing.html#typing.ClassVar) сам по себе не является классом и не должен использоваться с [`isinstance()`](https://python-all.ru/3.9/library/functions.html#isinstance) или [`issubclass()`](https://python-all.ru/3.9/library/functions.html#issubclass). [`ClassVar`](https://python-all.ru/3.9/library/typing.html#typing.ClassVar) не меняет поведение Python во время выполнения, но может использоваться сторонними проверяющими типов. Например, проверяющий типов может отметить следующий код как ошибочный:620621```python622enterprise_d = Starship(3000)623enterprise_d.stats = {} # Ошибка: установка переменной класса на экземпляре624Starship.stats = {}     # Это корректно.625```626627Новое в версии 3.5.3.628629#### `typing.Final`630631Специальная конструкция типов для указания средствам проверки типов, что имя не может быть переприсвоено или переопределено в подклассе. Например:632633```python634MAX_SIZE: Final = 9000635MAX_SIZE += 1  # Ошибка, выдаваемая проверщиком типов636637class Connection:638    TIMEOUT: Final[int] = 10639640class FastConnector(Connection):641    TIMEOUT = 1  # Ошибка, выдаваемая проверщиком типов642```643644Проверка этих свойств во время выполнения не выполняется. Подробнее см. [**PEP 591**](https://python-all.ru/3.9/library/typing.html).645646Новое в версии 3.8.647648#### `typing.Annotated`649650Тип, введённый в [**PEP 593**](https://python-all.ru/3.9/library/typing.html) (`Flexible function and variable annotations`), для декорирования существующих типов контекстно-зависимыми метаданными (возможно, несколькими их частями, так как `Annotated` вариадичен). В частности, тип `T` можно аннотировать метаданными `x` с помощью аннотации типа `Annotated[T, x]`. Эти метаданные можно использовать как для статического анализа, так и во время выполнения. Если библиотека (или инструмент) встречает аннотацию типа `Annotated[T, x]` и не имеет специальной логики для метаданных `x`, она должна игнорировать их и просто обрабатывать тип как `T`. В отличие от функциональности `no_type_check`, которая в настоящее время существует в модуле `typing` и полностью отключает проверку типов аннотаций для функции или класса, тип `Annotated` позволяет как статическую проверку типов `T` (которая может безопасно игнорировать `x`), так и доступ к `x` во время выполнения в рамках конкретного приложения.651652В конечном счёте, ответственность за интерпретацию аннотаций (если вообще) лежит на инструменте или библиотеке, встречающей тип `Annotated`. Инструмент или библиотека, встречающие тип `Annotated`, могут просматривать аннотации, чтобы определить, представляют ли они интерес (например, с помощью `isinstance()`).653654Когда инструмент или библиотека не поддерживает аннотации или встречает неизвестную аннотацию, она должна просто игнорировать её и обрабатывать аннотированный тип как базовый тип.655656Инструмент, потребляющий аннотации, сам решает, разрешено ли клиенту иметь несколько аннотаций на одном типе и как объединять эти аннотации.657658Поскольку тип `Annotated` позволяет помещать несколько аннотаций одного (или разных) типа на любой узел, инструменты или библиотеки, потребляющие эти аннотации, отвечают за обработку возможных дубликатов. Например, если вы выполняете анализ диапазона значений, вы можете разрешить это:659660```python661T1 = Annotated[int, ValueRange(-10, 5)]662T2 = Annotated[T1, ValueRange(-20, 3)]663```664665Передача `include_extras=True` в [`get_type_hints()`](https://python-all.ru/3.9/library/typing.html#typing.get_type_hints) позволяет получить доступ к дополнительным аннотациям во время выполнения.666667Подробности синтаксиса:668669- Первый аргумент `Annotated` должен быть допустимым типом670- Поддерживаются несколько аннотаций типов (`Annotated` поддерживает вариадические аргументы):671672  ```python673  Annotated[int, ValueRange(3, 10), ctype("char")]674  ```675- `Annotated` должен вызываться как минимум с двумя аргументами ( `Annotated[int]` недействителен)676- Порядок аннотаций сохраняется и важен для проверки на равенство:677678  ```python679  Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[680      int, ctype("char"), ValueRange(3, 10)681  ]682  ```683- Вложенные типы `Annotated` уплощаются, при этом метаданные упорядочиваются, начиная с самой внутренней аннотации:684685  ```python686  Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[687      int, ValueRange(3, 10), ctype("char")688  ]689  ```690- Дублирующиеся аннотации не удаляются:691692  ```python693  Annotated[int, ValueRange(3, 10)] != Annotated[694      int, ValueRange(3, 10), ValueRange(3, 10)695  ]696  ```697- `Annotated` можно использовать с вложенными и обобщёнными псевдонимами:698699  ```python700  T = TypeVar('T')701  Vec = Annotated[list[tuple[T, T]], MaxLen(10)]702  V = Vec[int]703704  V == Annotated[list[tuple[int, int]], MaxLen(10)]705  ```706707Новое в версии 3.9.708709#### Построение обобщённых типов710711Они не используются в аннотациях. Это строительные блоки для создания обобщённых типов.712713#### `class typing.Generic`714715Абстрактный базовый класс для обобщённых типов.716717Обобщённый тип обычно объявляется наследованием от экземпляра этого класса с одной или несколькими переменными типа. Например, обобщённый тип отображения может быть определён так:718719```python720class Mapping(Generic[KT, VT]):721    def __getitem__(self, key: KT) -> VT:722        ...723        # И т.д.724```725726Затем этот класс можно использовать следующим образом:727728```python729X = TypeVar('X')730Y = TypeVar('Y')731732def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:733    try:734        return mapping[key]735    except KeyError:736        return default737```738739#### `class typing.TypeVar`740741Переменная типа.742743Использование:744745```python746T = TypeVar('T')  # Может быть чем угодно747S = TypeVar('S', bound=str)  # Может быть любым подтипом str748A = TypeVar('A', str, bytes)  # Должно быть ровно str или bytes749```750751Переменные типов существуют в первую очередь для пользы статических средств проверки типов. Они служат параметрами для обобщённых типов, а также для определений обобщённых функций. Смотрите [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic) для получения дополнительной информации об обобщённых типах. Обобщённые функции работают следующим образом:752753```python754def repeat(x: T, n: int) -> Sequence[T]:755    """Возвращает список, содержащий n ссылок на x."""756    return [x]*n757758def print_capitalized(x: S) -> S:759    """Печатает x с заглавной буквы и возвращает x."""760    print(x.capitalize())761    return x762763def concatenate(x: A, y: A) -> A:764    """Складывает две строки или два объекта bytes."""765    return x + y766```767768Обратите внимание, что переменные типа могут быть *связаны*, *ограничены* или ни тем, ни другим, но не могут быть одновременно и связаны, *и* ограничены.769770Ограниченные переменные типов и связанные переменные типов имеют разную семантику в нескольких важных аспектах. Использование *ограниченной* переменной типа означает, что `TypeVar` может быть решена только как одна из заданных ограничений:771772```python773a = concatenate('one', 'two')  # Ок, переменная 'a' имеет тип 'str'774b = concatenate(StringSubclass('one'), StringSubclass('two'))  # Выведенный тип переменной 'b' – 'str',775                                                               # несмотря на передачу 'StringSubclass'776c = concatenate('one', b'two')  # ошибка: переменная типа 'A' может быть 'str' или 'bytes' при вызове функции, но не оба сразу777```778779Использование *связанной* переменной типа, однако, означает, что `TypeVar` будет решена с использованием наиболее конкретного типа:780781```python782print_capitalized('a string')  # Ок, результат имеет тип 'str'783784class StringSubclass(str):785    pass786787print_capitalized(StringSubclass('another string'))  # Ок, результат имеет тип 'StringSubclass'788print_capitalized(45)  # ошибка: int не является подтипом str789```790791Переменные типа могут быть связаны с конкретными типами, абстрактными типами (ABC или протоколами) и даже объединениями типов:792793```python794U = TypeVar('U', bound=str|bytes)  # Может быть любым подтипом объединения str|bytes795V = TypeVar('V', bound=SupportsAbs)  # Может быть чем угодно с методом __abs__796```797798Связанные переменные типа особенно полезны для аннотирования [`classmethods`](https://python-all.ru/3.9/library/functions.html#classmethod), которые служат альтернативными конструкторами. В следующем примере (© [Raymond Hettinger](https://python-all.ru/3.9/library/typing.html)) переменная типа `C` привязана к классу `Circle` с помощью прямой ссылки. Использование этой переменной типа для аннотирования классового метода `with_circumference` вместо жёстко заданного возвращаемого типа `Circle` означает, что проверяющий типы может корректно вывести возвращаемый тип, даже если метод вызван на подклассе:799800```python801import math802803C = TypeVar('C', bound='Circle')804805class Circle:806    """Абстрактная окружность"""807808    def __init__(self, radius: float) -> None:809        self.radius = radius810811    # Используется переменная типа, чтобы показать, что возвращаемый тип812    # всегда будет экземпляром того, чем является ``cls``813    @classmethod814    def with_circumference(cls: type[C], circumference: float) -> C:815        """Создать окружность с указанной длиной окружности"""816        radius = circumference / (math.pi * 2)817        return cls(radius)818819class Tire(Circle):820    """Специализированная окружность (из резины)"""821822    MATERIAL = 'rubber'823824c = Circle.with_circumference(3)  # Ок, переменная 'c' имеет тип 'Circle'825t = Tire.with_circumference(4)  # Ок, переменная 't' имеет тип 'Tire' (не 'Circle')826```827828Во время выполнения `isinstance(x, T)` вызовет [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError). В общем, [`isinstance()`](https://python-all.ru/3.9/library/functions.html#isinstance) и [`issubclass()`](https://python-all.ru/3.9/library/functions.html#issubclass) не должны использоваться с типами.829830Переменные типа могут быть помечены как ковариантные или контравариантные путём передачи `covariant=True` или `contravariant=True`. См. [**PEP 484**](https://python-all.ru/3.9/library/typing.html) для получения дополнительных сведений. По умолчанию переменные типа инвариантны.831832#### `typing.AnyStr`833834`AnyStr` – это [`constrained type variable`](https://python-all.ru/3.9/library/typing.html#typing.TypeVar), определённый как `AnyStr = TypeVar('AnyStr', str, bytes)`.835836Предназначен для функций, которые могут принимать строки любого типа, не допуская смешивания разных типов строк. Например:837838```python839def concat(a: AnyStr, b: AnyStr) -> AnyStr:840    return a + b841842concat(u"foo", u"bar")  # Ок, результат имеет тип 'unicode'843concat(b"foo", b"bar")  # Ок, результат имеет тип 'bytes'844concat(u"foo", b"bar")  # Ошибка, нельзя смешивать unicode и bytes845```846847#### `class typing.Protocol(Generic)`848849Базовый класс для классов протоколов. Классы протоколов определяются следующим образом:850851```python852class Proto(Protocol):853    def meth(self) -> int:854        ...855```856857Такие классы в основном используются со статическими проверяющими типов, которые распознают структурную подтипизацию (статическую утиную типизацию), например:858859```python860class C:861    def meth(self) -> int:862        return 0863864def func(x: Proto) -> int:865    return x.meth()866867func(C())  # Проходит статическую проверку типов868```869870Подробности см. в [**PEP 544**](https://python-all.ru/3.9/library/typing.html). Классы протоколов, декорированные [`runtime_checkable()`](https://python-all.ru/3.9/library/typing.html#typing.runtime_checkable) (описаны далее), действуют как упрощённые протоколы времени выполнения, которые проверяют только наличие заданных атрибутов, игнорируя их сигнатуры типов.871872Протокольные классы могут быть обобщёнными, например:873874```python875class GenProto(Protocol[T]):876    def meth(self) -> T:877        ...878```879880Новое в версии 3.8.881882#### `@typing.runtime_checkable`883884Помечает протокольный класс как протокол времени выполнения.885886Такой протокол может использоваться с [`isinstance()`](https://python-all.ru/3.9/library/functions.html#isinstance) и [`issubclass()`](https://python-all.ru/3.9/library/functions.html#issubclass). При применении к классу, не являющемуся протоколом, возникает [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError). Это позволяет выполнять простую структурную проверку, очень похожую на “one trick ponies” в [`collections.abc`](https://python-all.ru/3.9/library/collections.abc.html#module-collections.abc), таких как [`Iterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterable). Например:887888```python889@runtime_checkable890class Closable(Protocol):891    def close(self): ...892893assert isinstance(open('/some/file'), Closable)894```895896> **Примечание**897>898> [`runtime_checkable()`](https://python-all.ru/3.9/library/typing.html#typing.runtime_checkable) будет проверять только наличие требуемых методов, но не их сигнатуры типов! Например, [`builtins.complex`](https://python-all.ru/3.9/library/functions.html#complex) реализует [`__float__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__float__), поэтому он проходит проверку [`issubclass()`](https://python-all.ru/3.9/library/functions.html#issubclass) на соответствие [`SupportsFloat`](https://python-all.ru/3.9/library/typing.html#typing.SupportsFloat). Однако метод `complex.__float__` существует только для того, чтобы вызвать [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError) с более информативным сообщением.899900Новое в версии 3.8.901902#### Другие специальные директивы903904Они не используются в аннотациях. Это строительные блоки для объявления типов.905906#### `class typing.NamedTuple`907908Типизированная версия [`collections.namedtuple()`](https://python-all.ru/3.9/library/collections.html#collections.namedtuple).909910Использование:911912```python913class Employee(NamedTuple):914    name: str915    id: int916```917918Это эквивалентно:919920```python921Employee = collections.namedtuple('Employee', ['name', 'id'])922```923924Чтобы задать полю значение по умолчанию, можно присвоить его в теле класса:925926```python927class Employee(NamedTuple):928    name: str929    id: int = 3930931employee = Employee('Guido')932assert employee.id == 3933```934935Поля со значением по умолчанию должны следовать после полей без значения по умолчанию.936937Полученный класс имеет дополнительный атрибут `__annotations__`, который содержит словарь, отображающий имена полей на их типы. (Имена полей находятся в атрибуте `_fields`, а значения по умолчанию – в атрибуте `_field_defaults`; оба они являются частью API [`namedtuple()`](https://python-all.ru/3.9/library/collections.html#collections.namedtuple).)938939Подклассы `NamedTuple` также могут иметь докстринги и методы:940941```python942class Employee(NamedTuple):943    """Представляет сотрудника."""944    name: str945    id: int = 3946947    def __repr__(self) -> str:948        return f'<Employee {self.name}, id={self.id}>'949```950951Обратно совместимое использование:952953```python954Employee = NamedTuple('Employee', [('name', str), ('id', int)])955```956957Изменено в версии 3.6: Добавлена поддержка синтаксиса аннотации переменных [**PEP 526**](https://python-all.ru/3.9/library/typing.html).958959Изменено в версии 3.6.1: Добавлена поддержка значений по умолчанию, методов и строк документации.960961Изменено в версии 3.8: Атрибуты `_field_types` и `__annotations__` теперь являются обычными словарями, а не экземплярами `OrderedDict`.962963Изменено в версии 3.9: Атрибут `_field_types` удалён в пользу более стандартного атрибута `__annotations__`, который содержит ту же информацию.964965#### `typing.NewType(name, tp)`966967Вспомогательная функция для указания отдельного типа проверяющему типы, см. [NewType](https://python-all.ru/3.9/library/typing.html#distinct). Во время выполнения она возвращает функцию, которая возвращает свой аргумент. Использование:968969```python970UserId = NewType('UserId', int)971first_user = UserId(1)972```973974Новое в версии 3.5.2.975976#### `class typing.TypedDict(dict)`977978Специальная конструкция для добавления подсказок типов к словарю. Во время выполнения это обычный [`dict`](https://python-all.ru/3.9/library/stdtypes.html#dict).979980`TypedDict` объявляет тип словаря, который ожидает, что все его экземпляры будут иметь определённый набор ключей, где каждый ключ связан со значением согласованного типа. Это ожидание не проверяется во время выполнения, а обеспечивается только средствами проверки типов. Использование:981982```python983class Point2D(TypedDict):984    x: int985    y: int986    label: str987988a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # ОК989b: Point2D = {'z': 3, 'label': 'bad'}           # Не проходит проверку типов990991assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')992```993994Чтобы разрешить использование этой возможности в старых версиях Python, которые не поддерживают [**PEP 526**](https://python-all.ru/3.9/library/typing.html), `TypedDict` поддерживает две дополнительные эквивалентные синтаксические формы:995996- Использование литерала [`dict`](https://python-all.ru/3.9/library/stdtypes.html#dict) в качестве второго аргумента:997998  ```python999  Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})1000  ```1001- Использование именованных аргументов:10021003  ```python1004  Point2D = TypedDict('Point2D', x=int, y=int, label=str)1005  ```10061007Функциональный синтаксис также следует использовать, когда какой-либо из ключей не является допустимым [идентификатором](https://python-all.ru/3.9/reference/lexical_analysis.html#identifiers), например, потому что они являются ключевыми словами или содержат дефисы. Пример:10081009```python1010# возбуждает SyntaxError1011class Point2D(TypedDict):1012    in: int  # 'in' – ключевое слово1013    x-y: int  # имя с дефисами10141015# ОК, функциональный синтаксис1016Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})1017```10181019По умолчанию все ключи должны присутствовать в `TypedDict`. Это можно переопределить, указав totality. Использование:10201021```python1022class Point2D(TypedDict, total=False):1023    x: int1024    y: int10251026# Альтернативный синтаксис1027Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False)1028```10291030Это означает, что `Point2D` `TypedDict` может не содержать любой из ключей. Средство проверки типов должно поддерживать только литерал `False` или `True` в качестве значения аргумента `total`. `True` – значение по умолчанию, и оно делает все элементы, определённые в теле класса, обязательными.10311032`TypedDict` может наследоваться от одного или нескольких других типов `TypedDict` с использованием синтаксиса на основе классов. Использование:10331034```python1035class Point3D(Point2D):1036    z: int1037```10381039`Point3D` содержит три элемента: `x`, `y` и `z`. Это эквивалентно следующему определению:10401041```python1042class Point3D(TypedDict):1043    x: int1044    y: int1045    z: int1046```10471048`TypedDict` не может наследоваться от не-`TypedDict` класса, включая [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic). Например:10491050```python1051class X(TypedDict):1052    x: int10531054class Y(TypedDict):1055    y: int10561057class Z(object): pass  # Класс, не являющийся TypedDict10581059class XY(X, Y): pass  # ОК10601061class XZ(X, Z): pass  # вызывает TypeError10621063T = TypeVar('T')1064class XT(X, Generic[T]): pass  # вызывает TypeError1065```10661067Объект `TypedDict` можно исследовать с помощью `__annotations__`, [`__total__`](https://python-all.ru/3.9/library/typing.html#typing.TypedDict.__total__), [`__required_keys__`](https://python-all.ru/3.9/library/typing.html#typing.TypedDict.__required_keys__) и [`__optional_keys__`](https://python-all.ru/3.9/library/typing.html#typing.TypedDict.__optional_keys__).10681069#### `__total__`10701071`Point2D.__total__` возвращает значение аргумента `total`. Пример:10721073```python1074>>> from typing import TypedDict1075>>> class Point2D(TypedDict): pass1076>>> Point2D.__total__1077True1078>>> class Point2D(TypedDict, total=False): pass1079>>> Point2D.__total__1080False1081>>> class Point3D(Point2D): pass1082>>> Point3D.__total__1083True1084```10851086#### `__required_keys__`10871088#### `__optional_keys__`10891090`Point2D.__required_keys__` и `Point2D.__optional_keys__` возвращают объекты [`frozenset`](https://python-all.ru/3.9/library/stdtypes.html#frozenset), содержащие обязательные и необязательные ключи соответственно. В настоящее время единственный способ объявить как обязательные, так и необязательные ключи в одном `TypedDict` – это смешанное наследование: объявить `TypedDict` с одним значением для аргумента `total`, а затем унаследовать его от другого `TypedDict` с другим значением для `total`. Использование:10911092```python1093>>> class Point2D(TypedDict, total=False):1094...     x: int1095...     y: int1096...1097>>> class Point3D(Point2D):1098...     z: int1099...1100>>> Point3D.__required_keys__ == frozenset({'z'})1101True1102>>> Point3D.__optional_keys__ == frozenset({'x', 'y'})1103True1104```11051106Смотрите [**PEP 589**](https://python-all.ru/3.9/library/typing.html) для дополнительных примеров и подробных правил использования `TypedDict`.11071108Новое в версии 3.8.11091110### Конкретные обобщённые коллекции11111112#### Соответствующие встроенным типам11131114#### `class typing.Dict(dict, MutableMapping[KT, VT])`11151116Обобщённая версия [`dict`](https://python-all.ru/3.9/library/stdtypes.html#dict). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`Mapping`](https://python-all.ru/3.9/library/typing.html#typing.Mapping).11171118Этот тип можно использовать следующим образом:11191120```python1121def count_words(text: str) -> Dict[str, int]:1122    ...1123```11241125Устарело с версии 3.9: [`builtins.dict`](https://python-all.ru/3.9/library/stdtypes.html#dict) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).11261127#### `class typing.List(list, MutableSequence[T])`11281129Обобщённая версия [`list`](https://python-all.ru/3.9/library/stdtypes.html#list). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`Sequence`](https://python-all.ru/3.9/library/typing.html#typing.Sequence) или [`Iterable`](https://python-all.ru/3.9/library/typing.html#typing.Iterable).11301131Этот тип можно использовать следующим образом:11321133```python1134T = TypeVar('T', int, float)11351136def vec2(x: T, y: T) -> List[T]:1137    return [x, y]11381139def keep_positives(vector: Sequence[T]) -> List[T]:1140    return [item for item in vector if item > 0]1141```11421143Устарело с версии 3.9: [`builtins.list`](https://python-all.ru/3.9/library/stdtypes.html#list) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).11441145#### `class typing.Set(set, MutableSet[T])`11461147Обобщённая версия [`builtins.set`](https://python-all.ru/3.9/library/stdtypes.html#set). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`AbstractSet`](https://python-all.ru/3.9/library/typing.html#typing.AbstractSet).11481149Устарело с версии 3.9: [`builtins.set`](https://python-all.ru/3.9/library/stdtypes.html#set) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).11501151#### `class typing.FrozenSet(frozenset, AbstractSet[T_co])`11521153Обобщённая версия [`builtins.frozenset`](https://python-all.ru/3.9/library/stdtypes.html#frozenset).11541155Устарело с версии 3.9: [`builtins.frozenset`](https://python-all.ru/3.9/library/stdtypes.html#frozenset) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).11561157> **Примечание**1158>1159> [`Tuple`](https://python-all.ru/3.9/library/typing.html#typing.Tuple) – это специальная форма.11601161#### Соответствует типам в [`collections`](https://python-all.ru/3.9/library/collections.html#module-collections)11621163#### `class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])`11641165Обобщённая версия [`collections.defaultdict`](https://python-all.ru/3.9/library/collections.html#collections.defaultdict).11661167Новое в версии 3.5.2.11681169Устарело с версии 3.9: [`collections.defaultdict`](https://python-all.ru/3.9/library/collections.html#collections.defaultdict) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).11701171#### `class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])`11721173Обобщённая версия [`collections.OrderedDict`](https://python-all.ru/3.9/library/collections.html#collections.OrderedDict).11741175Добавлено в версии 3.7.2.11761177Устарело с версии 3.9: [`collections.OrderedDict`](https://python-all.ru/3.9/library/collections.html#collections.OrderedDict) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).11781179#### `class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])`11801181Обобщённая версия [`collections.ChainMap`](https://python-all.ru/3.9/library/collections.html#collections.ChainMap).11821183Новое в версии 3.5.4.11841185Новое в версии 3.6.1.11861187Устарело с версии 3.9: [`collections.ChainMap`](https://python-all.ru/3.9/library/collections.html#collections.ChainMap) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).11881189#### `class typing.Counter(collections.Counter, Dict[T, int])`11901191Обобщённая версия [`collections.Counter`](https://python-all.ru/3.9/library/collections.html#collections.Counter).11921193Новое в версии 3.5.4.11941195Новое в версии 3.6.1.11961197Устарело с версии 3.9: [`collections.Counter`](https://python-all.ru/3.9/library/collections.html#collections.Counter) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).11981199#### `class typing.Deque(deque, MutableSequence[T])`12001201Обобщённая версия [`collections.deque`](https://python-all.ru/3.9/library/collections.html#collections.deque).12021203Новое в версии 3.5.4.12041205Новое в версии 3.6.1.12061207Устарело с версии 3.9: [`collections.deque`](https://python-all.ru/3.9/library/collections.html#collections.deque) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).12081209#### Другие конкретные типы12101211#### `class typing.IO`12121213#### `class typing.TextIO`12141215#### `class typing.BinaryIO`12161217Обобщённый тип `IO[AnyStr]` и его подклассы `TextIO(IO[str])` и `BinaryIO(IO[bytes])` представляют типы потоков ввода-вывода, такие как возвращаемые [`open()`](https://python-all.ru/3.9/library/functions.html#open).12181219Устарело с версии 3.8, будет удалено в версии 3.12: Эти типы также находятся в пространстве имён `typing.io`, которое никогда не поддерживалось проверщиками типов и будет удалено.12201221#### `class typing.Pattern`12221223#### `class typing.Match`12241225Эти псевдонимы типов соответствуют возвращаемым типам из [`re.compile()`](https://python-all.ru/3.9/library/re.html#re.compile) и [`re.match()`](https://python-all.ru/3.9/library/re.html#re.match). Эти типы (и соответствующие функции) являются обобщёнными по `AnyStr` и могут быть конкретизированы записью `Pattern[str]`, `Pattern[bytes]`, `Match[str]` или `Match[bytes]`.12261227Устарело с версии 3.8, будет удалено в версии 3.12: Эти типы также находятся в пространстве имён `typing.re`, которое никогда не поддерживалось проверщиками типов и будет удалено.12281229Устарело с версии 3.9: Классы `Pattern` и `Match` из [`re`](https://python-all.ru/3.9/library/re.html#module-re) теперь поддерживают `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).12301231#### `class typing.Text`12321233`Text` – это псевдоним для `str`. Он предоставляется для обеспечения совместимости с кодом Python 2: в Python 2 `Text` является псевдонимом для `unicode`.12341235Используйте `Text`, чтобы указать, что значение должно содержать строку Unicode, совместимую как с Python 2, так и с Python 3:12361237```python1238def add_unicode_checkmark(text: Text) -> Text:1239    return text + u' \u2713'1240```12411242Новое в версии 3.5.2.12431244### Абстрактные базовые классы12451246#### Соответствуют коллекциям из [`collections.abc`](https://python-all.ru/3.9/library/collections.abc.html#module-collections.abc)12471248#### `class typing.AbstractSet(Sized, Collection[T_co])`12491250Обобщённая версия [`collections.abc.Set`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Set).12511252Устарело с версии 3.9: [`collections.abc.Set`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Set) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).12531254#### `class typing.ByteString(Sequence[int])`12551256Обобщённая версия [`collections.abc.ByteString`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ByteString).12571258Этот тип представляет типы [`bytes`](https://python-all.ru/3.9/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.9/library/stdtypes.html#bytearray) и [`memoryview`](https://python-all.ru/3.9/library/stdtypes.html#memoryview) последовательностей байтов.12591260В качестве сокращения для этого типа [`bytes`](https://python-all.ru/3.9/library/stdtypes.html#bytes) можно использовать для аннотации аргументов любого из упомянутых выше типов.12611262Устарело с версии 3.9: [`collections.abc.ByteString`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ByteString) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).12631264#### `class typing.Collection(Sized, Iterable[T_co], Container[T_co])`12651266Обобщённая версия [`collections.abc.Collection`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Collection)12671268Новое в версии 3.6.0.12691270Устарело с версии 3.9: [`collections.abc.Collection`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Collection) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).12711272#### `class typing.Container(Generic[T_co])`12731274Обобщённая версия [`collections.abc.Container`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Container).12751276Устарело с версии 3.9: [`collections.abc.Container`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Container) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).12771278#### `class typing.ItemsView(MappingView, Generic[KT_co, VT_co])`12791280Обобщённая версия [`collections.abc.ItemsView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ItemsView).12811282Устарело с версии 3.9: [`collections.abc.ItemsView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ItemsView) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).12831284#### `class typing.KeysView(MappingView[KT_co], AbstractSet[KT_co])`12851286Обобщённая версия [`collections.abc.KeysView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.KeysView).12871288Устарело с версии 3.9: [`collections.abc.KeysView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.KeysView) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).12891290#### `class typing.Mapping(Sized, Collection[KT], Generic[VT_co])`12911292Обобщённая версия [`collections.abc.Mapping`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Mapping). Этот тип можно использовать следующим образом:12931294```python1295def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:1296    return word_list[word]1297```12981299Устарело с версии 3.9: [`collections.abc.Mapping`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Mapping) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13001301#### `class typing.MappingView(Sized, Iterable[T_co])`13021303Обобщённая версия [`collections.abc.MappingView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MappingView).13041305Устарело с версии 3.9: [`collections.abc.MappingView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MappingView) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13061307#### `class typing.MutableMapping(Mapping[KT, VT])`13081309Обобщённая версия [`collections.abc.MutableMapping`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableMapping).13101311Устарело с версии 3.9: [`collections.abc.MutableMapping`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableMapping) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13121313#### `class typing.MutableSequence(Sequence[T])`13141315Обобщённая версия [`collections.abc.MutableSequence`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableSequence).13161317Устарело с версии 3.9: [`collections.abc.MutableSequence`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableSequence) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13181319#### `class typing.MutableSet(AbstractSet[T])`13201321Обобщённая версия [`collections.abc.MutableSet`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableSet).13221323Устарело с версии 3.9: [`collections.abc.MutableSet`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableSet) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13241325#### `class typing.Sequence(Reversible[T_co], Collection[T_co])`13261327Обобщённая версия [`collections.abc.Sequence`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Sequence).13281329Устарело с версии 3.9: [`collections.abc.Sequence`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Sequence) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13301331#### `class typing.ValuesView(MappingView[VT_co])`13321333Обобщённая версия [`collections.abc.ValuesView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ValuesView).13341335Устарело с версии 3.9: [`collections.abc.ValuesView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ValuesView) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13361337#### Соответствует другим типам в [`collections.abc`](https://python-all.ru/3.9/library/collections.abc.html#module-collections.abc)13381339#### `class typing.Iterable(Generic[T_co])`13401341Обобщённая версия [`collections.abc.Iterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterable).13421343Устарело с версии 3.9: [`collections.abc.Iterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterable) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13441345#### `class typing.Iterator(Iterable[T_co])`13461347Обобщённая версия [`collections.abc.Iterator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterator).13481349Устарело с версии 3.9: [`collections.abc.Iterator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterator) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13501351#### `class typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])`13521353Генератор можно аннотировать обобщённым типом `Generator[YieldType, SendType, ReturnType]`. Например:13541355```python1356def echo_round() -> Generator[int, float, str]:1357    sent = yield 01358    while sent >= 0:1359        sent = yield round(sent)1360    return 'Done'1361```13621363Обратите внимание: в отличие от многих других обобщённых типов в модуле typing, `SendType` из [`Generator`](https://python-all.ru/3.9/library/typing.html#typing.Generator) ведёт себя контравариантно, а не ковариантно или инвариантно.13641365Если ваш генератор будет только выдавать значения, установите `SendType` и `ReturnType` в `None`:13661367```python1368def infinite_stream(start: int) -> Generator[int, None, None]:1369    while True:1370        yield start1371        start += 11372```13731374В качестве альтернативы аннотируйте генератор как имеющий тип возвращаемого значения либо `Iterable[YieldType]`, либо `Iterator[YieldType]`:13751376```python1377def infinite_stream(start: int) -> Iterator[int]:1378    while True:1379        yield start1380        start += 11381```13821383Устарело с версии 3.9: [`collections.abc.Generator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Generator) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13841385#### `class typing.Hashable`13861387Псевдоним для [`collections.abc.Hashable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Hashable).13881389#### `class typing.Reversible(Iterable[T_co])`13901391Обобщённая версия [`collections.abc.Reversible`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Reversible).13921393Устарело с версии 3.9: [`collections.abc.Reversible`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Reversible) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).13941395#### `class typing.Sized`13961397Псевдоним для [`collections.abc.Sized`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Sized).13981399#### Асинхронное программирование14001401#### `class typing.Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co])`14021403Обобщённая версия [`collections.abc.Coroutine`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Coroutine). Вариантность и порядок переменных типа соответствуют таковым у [`Generator`](https://python-all.ru/3.9/library/typing.html#typing.Generator), например:14041405```python1406from collections.abc import Coroutine1407c: Coroutine[list[str], str, int]  # Некоторая корутина, определённая в другом месте.1408x = c.send('hi')                   # Выведенный тип 'x' – list[str].1409async def bar() -> None:1410    y = await c                    # Выведенный тип 'y' – int.1411```14121413Новое в версии 3.5.3.14141415Устарело с версии 3.9: [`collections.abc.Coroutine`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Coroutine) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).14161417#### `class typing.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])`14181419Асинхронный генератор можно аннотировать обобщённым типом `AsyncGenerator[YieldType, SendType]`. Например:14201421```python1422async def echo_round() -> AsyncGenerator[int, float]:1423    sent = yield 01424    while sent >= 0.0:1425        rounded = await round(sent)1426        sent = yield rounded1427```14281429В отличие от обычных генераторов, асинхронные генераторы не могут возвращать значение, поэтому параметр типа `ReturnType` отсутствует. Как и в случае с [`Generator`](https://python-all.ru/3.9/library/typing.html#typing.Generator), `SendType` ведёт себя контравариантно.14301431Если генератор только выдаёт значения, установите `SendType` в `None`:14321433```python1434async def infinite_stream(start: int) -> AsyncGenerator[int, None]:1435    while True:1436        yield start1437        start = await increment(start)1438```14391440В качестве альтернативы аннотируйте генератор как имеющий тип возвращаемого значения либо `AsyncIterable[YieldType]`, либо `AsyncIterator[YieldType]`:14411442```python1443async def infinite_stream(start: int) -> AsyncIterator[int]:1444    while True:1445        yield start1446        start = await increment(start)1447```14481449Новое в версии 3.6.1.14501451Устарело с версии 3.9: [`collections.abc.AsyncGenerator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.AsyncGenerator) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).14521453#### `class typing.AsyncIterable(Generic[T_co])`14541455Обобщённая версия [`collections.abc.AsyncIterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.AsyncIterable).14561457Новое в версии 3.5.2.14581459Устарело с версии 3.9: [`collections.abc.AsyncIterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.AsyncIterable) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).14601461#### `class typing.AsyncIterator(AsyncIterable[T_co])`14621463Обобщённая версия [`collections.abc.AsyncIterator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.AsyncIterator).14641465Новое в версии 3.5.2.14661467Устарело с версии 3.9: [`collections.abc.AsyncIterator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.AsyncIterator) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).14681469#### `class typing.Awaitable(Generic[T_co])`14701471Обобщённая версия [`collections.abc.Awaitable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Awaitable).14721473Новое в версии 3.5.2.14741475Устарело с версии 3.9: [`collections.abc.Awaitable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Awaitable) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).14761477#### Типы контекстных менеджеров14781479#### `class typing.ContextManager(Generic[T_co])`14801481Обобщённая версия [`contextlib.AbstractContextManager`](https://python-all.ru/3.9/library/contextlib.html#contextlib.AbstractContextManager).14821483Новое в версии 3.5.4.14841485Новое в версии 3.6.0.14861487Устарело с версии 3.9: [`contextlib.AbstractContextManager`](https://python-all.ru/3.9/library/contextlib.html#contextlib.AbstractContextManager) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).14881489#### `class typing.AsyncContextManager(Generic[T_co])`14901491Обобщённая версия [`contextlib.AbstractAsyncContextManager`](https://python-all.ru/3.9/library/contextlib.html#contextlib.AbstractAsyncContextManager).14921493Новое в версии 3.5.4.14941495Новое в версии 3.6.2.14961497Устарело с версии 3.9: [`contextlib.AbstractAsyncContextManager`](https://python-all.ru/3.9/library/contextlib.html#contextlib.AbstractAsyncContextManager) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias).14981499### Протоколы15001501Эти протоколы декорированы [`runtime_checkable()`](https://python-all.ru/3.9/library/typing.html#typing.runtime_checkable).15021503#### `class typing.SupportsAbs`15041505ABC с одним абстрактным методом `__abs__`, ковариантным по типу возвращаемого значения.15061507#### `class typing.SupportsBytes`15081509ABC с одним абстрактным методом `__bytes__`.15101511#### `class typing.SupportsComplex`15121513ABC с одним абстрактным методом `__complex__`.15141515#### `class typing.SupportsFloat`15161517ABC с одним абстрактным методом `__float__`.15181519#### `class typing.SupportsIndex`15201521ABC с одним абстрактным методом `__index__`.15221523Новое в версии 3.8.15241525#### `class typing.SupportsInt`15261527ABC с одним абстрактным методом `__int__`.15281529#### `class typing.SupportsRound`15301531ABC с одним абстрактным методом `__round__` ковариантным по возвращаемому типу.15321533### Функции и декораторы15341535#### `typing.cast(typ, val)`15361537Приводит значение к типу.15381539Это возвращает значение без изменений. Для проверщика типов это сигнализирует, что возвращаемое значение имеет указанный тип, но во время выполнения мы намеренно ничего не проверяем (мы хотим, чтобы это было как можно быстрее).15401541#### `@typing.overload`15421543Декоратор `@overload` позволяет описывать функции и методы, поддерживающие несколько различных комбинаций типов аргументов. За серией определений, декорированных `@overload`, должно следовать ровно одно определение без `@overload` (для той же функции/метода). Определения с `@overload` предназначены только для проверки типов, так как они будут перезаписаны определением без `@overload`, которое используется во время выполнения, но должно игнорироваться проверщиком типов. Во время выполнения прямой вызов функции, декорированной `@overload`, вызовет [`NotImplementedError`](https://python-all.ru/3.9/library/exceptions.html#NotImplementedError). Пример перегрузки, дающей более точный тип, чем можно выразить с помощью объединения или переменной типа:15441545```python1546@overload1547def process(response: None) -> None:1548    ...1549@overload1550def process(response: int) -> tuple[int, str]:1551    ...1552@overload1553def process(response: bytes) -> str:1554    ...1555def process(response):1556    <actual implementation>1557```15581559См. [**PEP 484**](https://python-all.ru/3.9/library/typing.html) для подробностей и сравнения с другими семантиками типизации.15601561#### `@typing.final`15621563Декоратор, указывающий проверщикам типов, что декорированный метод нельзя переопределить, а декорированный класс нельзя наследовать. Например:15641565```python1566class Base:1567    @final1568    def done(self) -> None:1569        ...1570class Sub(Base):1571    def done(self) -> None:  # Ошибка, выдаваемая проверщиком типов1572        ...15731574@final1575class Leaf:1576    ...1577class Other(Leaf):  # Ошибка, выдаваемая проверщиком типов1578    ...1579```15801581Проверка этих свойств во время выполнения не выполняется. Подробнее см. [**PEP 591**](https://python-all.ru/3.9/library/typing.html).15821583Новое в версии 3.8.15841585#### `@typing.no_type_check`15861587Декоратор, указывающий, что аннотации не являются подсказками типов.15881589Это работает как декоратор класса или функции [декоратор](https://python-all.ru/3.9/glossary.html#term-decorator). В случае класса он рекурсивно применяется ко всем методам, определённым в этом классе (но не к методам, определённым в его суперклассах или подклассах).15901591Это изменяет функцию(и) на месте.15921593#### `@typing.no_type_check_decorator`15941595Декоратор, придающий другому декоратору эффект [`no_type_check()`](https://python-all.ru/3.9/library/typing.html#typing.no_type_check).15961597Он оборачивает декоратор чем-то, что оборачивает декорированную функцию в [`no_type_check()`](https://python-all.ru/3.9/library/typing.html#typing.no_type_check).15981599#### `@typing.type_check_only`16001601Декоратор, помечающий класс или функцию как недоступные во время выполнения.16021603Сам этот декоратор недоступен во время выполнения. Он в основном предназначен для пометки классов, определённых в файлах заглушек типов (type stub), если реализация возвращает экземпляр закрытого класса:16041605```python1606@type_check_only1607class Response:  # приватный или недоступный во время выполнения1608    code: int1609    def get_header(self, name: str) -> str: ...16101611def fetch_response() -> Response: ...1612```16131614Обратите внимание, что возврат экземпляров закрытых классов не рекомендуется. Обычно предпочтительнее делать такие классы открытыми.16151616### Вспомогательные функции для интроспекции16171618#### `typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False)`16191620Возвращает словарь, содержащий аннотации типов для функции, метода, модуля или объекта класса.16211622Это часто совпадает с `obj.__annotations__`. Кроме того, прямые ссылки, закодированные как строковые литералы, обрабатываются путём вычисления их в пространствах имён `globals` и `locals`. При необходимости `Optional[t]` добавляется для аннотаций функций и методов, если задано значение по умолчанию, равное `None`. Для класса `C` возвращается словарь, построенный объединением всех `__annotations__` по `C.__mro__` в обратном порядке.16231624Функция рекурсивно заменяет все `Annotated[T, ...]` на `T`, если только `include_extras` не установлено в `True` (см. [`Annotated`](https://python-all.ru/3.9/library/typing.html#typing.Annotated) для получения дополнительной информации). Например:16251626```python1627class Student(NamedTuple):1628    name: Annotated[str, 'some marker']16291630get_type_hints(Student) == {'name': str}1631get_type_hints(Student, include_extras=False) == {'name': str}1632get_type_hints(Student, include_extras=True) == {1633    'name': Annotated[str, 'some marker']1634}1635```16361637Изменено в версии 3.9: Добавлен параметр `include_extras` в рамках [**PEP 593**](https://python-all.ru/3.9/library/typing.html).16381639#### `typing.get_args(tp)`16401641#### `typing.get_origin(tp)`16421643Предоставляют базовую интроспекцию для обобщённых типов и специальных форм typing.16441645Для объекта типизации вида `X[Y, Z, ...]` эти функции возвращают `X` и `(Y, Z, ...)`. Если `X` является обобщенным псевдонимом для встроенного или [`collections`](https://python-all.ru/3.9/library/collections.html#module-collections) класса, он нормализуется до исходного класса. Если `X` является [`Union`](https://python-all.ru/3.9/library/typing.html#typing.Union) или [`Literal`](https://python-all.ru/3.9/library/typing.html#typing.Literal), содержащимся в другом обобщенном типе, порядок `(Y, Z, ...)` может отличаться от порядка исходных аргументов `[Y, Z, ...]` из-за кеширования типов. Для неподдерживаемых объектов возвращается `None` и `()` соответственно. Примеры:16461647```python1648assert get_origin(Dict[str, int]) is dict1649assert get_args(Dict[int, str]) == (int, str)16501651assert get_origin(Union[int, str]) is Union1652assert get_args(Union[int, str]) == (int, str)1653```16541655Новое в версии 3.8.16561657#### `class typing.ForwardRef`16581659Класс, используемый для внутреннего представления типов строковых прямых ссылок. Например, `List["SomeClass"]` неявно преобразуется в `List[ForwardRef("SomeClass")]`. Этот класс не должен создаваться пользователем, но может использоваться инструментами интроспекции.16601661> **Примечание**1662>1663> обобщённые типы [**PEP 585**](https://python-all.ru/3.9/library/typing.html), такие как `list["SomeClass"]`, не будут неявно преобразовываться в `list[ForwardRef("SomeClass")]` и, следовательно, не будут автоматически разрешаться в `list[SomeClass]`.16641665Новое в версии 3.7.4.16661667### Константа16681669#### `typing.TYPE_CHECKING`16701671Специальная константа, которая считается `True` сторонними статическими проверщиками типов. Во время выполнения она равна `False`. Применение:16721673```python1674if TYPE_CHECKING:1675    import expensive_mod16761677def fun(arg: 'expensive_mod.SomeType') -> None:1678    local_var: expensive_mod.AnotherType = other_fun()1679```16801681Первую аннотацию типа необходимо заключать в кавычки, превращая её в «прямую ссылку» (forward reference), чтобы скрыть ссылку `expensive_mod` от интерпретатора во время выполнения. Аннотации типов для локальных переменных не вычисляются, поэтому вторую аннотацию не нужно заключать в кавычки.16821683> **Примечание**1684>1685> Если используется `from __future__ import annotations`, аннотации не вычисляются во время определения функции. Вместо этого они сохраняются как строки в `__annotations__`. Это избавляет от необходимости заключать аннотацию в кавычки (см. [**PEP 563**](https://python-all.ru/3.9/library/typing.html)).16861687Новое в версии 3.5.2.1688