> **Источник:** https://python-all.ru/3.10/library/typing.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# [`typing`](https://python-all.ru/3.10/library/typing.html#module-typing) – Поддержка аннотаций типов

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

**Исходный код:** [Lib/typing.py](https://python-all.ru/src/3.10/Lib/typing.py)

> **Примечание**
>
> Среда выполнения Python не проверяет аннотации типов функций и переменных. Они могут использоваться сторонними инструментами, такими как средства проверки типов, IDE, линтеры и т. д.

---

Данный модуль предоставляет поддержку аннотаций типов на уровне выполнения. Самая базовая поддержка включает типы [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any), [`Union`](https://python-all.ru/3.10/library/typing.html#typing.Union), [`Callable`](https://python-all.ru/3.10/library/typing.html#typing.Callable), [`TypeVar`](https://python-all.ru/3.10/library/typing.html#typing.TypeVar) и [`Generic`](https://python-all.ru/3.10/library/typing.html#typing.Generic). Полную спецификацию см. в [**PEP 484**](https://python-all.ru/3.10/library/typing.html). Для упрощённого введения в аннотации типов см. [**PEP 483**](https://python-all.ru/3.10/library/typing.html).

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

```python
def greeting(name: str) -> str:
    return 'Hello ' + name
```

В функции `greeting` аргумент `name` ожидается типа [`str`](https://python-all.ru/3.10/library/stdtypes.html#str), а возвращаемый тип – [`str`](https://python-all.ru/3.10/library/stdtypes.html#str). Подтипы допускаются в качестве аргументов.

Новые функции часто добавляются в модуль `typing`. Пакет [typing\_extensions](https://python-all.ru/3.10/library/typing.html) предоставляет бэкпорты этих новых функций для старых версий Python.

> **См. также**
>
> Для быстрого ознакомления с аннотациями типов обратитесь к [этому краткому справочнику](https://python-all.ru/3.10/library/typing.html).
>
> Раздел «Справочник по системе типов» из [https://mypy.readthedocs.io/](https://python-all.ru/3.10/library/typing.html) – поскольку система аннотаций Python стандартизирована через PEP, данный справочник должен быть в целом применим к большинству проверяющих типы, хотя некоторые части могут по-прежнему относиться к mypy.
>
> Документация на [https://typing.readthedocs.io/](https://python-all.ru/3.10/library/typing.html) служит полезным справочником по возможностям системы типов, полезным инструментам для аннотаций и лучшим практикам.

## Соответствующие PEP

С момента первого появления аннотаций типов в [**PEP 484**](https://python-all.ru/3.10/library/typing.html) и [**PEP 483**](https://python-all.ru/3.10/library/typing.html) ряд PEP изменил и расширил инфраструктуру Python для аннотаций типов. К ним относятся:

- **[**PEP 526**](https://python-all.ru/3.10/library/typing.html): Синтаксис аннотаций переменных**

  *Вводит* синтаксис аннотирования переменных вне определений функций, а также [`ClassVar`](https://python-all.ru/3.10/library/typing.html#typing.ClassVar)
- **[**PEP 544**](https://python-all.ru/3.10/library/typing.html): Протоколы: структурная типизация (статическая утиная типизация)**

  *Вводит* [`Protocol`](https://python-all.ru/3.10/library/typing.html#typing.Protocol) и декоратор [`@runtime_checkable`](https://python-all.ru/3.10/library/typing.html#typing.runtime_checkable)
- **[**PEP 585**](https://python-all.ru/3.10/library/typing.html): Обобщённые типы в стандартных коллекциях**

  *Вводит* [`types.GenericAlias`](https://python-all.ru/3.10/library/types.html#types.GenericAlias) и возможность использовать классы стандартной библиотеки как [обобщённые типы](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias)
- **[**PEP 586**](https://python-all.ru/3.10/library/typing.html): Литеральные типы**

  *Представлен* [`Literal`](https://python-all.ru/3.10/library/typing.html#typing.Literal)
- **[**PEP 589**](https://python-all.ru/3.10/library/typing.html): TypedDict: аннотации типов для словарей с фиксированным набором ключей**

  *Представлен* [`TypedDict`](https://python-all.ru/3.10/library/typing.html#typing.TypedDict)
- **[**PEP 591**](https://python-all.ru/3.10/library/typing.html): Добавление квалификатора final в typing**

  *Вводит* [`Final`](https://python-all.ru/3.10/library/typing.html#typing.Final) и декоратор [`@final`](https://python-all.ru/3.10/library/typing.html#typing.final)
- **[**PEP 593**](https://python-all.ru/3.10/library/typing.html): Гибкие аннотации функций и переменных**

  *Представлен* [`Annotated`](https://python-all.ru/3.10/library/typing.html#typing.Annotated)
- **[**PEP 604**](https://python-all.ru/3.10/library/typing.html): Разрешение записи объединённых типов как `X | Y`**

  *Вводит* [`types.UnionType`](https://python-all.ru/3.10/library/types.html#types.UnionType) и возможность использовать бинарный оператор ИЛИ `|` для обозначения [объединения типов](https://python-all.ru/3.10/library/stdtypes.html#types-union)
- **[**PEP 612**](https://python-all.ru/3.10/library/typing.html): Переменные спецификации параметров**

  *Представлен* [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec) и [`Concatenate`](https://python-all.ru/3.10/library/typing.html#typing.Concatenate)
- **[**PEP 613**](https://python-all.ru/3.10/library/typing.html): Явные псевдонимы типов**

  *Представлен* [`TypeAlias`](https://python-all.ru/3.10/library/typing.html#typing.TypeAlias)
- **[**PEP 647**](https://python-all.ru/3.10/library/typing.html): Защитники типов, определяемые пользователем**

  *Представлен* [`TypeGuard`](https://python-all.ru/3.10/library/typing.html#typing.TypeGuard)

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

Псевдоним типа определяется присваиванием типа псевдониму. В этом примере `Vector` и `list[float]` будут рассматриваться как взаимозаменяемые синонимы:

```python
Vector = list[float]

def scale(scalar: float, vector: Vector) -> Vector:
    return [scalar * num for num in vector]

# проходит проверку типов; список чисел с плавающей точкой считается Vector.
new_vector = scale(2.0, [1.0, -4.2, 5.4])
```

Псевдонимы типов полезны для упрощения сложных сигнатур типов. Например:

```python
from collections.abc import Sequence

ConnectionOptions = dict[str, str]
Address = tuple[str, int]
Server = tuple[Address, ConnectionOptions]

def broadcast_message(message: str, servers: Sequence[Server]) -> None:
    ...

# Статическая проверка типов будет считать предыдущую сигнатуру типа как
# полностью эквивалентную этой.
def broadcast_message(
        message: str,
        servers: Sequence[tuple[tuple[str, int], dict[str, str]]]) -> None:
    ...
```

Обратите внимание, что `None` как аннотация типа является особым случаем и заменяется на `type(None)`.

## NewType

Используйте вспомогательную функцию [`NewType`](https://python-all.ru/3.10/library/typing.html#typing.NewType) для создания отдельных типов:

```python
from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)
```

Статический проверщик типов будет рассматривать новый тип как подкласс исходного типа. Это полезно для выявления логических ошибок:

```python
def get_user_name(user_id: UserId) -> str:
    ...

# проходит проверку типов
user_a = get_user_name(UserId(42351))

# не проходит проверку типов; int не является UserId
user_b = get_user_name(-1)
```

Можно по-прежнему выполнять все операции `int` над переменной типа `UserId`, но результат всегда будет типа `int`. Это позволяет передавать `UserId` везде, где может ожидаться `int`, но предотвращает случайное создание `UserId` недопустимым способом:

```python
# 'output' имеет тип 'int', а не 'UserId'
output = UserId(23413) + UserId(54341)
```

Обратите внимание, что эти проверки выполняются только статическим проверщиком типов. Во время выполнения оператор `Derived = NewType('Derived', Base)` сделает `Derived` вызываемым объектом, который немедленно возвращает любой переданный ему параметр. Это означает, что выражение `Derived(some_value)` не создаёт новый класс и не вносит значительных накладных расходов по сравнению с обычным вызовом функции.

Точнее, выражение `some_value is Derived(some_value)` во время выполнения всегда истинно.

Недопустимо создание подтипа `Derived`:

```python
from typing import NewType

UserId = NewType('UserId', int)

# Завершается ошибкой во время выполнения и не проходит проверку типов
class AdminUserId(UserId): pass
```

Однако можно создать [`NewType`](https://python-all.ru/3.10/library/typing.html#typing.NewType) на основе «производного» `NewType`:

```python
from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)
```

и проверка типов для `ProUserId` будет работать как ожидается.

Подробнее см. [**PEP 484**](https://python-all.ru/3.10/library/typing.html).

> **Примечание**
>
> Напомним, что использование псевдонима типа объявляет два типа *эквивалентными* друг другу. Использование `Alias = Original` заставит статический анализатор типов считать `Alias` *точно эквивалентным* `Original` во всех случаях. Это полезно, когда требуется упростить сложные сигнатуры типов.
>
> В отличие от этого, `NewType` объявляет один тип *подтипом* другого. Использование `Derived = NewType('Derived', Original)` заставит статический анализатор типов считать `Derived` *подклассом* `Original`, что означает, что значение типа `Original` не может использоваться там, где ожидается значение типа `Derived`. Это полезно для предотвращения логических ошибок с минимальными затратами времени выполнения.

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

Изменено в версии 3.10: `NewType` теперь является классом, а не функцией. Вызов `NewType` вместо обычной функции влечёт некоторые дополнительные накладные расходы во время выполнения. Однако эти расходы будут уменьшены в версии 3.11.0.

## Callable

Фреймворки, ожидающие функции обратного вызова с определённой сигнатурой, могут быть аннотированы с помощью `Callable[[Arg1Type, Arg2Type], ReturnType]`.

Например:

```python
from collections.abc import Callable

def feeder(get_next_item: Callable[[], str]) -> None:
    # Тело

def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    # Тело

async def on_update(value: str) -> None:
    # Тело
callback: Callable[[str], Awaitable[None]] = on_update
```

Можно объявить возвращаемый тип вызываемого объекта, не указывая сигнатуру вызова, заменив список аргументов многоточием в аннотации типа: `Callable[..., ReturnType]`.

Объекты, принимающие другие вызываемые объекты в качестве аргументов, могут указать, что их типы параметров зависят друг от друга, с помощью [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec). Кроме того, если такой вызываемый объект добавляет или удаляет аргументы из других вызываемых объектов, может использоваться оператор [`Concatenate`](https://python-all.ru/3.10/library/typing.html#typing.Concatenate). Они имеют соответственно форму `Callable[ParamSpecVariable, ReturnType]` и `Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType]`.

Changed in version 3.10: `Callable` now supports [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec) and [`Concatenate`](https://python-all.ru/3.10/library/typing.html#typing.Concatenate). See [**PEP 612**](https://python-all.ru/3.10/library/typing.html) for more details.

> **См. также**
>
> В документации к [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec) и [`Concatenate`](https://python-all.ru/3.10/library/typing.html#typing.Concatenate) приведены примеры использования в `Callable`.

## Обобщённые типы

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

```python
from collections.abc import Mapping, Sequence

def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...
```

Обобщённые типы можно параметризовать с помощью фабрики, доступной в typing под названием [`TypeVar`](https://python-all.ru/3.10/library/typing.html#typing.TypeVar).

```python
from collections.abc import Sequence
from typing import TypeVar

T = TypeVar('T')      # Объявить переменную типа

def first(l: Sequence[T]) -> T:   # Обобщённая функция
    return l[0]
```

## Пользовательские обобщённые типы

Пользовательский класс можно определить как обобщённый класс.

```python
from typing import TypeVar, Generic
from logging import Logger

T = TypeVar('T')

class LoggedVar(Generic[T]):
    def __init__(self, value: T, name: str, logger: Logger) -> None:
        self.name = name
        self.logger = logger
        self.value = value

    def set(self, new: T) -> None:
        self.log('Set ' + repr(self.value))
        self.value = new

    def get(self) -> T:
        self.log('Get ' + repr(self.value))
        return self.value

    def log(self, message: str) -> None:
        self.logger.info('%s: %s', self.name, message)
```

`Generic[T]` в качестве базового класса определяет, что класс `LoggedVar` принимает один параметр типа `T`. Это также делает `T` допустимым типом внутри тела класса.

Базовый класс [`Generic`](https://python-all.ru/3.10/library/typing.html#typing.Generic) определяет [`__class_getitem__()`](https://python-all.ru/3.10/reference/datamodel.html#object.__class_getitem__) так, что `LoggedVar[T]` является допустимым типом:

```python
from collections.abc import Iterable

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
    for var in vars:
        var.set(0)
```

Обобщённый тип может иметь любое количество переменных типа. Все разновидности [`TypeVar`](https://python-all.ru/3.10/library/typing.html#typing.TypeVar) допустимы в качестве параметров обобщённого типа:

```python
from typing import TypeVar, Generic, Sequence

T = TypeVar('T', contravariant=True)
B = TypeVar('B', bound=Sequence[bytes], covariant=True)
S = TypeVar('S', int, str)

class WeirdTrio(Generic[T, B, S]):
    ...
```

Каждый аргумент-переменная типа для [`Generic`](https://python-all.ru/3.10/library/typing.html#typing.Generic) должен быть уникальным. Поэтому такой код некорректен:

```python
from typing import TypeVar, Generic
...

T = TypeVar('T')

class Pair(Generic[T, T]):   # INVALID
    ...
```

Можно использовать множественное наследование с [`Generic`](https://python-all.ru/3.10/library/typing.html#typing.Generic):

```python
from collections.abc import Sized
from typing import TypeVar, Generic

T = TypeVar('T')

class LinkedList(Sized, Generic[T]):
    ...
```

При наследовании от обобщённых классов некоторые переменные типа могут быть зафиксированы:

```python
from collections.abc import Mapping
from typing import TypeVar

T = TypeVar('T')

class MyDict(Mapping[str, T]):
    ...
```

В этом случае `MyDict` имеет один параметр – `T`.

Использование обобщённого класса без указания параметров типа подразумевает [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any) для каждой позиции. В следующем примере `MyIterable` не является обобщённым, но неявно наследуется от `Iterable[Any]`:

```python
from collections.abc import Iterable

class MyIterable(Iterable): # То же, что и Iterable[Any].
```

Пользовательские обобщённые псевдонимы типов также поддерживаются. Примеры:

```python
from collections.abc import Iterable
from typing import TypeVar
S = TypeVar('S')
Response = Iterable[S] | int

# Тип возвращаемого значения здесь такой же, как Iterable[str] | int
def response(query: str) -> Response[str]:
    ...

T = TypeVar('T', int, float, complex)
Vec = Iterable[tuple[T, T]]

def inproduct(v: Vec[T]) -> T: # То же, что и Iterable[tuple[T, T]]
    return sum(x*y for x, y in v)
```

Изменено в версии 3.7: [`Generic`](https://python-all.ru/3.10/library/typing.html#typing.Generic) больше не имеет собственного метакласса.

Пользовательские обобщённые типы для выражений параметров также поддерживаются через переменные спецификации параметров в форме `Generic[P]`. Поведение согласуется с описанными выше переменными типов, так как переменные спецификации параметров обрабатываются модулем typing как специализированные переменные типов. Единственное исключение состоит в том, что список типов может использоваться для подстановки [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec):

```python
>>> from typing import Generic, ParamSpec, TypeVar

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

>>> class Z(Generic[T, P]): ...
...
>>> Z[int, [dict, float]]
__main__.Z[int, (<class 'dict'>, <class 'float'>)]
```

Кроме того, обобщённый (generic) с единственной переменной спецификации параметра будет принимать списки параметров в виде `X[[Type1, Type2, ...]]`, а также `X[Type1, Type2, ...]` из эстетических соображений. Внутренне последний преобразуется в первый, поэтому следующие эквивалентны:

```python
>>> class X(Generic[P]): ...
...
>>> X[int, str]
__main__.X[(<class 'int'>, <class 'str'>)]
>>> X[[int, str]]
__main__.X[(<class 'int'>, <class 'str'>)]
```

Обратите внимание, что обобщённые типы с [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec) могут иметь некорректный `__parameters__` после подстановки в некоторых случаях, так как они предназначены в первую очередь для статической проверки типов.

Изменено в версии 3.10: [`Generic`](https://python-all.ru/3.10/library/typing.html#typing.Generic) теперь можно параметризовать по выражениям параметров. Подробнее см. [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec) и [**PEP 612**](https://python-all.ru/3.10/library/typing.html).

Пользовательский обобщённый класс может иметь ABC в качестве базовых классов без конфликта метаклассов. Обобщённые метаклассы не поддерживаются. Результат параметризации обобщённых типов кэшируется, и большинство типов в модуле typing являются [хэшируемыми](https://python-all.ru/3.10/glossary.html#term-hashable) и сравнимыми на равенство.

## Тип [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any)

Особым видом типа является [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any). Статический проверяющий типов будет считать каждый тип совместимым с [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any), а [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any) – совместимым с каждым типом.

Это означает, что над значением типа [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any) можно выполнять любые операции или вызовы методов и присваивать его любой переменной:

```python
from typing import Any

a: Any = None
a = []          # ОК
a = 2           # ОК

s: str = ''
s = a           # ОК

def foo(item: Any) -> int:
    # Проходит проверку типов; 'item' может быть любого типа,
    # и этот тип может иметь метод 'bar'
    item.bar()
    ...
```

Обратите внимание: при присваивании значения типа [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any) более точному типу проверка типов не выполняется. Например, статический анализатор типов не сообщил об ошибке при присваивании `a` переменной `s`, хотя `s` была объявлена как тип [`str`](https://python-all.ru/3.10/library/stdtypes.html#str) и во время выполнения получает значение [`int`](https://python-all.ru/3.10/library/functions.html#int)!

Кроме того, все функции без указания типа возврата или типов параметров по умолчанию неявно используют [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any):

```python
def legacy_parser(text):
    ...
    return data

# Статический проверщик типов будет рассматривать вышеприведенное
# как имеющее ту же сигнатуру, что и:
def legacy_parser(text: Any) -> Any:
    ...
    return data
```

Такое поведение позволяет использовать [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any) в качестве *запасного выхода*, когда нужно смешивать динамически и статически типизированный код.

Сравните поведение [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any) с поведением [`object`](https://python-all.ru/3.10/library/functions.html#object). Как и [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any), каждый тип является подтипом [`object`](https://python-all.ru/3.10/library/functions.html#object). Однако, в отличие от [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any), обратное неверно: [`object`](https://python-all.ru/3.10/library/functions.html#object) *не* является подтипом любого другого типа.

Это означает, что когда тип значения – [`object`](https://python-all.ru/3.10/library/functions.html#object), проверяющий типы будет отклонять почти все операции над ним, а присваивание его переменной (или использование в качестве возвращаемого значения) более специализированного типа является ошибкой типа. Например:

```python
def hash_a(item: object) -> int:
    # Не проходит проверку типов; у объекта нет метода 'magic'.
    item.magic()
    ...

def hash_b(item: Any) -> int:
    # Проходит проверку типов
    item.magic()
    ...

# Проходит проверку типов, так как int и str являются подклассами object
hash_a(42)
hash_a("foo")

# Проходит проверку типов, так как Any совместим со всеми типами
hash_b(42)
hash_b("foo")
```

Используйте [`object`](https://python-all.ru/3.10/library/functions.html#object), чтобы указать, что значение может быть любого типа в типобезопасной манере. Используйте [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any), чтобы указать, что значение динамически типизировано.

## Номинальная и структурная типизация

Изначально [**PEP 484**](https://python-all.ru/3.10/library/typing.html) определял систему статической типизации Python как использующую *номинальное подтипирование*. Это означает, что класс `A` разрешён там, где ожидается класс `B`, если и только если `A` является подклассом `B`.

Ранее это требование также применялось к абстрактным базовым классам, таким как [`Iterable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Iterable). Проблема такого подхода в том, что класс должен быть явно помечен для их поддержки, что непитонично и не похоже на то, что обычно делается в идиоматическом динамически типизированном коде Python. Например, следующее соответствует [**PEP 484**](https://python-all.ru/3.10/library/typing.html):

```python
from collections.abc import Sized, Iterable, Iterator

class Bucket(Sized, Iterable[int]):
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...
```

[**PEP 544**](https://python-all.ru/3.10/library/typing.html) позволяет решить эту проблему, разрешая пользователям писать приведённый выше код без явных базовых классов в определении класса, что позволяет `Bucket` неявно считаться подтипом как `Sized`, так и `Iterable[int]` статическими проверяющими типов. Это называется *структурной подтипизацией* (или статической утиной типизацией):

```python
from collections.abc import Iterator, Iterable

class Bucket:  # Примечание: базовые классы отсутствуют
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

def collect(items: Iterable[int]) -> int: ...
result = collect(Bucket())  # Проходит проверку типов
```

Более того, наследуя специальный класс [`Protocol`](https://python-all.ru/3.10/library/typing.html#typing.Protocol), пользователь может определять новые пользовательские протоколы, чтобы в полной мере использовать структурное подтипирование (см. примеры ниже).

## Содержимое модуля

Модуль определяет следующие классы, функции и декораторы.

> **Примечание**
>
> Данный модуль определяет несколько типов, которые являются подклассами уже существующих классов стандартной библиотеки и которые также расширяют [`Generic`](https://python-all.ru/3.10/library/typing.html#typing.Generic) для поддержки переменных типа внутри `[]`. Эти типы стали избыточными в Python 3.9, когда соответствующие существовавшие классы были расширены для поддержки `[]`.
>
> Избыточные типы объявлены устаревшими начиная с Python 3.9, но интерпретатор не будет выдавать предупреждений об устаревании. Ожидается, что средства проверки типов будут помечать устаревшие типы, если проверяемая программа нацелена на Python 3.9 или новее.
>
> Устаревшие типы будут удалены из модуля [`typing`](https://python-all.ru/3.10/library/typing.html#module-typing) в первой версии Python, выпущенной через 5 лет после выхода Python 3.9.0. Подробнее см. в [**PEP 585**](https://python-all.ru/3.10/library/typing.html)–*Аннотации обобщённых типов в стандартных коллекциях*.

### Специальные примитивы типизации

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

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

#### `typing.Any`

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

- Каждый тип совместим с [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any).
- [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any) совместим с каждым типом.

#### `typing.NoReturn`

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

```python
from typing import NoReturn

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

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

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

#### `typing.TypeAlias`

Специальная аннотация для явного объявления [псевдонима типа](https://python-all.ru/3.10/library/typing.html#type-aliases). Например:

```python
from typing import TypeAlias

Factors: TypeAlias = list[int]
```

См. [**PEP 613**](https://python-all.ru/3.10/library/typing.html) для получения дополнительных сведений о явных псевдонимах типов.

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

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

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

#### `typing.Tuple`

Тип кортежа; `Tuple[X, Y]` – это тип кортежа из двух элементов, где первый элемент имеет тип X, а второй – Y. Тип пустого кортежа может быть записан как `Tuple[()]`.

Пример: `Tuple[T1, T2]` – это кортеж из двух элементов, соответствующих переменным типа T1 и T2. `Tuple[int, float, str]` – это кортеж из int, float и строки.

Чтобы задать кортеж переменной длины из однотипных элементов, используйте литеральное многоточие, например `Tuple[int, ...]`. Простой [`Tuple`](https://python-all.ru/3.10/library/typing.html#typing.Tuple) эквивалентен `Tuple[Any, ...]`, а тот, в свою очередь, [`tuple`](https://python-all.ru/3.10/library/stdtypes.html#tuple).

Deprecated since version 3.9: [`builtins.tuple`](https://python-all.ru/3.10/library/stdtypes.html#tuple) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `typing.Union`

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

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

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

  ```python
  Union[Union[int, str], float] == Union[int, str, float]
  ```
- Объединения из одного аргумента исчезают, например:

  ```python
  Union[int] == int  # Конструктор на самом деле возвращает int
  ```
- Повторяющиеся аргументы пропускаются, например:

  ```python
  Union[int, str, int] == Union[int, str] == int | str
  ```
- При сравнении объединений порядок аргументов игнорируется, например:

  ```python
  Union[int, str] == Union[str, int]
  ```
- Нельзя наследовать или создавать экземпляр `Union`.
- Нельзя записать `Union[X][Y]`.

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

Изменено в версии 3.10: Объединения теперь можно записывать как `X | Y`. См. [выражения типов объединений](https://python-all.ru/3.10/library/stdtypes.html#types-union).

#### `typing.Optional`

Тип Optional.

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

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

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

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

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

Изменено в версии 3.10: Optional теперь можно записывать как `X | None`. См. [выражения типов объединений](https://python-all.ru/3.10/library/stdtypes.html#types-union).

#### `typing.Callable`

Тип Callable; `Callable[[int], str]` – это функция вида (int) -\> str.

Синтаксис индексирования всегда должен использоваться ровно с двумя значениями: списком аргументов и типом возвращаемого значения. Список аргументов должен быть списком типов или многоточием; тип возвращаемого значения должен быть одним типом.

Нет синтаксиса для указания необязательных или именованных аргументов; такие типы функций редко используются в качестве типов колбэков. `Callable[..., ReturnType]` (буквальное многоточие) можно использовать для аннотации вызываемого объекта, принимающего любое количество аргументов и возвращающего `ReturnType`. Обычное [`Callable`](https://python-all.ru/3.10/library/typing.html#typing.Callable) эквивалентно `Callable[..., Any]`, а в свою очередь – [`collections.abc.Callable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Callable).

Объекты, принимающие другие вызываемые объекты в качестве аргументов, могут указать, что их типы параметров зависят друг от друга, с помощью [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec). Кроме того, если такой вызываемый объект добавляет или удаляет аргументы из других вызываемых объектов, может использоваться оператор [`Concatenate`](https://python-all.ru/3.10/library/typing.html#typing.Concatenate). Они имеют соответственно форму `Callable[ParamSpecVariable, ReturnType]` и `Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType]`.

Deprecated since version 3.9: [`collections.abc.Callable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Callable) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

Changed in version 3.10: `Callable` now supports [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec) and [`Concatenate`](https://python-all.ru/3.10/library/typing.html#typing.Concatenate). See [**PEP 612**](https://python-all.ru/3.10/library/typing.html) for more details.

> **См. также**
>
> Документация по [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec) и [`Concatenate`](https://python-all.ru/3.10/library/typing.html#typing.Concatenate) содержит примеры использования с `Callable`.

#### `typing.Concatenate`

Используется с [`Callable`](https://python-all.ru/3.10/library/typing.html#typing.Callable) и [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec) для аннотации типа вызываемого объекта высшего порядка, который добавляет, удаляет или преобразует параметры другого вызываемого объекта. Использование в форме `Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]`. `Concatenate` в настоящее время допустим только при использовании в качестве первого аргумента [`Callable`](https://python-all.ru/3.10/library/typing.html#typing.Callable). Последний параметр `Concatenate` должен быть [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec).

Например, чтобы аннотировать декоратор `with_lock`, который предоставляет [`threading.Lock`](https://python-all.ru/3.10/library/threading.html#threading.Lock) декорируемой функции, можно использовать `Concatenate`, чтобы указать, что `with_lock` ожидает вызываемый объект, который принимает `Lock` в качестве первого аргумента, и возвращает вызываемый объект с другой сигнатурой типа. В этом случае [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec) указывает на то, что типы параметров возвращаемого вызываемого объекта зависят от типов параметров передаваемого вызываемого объекта:

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

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

# Используйте эту блокировку, чтобы гарантировать, что только один поток выполняет функцию
# в любой момент времени.
my_lock = Lock()

def with_lock(f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
    '''Типобезопасный декоратор, предоставляющий блокировку.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        # Передайте блокировку в качестве первого аргумента.
        return f(my_lock, *args, **kwargs)
    return inner

@with_lock
def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:
    '''Складывайте список чисел потокобезопасным способом.'''
    with lock:
        return sum(numbers)

# Нам не нужно передавать блокировку вручную благодаря декоратору.
sum_threadsafe([1.1, 2.2, 3.3])
```

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

> **См. также**
>
> - [**PEP 612**](https://python-all.ru/3.10/library/typing.html) – переменные спецификации параметров (PEP, который ввёл `ParamSpec` и `Concatenate`).
> - [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec) и [`Callable`](https://python-all.ru/3.10/library/typing.html#typing.Callable).

#### `class typing.Type(Generic[CT_co])`

Переменная, аннотированная `C`, может принимать значение типа `C`. Напротив, переменная, аннотированная `Type[C]`, может принимать значения, которые сами являются классами – а именно, она принимает *объект класса* `C`. Например:

```python
a = 3         # Имеет тип 'int'
b = int       # Имеет тип 'Type[int]'
c = type(a)   # Также имеет тип 'Type[int]'
```

Обратите внимание, что `Type[C]` ковариантен:

```python
class User: ...
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...

# Принимает User, BasicUser, ProUser, TeamUser, ...
def make_new_user(user_class: Type[User]) -> User:
    # ...
    return user_class()
```

Тот факт, что `Type[C]` ковариантен, подразумевает, что все подклассы `C` должны реализовывать те же сигнатуры конструктора и методов класса, что и `C`. Средство проверки типов должно отмечать нарушения этого, но также должно разрешать вызовы конструкторов в подклассах, которые соответствуют вызовам конструктора в указанном базовом классе. То, как средство проверки типов должно обрабатывать этот конкретный случай, может измениться в будущих версиях [**PEP 484**](https://python-all.ru/3.10/library/typing.html).

Единственными допустимыми параметрами для [`Type`](https://python-all.ru/3.10/library/typing.html#typing.Type) являются классы, [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any), [переменные типа](https://python-all.ru/3.10/library/typing.html#generics) и объединения любых из этих типов. Например:

```python
def new_non_team_user(user_class: Type[BasicUser | ProUser]): ...
```

`Type[Any]` эквивалентен `Type`, который в свою очередь эквивалентен `type`, корню метаклассовой иерархии Python.

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

Deprecated since version 3.9: [`builtins.type`](https://python-all.ru/3.10/library/functions.html#type) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `typing.Literal`

Тип, который можно использовать для указания средствам проверки типов, что соответствующая переменная или параметр функции имеет значение, эквивалентное предоставленному литералу (или одному из нескольких литералов). Например:

```python
def validate_simple(data: Any) -> Literal[True]:  # всегда возвращает True
    ...

MODE = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: MODE) -> str:
    ...

open_helper('/some/path', 'r')  # Проходит проверку типов
open_helper('/other/path', 'typo')  # Ошибка в тайпчекере
```

`Literal[...]` нельзя наследовать. Во время выполнения произвольное значение допускается в качестве аргумента типа для `Literal[...]`, но проверяющие типа могут накладывать ограничения. См. [**PEP 586**](https://python-all.ru/3.10/library/typing.html) для получения дополнительных сведений о литеральных типах.

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

Изменено в версии 3.9.1: `Literal` теперь дедуплицирует параметры. Сравнения на равенство объектов `Literal` больше не зависят от порядка. Объекты `Literal` теперь будут вызывать исключение [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError) при сравнении на равенство, если один из их параметров не является [хешируемым](https://python-all.ru/3.10/glossary.html#term-hashable).

#### `typing.ClassVar`

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

Как представлено в [**PEP 526**](https://python-all.ru/3.10/library/typing.html), аннотация переменной, обёрнутая в ClassVar, указывает, что данный атрибут предназначен для использования в качестве переменной класса и не должен устанавливаться на экземплярах этого класса. Использование:

```python
class Starship:
    stats: ClassVar[dict[str, int]] = {} # переменная класса
    damage: int = 10                     # переменная экземпляра
```

[`ClassVar`](https://python-all.ru/3.10/library/typing.html#typing.ClassVar) принимает только типы и не может быть дополнительно индексирован.

[`ClassVar`](https://python-all.ru/3.10/library/typing.html#typing.ClassVar) сам по себе не является классом и не должен использоваться с [`isinstance()`](https://python-all.ru/3.10/library/functions.html#isinstance) или [`issubclass()`](https://python-all.ru/3.10/library/functions.html#issubclass). [`ClassVar`](https://python-all.ru/3.10/library/typing.html#typing.ClassVar) не меняет поведение Python во время выполнения, но может использоваться сторонними проверяющими типов. Например, проверяющий типов может отметить следующий код как ошибочный:

```python
enterprise_d = Starship(3000)
enterprise_d.stats = {} # Ошибка: установка переменной класса на экземпляре
Starship.stats = {}     # Это корректно.
```

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

#### `typing.Final`

Специальная конструкция типов для указания средствам проверки типов, что имя не может быть переприсвоено или переопределено в подклассе. Например:

```python
MAX_SIZE: Final = 9000
MAX_SIZE += 1  # Ошибка, выдаваемая проверщиком типов

class Connection:
    TIMEOUT: Final[int] = 10

class FastConnector(Connection):
    TIMEOUT = 1  # Ошибка, выдаваемая проверщиком типов
```

Проверка этих свойств во время выполнения не выполняется. Подробнее см. [**PEP 591**](https://python-all.ru/3.10/library/typing.html).

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

#### `typing.Annotated`

Тип, введённый в [**PEP 593**](https://python-all.ru/3.10/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` во время выполнения в рамках конкретного приложения.

В конечном счёте, ответственность за интерпретацию аннотаций (если вообще) лежит на инструменте или библиотеке, встречающей тип `Annotated`. Инструмент или библиотека, встречающие тип `Annotated`, могут просматривать аннотации, чтобы определить, представляют ли они интерес (например, с помощью `isinstance()`).

Когда инструмент или библиотека не поддерживает аннотации или встречает неизвестную аннотацию, она должна просто игнорировать её и обрабатывать аннотированный тип как базовый тип.

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

Поскольку тип `Annotated` позволяет помещать несколько аннотаций одного (или разных) типа на любой узел, инструменты или библиотеки, потребляющие эти аннотации, отвечают за обработку возможных дубликатов. Например, если вы выполняете анализ диапазона значений, вы можете разрешить это:

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

Передача `include_extras=True` в [`get_type_hints()`](https://python-all.ru/3.10/library/typing.html#typing.get_type_hints) позволяет получить доступ к дополнительным аннотациям во время выполнения.

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

- Первый аргумент `Annotated` должен быть допустимым типом
- Поддерживаются несколько аннотаций типов (`Annotated` поддерживает вариадические аргументы):

  ```python
  Annotated[int, ValueRange(3, 10), ctype("char")]
  ```
- `Annotated` должен вызываться как минимум с двумя аргументами ( `Annotated[int]` недействителен)
- Порядок аннотаций сохраняется и важен для проверки на равенство:

  ```python
  Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
      int, ctype("char"), ValueRange(3, 10)
  ]
  ```
- Вложенные типы `Annotated` уплощаются, при этом метаданные упорядочиваются, начиная с самой внутренней аннотации:

  ```python
  Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
      int, ValueRange(3, 10), ctype("char")
  ]
  ```
- Дублирующиеся аннотации не удаляются:

  ```python
  Annotated[int, ValueRange(3, 10)] != Annotated[
      int, ValueRange(3, 10), ValueRange(3, 10)
  ]
  ```
- `Annotated` можно использовать с вложенными и обобщёнными псевдонимами:

  ```python
  T = TypeVar('T')
  Vec = Annotated[list[tuple[T, T]], MaxLen(10)]
  V = Vec[int]

  V == Annotated[list[tuple[int, int]], MaxLen(10)]
  ```

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

#### `typing.TypeGuard`

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

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

```python
def is_str(val: str | float):
    # защита типа "isinstance"
    if isinstance(val, str):
        # Тип ``val`` сужается до ``str``
        ...
    else:
        # Иначе тип ``val`` сужается до ``float``.
        ...
```

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

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

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

Например:

```python
def is_str_list(val: List[object]) -> TypeGuard[List[str]]:
    '''Определяет, все ли объекты в списке являются строками'''
    return all(isinstance(x, str) for x in val)

def func1(val: List[object]):
    if is_str_list(val):
        # Тип ``val`` сужен до ``List[str]``.
        print(" ".join(val))
    else:
        # Тип ``val`` остаётся ``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**](https://python-all.ru/3.10/library/typing.html) для подробностей.

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

#### Построение обобщённых типов

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

#### `class typing.Generic`

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

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

```python
class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
        # И т.д.
```

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

```python
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`

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

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

```python
T = TypeVar('T')  # Может быть чем угодно
S = TypeVar('S', bound=str)  # Может быть любым подтипом str
A = TypeVar('A', str, bytes)  # Должно быть ровно str или bytes
```

Переменные типов существуют в первую очередь для пользы статических средств проверки типов. Они служат параметрами для обобщённых типов, а также для определений обобщённых функций. Смотрите [`Generic`](https://python-all.ru/3.10/library/typing.html#typing.Generic) для получения дополнительной информации об обобщённых типах. Обобщённые функции работают следующим образом:

```python
def repeat(x: T, n: int) -> Sequence[T]:
    """Возвращает список, содержащий n ссылок на x."""
    return [x]*n

def print_capitalized(x: S) -> S:
    """Печатает x с заглавной буквы и возвращает x."""
    print(x.capitalize())
    return x

def concatenate(x: A, y: A) -> A:
    """Складывает две строки или два объекта bytes."""
    return x + y
```

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

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

```python
a = concatenate('one', 'two')  # Ок, переменная 'a' имеет тип 'str'
b = concatenate(StringSubclass('one'), StringSubclass('two'))  # Выведенный тип переменной 'b' – 'str',
                                                               # несмотря на передачу 'StringSubclass'
c = concatenate('one', b'two')  # ошибка: переменная типа 'A' может быть 'str' или 'bytes' при вызове функции, но не оба сразу
```

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

```python
print_capitalized('a string')  # Ок, результат имеет тип 'str'

class StringSubclass(str):
    pass

print_capitalized(StringSubclass('another string'))  # Ок, результат имеет тип 'StringSubclass'
print_capitalized(45)  # ошибка: int не является подтипом str
```

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

```python
U = TypeVar('U', bound=str|bytes)  # Может быть любым подтипом объединения str|bytes
V = TypeVar('V', bound=SupportsAbs)  # Может быть чем угодно с методом __abs__
```

Связанные переменные типов особенно полезны для аннотации [`classmethods`](https://python-all.ru/3.10/library/functions.html#classmethod), которые служат альтернативными конструкторами. В следующем примере (от [Рэймонда Хеттингера](https://python-all.ru/3.10/library/typing.html)) переменная типа `C` привязана к классу `Circle` через использование прямой ссылки. Использование этой переменной типа для аннотации метода класса `with_circumference`, а не жёсткого кодирования возвращаемого типа как `Circle`, означает, что средство проверки типов может правильно вывести возвращаемый тип, даже если метод вызывается на подклассе:

```python
import math

C = TypeVar('C', bound='Circle')

class Circle:
    """Абстрактная окружность"""

    def __init__(self, radius: float) -> None:
        self.radius = radius

    # Используется переменная типа, чтобы показать, что возвращаемый тип
    # всегда будет экземпляром того, чем является ``cls``
    @classmethod
    def with_circumference(cls: type[C], circumference: float) -> C:
        """Создать окружность с указанной длиной окружности"""
        radius = circumference / (math.pi * 2)
        return cls(radius)

class Tire(Circle):
    """Специализированная окружность (из резины)"""

    MATERIAL = 'rubber'

c = Circle.with_circumference(3)  # Ок, переменная 'c' имеет тип 'Circle'
t = Tire.with_circumference(4)  # Ок, переменная 't' имеет тип 'Tire' (не 'Circle')
```

Во время выполнения `isinstance(x, T)` вызовет [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError). В общем, [`isinstance()`](https://python-all.ru/3.10/library/functions.html#isinstance) и [`issubclass()`](https://python-all.ru/3.10/library/functions.html#issubclass) не должны использоваться с типами.

Переменные типа могут быть помечены как ковариантные или контравариантные путём передачи `covariant=True` или `contravariant=True`. См. [**PEP 484**](https://python-all.ru/3.10/library/typing.html) для получения дополнительных сведений. По умолчанию переменные типа инвариантны.

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

Переменная спецификации параметров. Специализированная версия [`type variables`](https://python-all.ru/3.10/library/typing.html#typing.TypeVar).

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

```python
P = ParamSpec('P')
```

Переменные спецификации параметров существуют в первую очередь для статических проверок типов. Они используются для передачи типов параметров одного вызываемого объекта другому вызываемому объекту – шаблон, часто встречающийся в функциях высшего порядка и декораторах. Они допустимы только при использовании в `Concatenate`, или как первый аргумент `Callable`, или как параметры пользовательских обобщённых типов (Generics). См. [`Generic`](https://python-all.ru/3.10/library/typing.html#typing.Generic) для получения дополнительной информации об обобщённых типах.

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

```python
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]:
    '''Типобезопасный декоратор для добавления логирования в функцию.'''
    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:
    '''Складывает два числа.'''
    return x + y
```

Без `ParamSpec` самый простой способ аннотировать это ранее заключался в использовании [`TypeVar`](https://python-all.ru/3.10/library/typing.html#typing.TypeVar) с границей `Callable[..., Any]`. Однако это вызывает две проблемы:

1. Проверяющий типы не может проверить типы функции `inner`, потому что `*args` и `**kwargs` должны быть типизированы как [`Any`](https://python-all.ru/3.10/library/typing.html#typing.Any).
2. [`cast()`](https://python-all.ru/3.10/library/typing.html#typing.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`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpecArgs) и [`ParamSpecKwargs`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpecKwargs).

Переменные спецификации параметров, созданные с помощью `covariant=True` или `contravariant=True`, можно использовать для объявления ковариантных или контравариантных обобщённых типов. Аргумент `bound` также принимается, как и в [`TypeVar`](https://python-all.ru/3.10/library/typing.html#typing.TypeVar). Однако фактическая семантика этих ключевых слов ещё не определена.

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

> **Примечание**
>
> Только переменные спецификации параметров, определённые в глобальной области видимости, могут быть pickled.

> **См. также**
>
> - [**PEP 612**](https://python-all.ru/3.10/library/typing.html) – Переменные спецификации параметров (PEP, который ввёл `ParamSpec` и `Concatenate`).
> - [`Callable`](https://python-all.ru/3.10/library/typing.html#typing.Callable) и [`Concatenate`](https://python-all.ru/3.10/library/typing.html#typing.Concatenate).

#### `typing.ParamSpecArgs`

#### `typing.ParamSpecKwargs`

Атрибуты аргументов и именованных аргументов (keyword arguments) объекта [`ParamSpec`](https://python-all.ru/3.10/library/typing.html#typing.ParamSpec). Атрибут `P.args` объекта `ParamSpec` является экземпляром `ParamSpecArgs`, а `P.kwargs` – экземпляром `ParamSpecKwargs`. Они предназначены для интроспекции во время выполнения и не имеют особого значения для статических проверяющих типы.

Вызов [`get_origin()`](https://python-all.ru/3.10/library/typing.html#typing.get_origin) для любого из этих объектов вернёт исходный `ParamSpec`:

```python
P = ParamSpec("P")
get_origin(P.args)  # возвращает P
get_origin(P.kwargs)  # возвращает P
```

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

#### `typing.AnyStr`

`AnyStr` – это [`constrained type variable`](https://python-all.ru/3.10/library/typing.html#typing.TypeVar), определённый как `AnyStr = TypeVar('AnyStr', str, bytes)`.

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

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

concat(u"foo", u"bar")  # Ок, результат имеет тип 'unicode'
concat(b"foo", b"bar")  # Ок, результат имеет тип 'bytes'
concat(u"foo", b"bar")  # Ошибка, нельзя смешивать unicode и bytes
```

#### `class typing.Protocol(Generic)`

Базовый класс для классов протоколов. Классы протоколов определяются следующим образом:

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

Такие классы в основном используются со статическими проверяющими типов, которые распознают структурную подтипизацию (статическую утиную типизацию), например:

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

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

func(C())  # Проходит статическую проверку типов
```

См. [**PEP 544**](https://python-all.ru/3.10/library/typing.html) для получения дополнительных сведений. Классы-протоколы, декорированные [`runtime_checkable()`](https://python-all.ru/3.10/library/typing.html#typing.runtime_checkable) (описано далее), действуют как простые протоколы времени выполнения, которые проверяют только наличие заданных атрибутов, игнорируя их сигнатуры типов.

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

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

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

#### `@typing.runtime_checkable`

Помечает протокольный класс как протокол времени выполнения.

Такой протокол может использоваться с [`isinstance()`](https://python-all.ru/3.10/library/functions.html#isinstance) и [`issubclass()`](https://python-all.ru/3.10/library/functions.html#issubclass). При применении к классу, не являющемуся протоколом, возникает [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError). Это позволяет выполнять простую структурную проверку, очень похожую на “one trick ponies” в [`collections.abc`](https://python-all.ru/3.10/library/collections.abc.html#module-collections.abc), таких как [`Iterable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Iterable). Например:

```python
@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`](https://python-all.ru/3.10/library/ssl.html#ssl.SSLObject) является классом, поэтому он проходит проверку [`issubclass()`](https://python-all.ru/3.10/library/functions.html#issubclass) на соответствие [`Callable`](https://python-all.ru/3.10/library/typing.html#typing.Callable). Однако метод `ssl.SSLObject.__init__` существует только для того, чтобы вызвать [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError) с более информативным сообщением, что делает невозможным вызов (создание экземпляра) [`ssl.SSLObject`](https://python-all.ru/3.10/library/ssl.html#ssl.SSLObject).

> **Примечание**
>
> Проверка [`isinstance()`](https://python-all.ru/3.10/library/functions.html#isinstance) на соответствие протоколу с проверкой во время выполнения может быть удивительно медленной по сравнению с проверкой `isinstance()` для непротокольного класса. Рекомендуется использовать альтернативные идиомы, такие как вызовы [`hasattr()`](https://python-all.ru/3.10/library/functions.html#hasattr) для структурных проверок в коде, чувствительном к производительности.

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

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

Они не используются в аннотациях. Это строительные блоки для объявления типов.

#### `class typing.NamedTuple`

Типизированная версия [`collections.namedtuple()`](https://python-all.ru/3.10/library/collections.html#collections.namedtuple).

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

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

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

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

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

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

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

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

Полученный класс имеет дополнительный атрибут `__annotations__`, который содержит словарь, отображающий имена полей на их типы. (Имена полей находятся в атрибуте `_fields`, а значения по умолчанию – в атрибуте `_field_defaults`; оба они являются частью API [`namedtuple()`](https://python-all.ru/3.10/library/collections.html#collections.namedtuple).)

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

```python
class Employee(NamedTuple):
    """Представляет сотрудника."""
    name: str
    id: int = 3

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

Обратно совместимое использование:

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

Изменено в версии 3.6: Добавлена поддержка синтаксиса аннотации переменных [**PEP 526**](https://python-all.ru/3.10/library/typing.html).

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

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

Изменено в версии 3.9: Атрибут `_field_types` удалён в пользу более стандартного атрибута `__annotations__`, который содержит ту же информацию.

#### `class typing.NewType(name, tp)`

Вспомогательный класс для указания отдельного типа для проверяющего типа, см. [NewType](https://python-all.ru/3.10/library/typing.html#distinct). Во время выполнения он возвращает объект, который возвращает свой аргумент при вызове. Использование:

```python
UserId = NewType('UserId', int)
first_user = UserId(1)
```

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

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

#### `class typing.TypedDict(dict)`

Специальная конструкция для добавления подсказок типов к словарю. Во время выполнения это обычный [`dict`](https://python-all.ru/3.10/library/stdtypes.html#dict).

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

```python
class Point2D(TypedDict):
    x: int
    y: int
    label: str

a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # ОК
b: Point2D = {'z': 3, 'label': 'bad'}           # Не проходит проверку типов

assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
```

Чтобы разрешить использование этой возможности в старых версиях Python, которые не поддерживают [**PEP 526**](https://python-all.ru/3.10/library/typing.html), `TypedDict` поддерживает две дополнительные эквивалентные синтаксические формы:

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

Функциональный синтаксис также следует использовать, когда какой-либо из ключей не является допустимым [идентификатором](https://python-all.ru/3.10/reference/lexical_analysis.html#identifiers), например, потому что они являются ключевыми словами или содержат дефисы. Пример:

```python
# возбуждает SyntaxError
class Point2D(TypedDict):
    in: int  # 'in' – ключевое слово
    x-y: int  # имя с дефисами

# ОК, функциональный синтаксис
Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})
```

По умолчанию все ключи должны присутствовать в `TypedDict`. Это можно переопределить, указав totality. Использование:

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

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

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

```python
class Point3D(Point2D):
    z: int
```

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

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

`TypedDict` не может наследоваться от не-`TypedDict` класса, включая [`Generic`](https://python-all.ru/3.10/library/typing.html#typing.Generic). Например:

```python
class X(TypedDict):
    x: int

class Y(TypedDict):
    y: int

class Z(object): pass  # Класс, не являющийся TypedDict

class XY(X, Y): pass  # ОК

class XZ(X, Z): pass  # вызывает TypeError

T = TypeVar('T')
class XT(X, Generic[T]): pass  # вызывает TypeError
```

`TypedDict` может быть проанализирован с помощью словарей аннотаций (см. [Лучшие практики работы с аннотациями](https://python-all.ru/3.10/howto/annotations.html#annotations-howto) для получения дополнительной информации о лучших практиках работы с аннотациями), [`__total__`](https://python-all.ru/3.10/library/typing.html#typing.TypedDict.__total__), [`__required_keys__`](https://python-all.ru/3.10/library/typing.html#typing.TypedDict.__required_keys__) и [`__optional_keys__`](https://python-all.ru/3.10/library/typing.html#typing.TypedDict.__optional_keys__).

#### `__total__`

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

```python
>>> 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
```

#### `__required_keys__`

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

#### `__optional_keys__`

`Point2D.__required_keys__` и `Point2D.__optional_keys__` возвращают объекты [`frozenset`](https://python-all.ru/3.10/library/stdtypes.html#frozenset), содержащие обязательные и необязательные ключи соответственно. В настоящее время единственный способ объявить как обязательные, так и необязательные ключи в одном `TypedDict` – это смешанное наследование: объявить `TypedDict` с одним значением для аргумента `total`, а затем унаследовать его от другого `TypedDict` с другим значением для `total`. Использование:

```python
>>> 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.

Смотрите [**PEP 589**](https://python-all.ru/3.10/library/typing.html) для дополнительных примеров и подробных правил использования `TypedDict`.

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

### Конкретные обобщённые коллекции

#### Соответствующие встроенным типам

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

Обобщённая версия [`dict`](https://python-all.ru/3.10/library/stdtypes.html#dict). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`Mapping`](https://python-all.ru/3.10/library/typing.html#typing.Mapping).

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

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

Deprecated since version 3.9: [`builtins.dict`](https://python-all.ru/3.10/library/stdtypes.html#dict) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`list`](https://python-all.ru/3.10/library/stdtypes.html#list). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`Sequence`](https://python-all.ru/3.10/library/typing.html#typing.Sequence) или [`Iterable`](https://python-all.ru/3.10/library/typing.html#typing.Iterable).

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

```python
T = TypeVar('T', int, float)

def vec2(x: T, y: T) -> List[T]:
    return [x, y]

def keep_positives(vector: Sequence[T]) -> List[T]:
    return [item for item in vector if item > 0]
```

Deprecated since version 3.9: [`builtins.list`](https://python-all.ru/3.10/library/stdtypes.html#list) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`builtins.set`](https://python-all.ru/3.10/library/stdtypes.html#set). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`AbstractSet`](https://python-all.ru/3.10/library/typing.html#typing.AbstractSet).

Deprecated since version 3.9: [`builtins.set`](https://python-all.ru/3.10/library/stdtypes.html#set) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`builtins.frozenset`](https://python-all.ru/3.10/library/stdtypes.html#frozenset).

Deprecated since version 3.9: [`builtins.frozenset`](https://python-all.ru/3.10/library/stdtypes.html#frozenset) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

> **Примечание**
>
> [`Tuple`](https://python-all.ru/3.10/library/typing.html#typing.Tuple) – это специальная форма.

#### Соответствует типам в [`collections`](https://python-all.ru/3.10/library/collections.html#module-collections)

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

Обобщённая версия [`collections.defaultdict`](https://python-all.ru/3.10/library/collections.html#collections.defaultdict).

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

Deprecated since version 3.9: [`collections.defaultdict`](https://python-all.ru/3.10/library/collections.html#collections.defaultdict) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.OrderedDict`](https://python-all.ru/3.10/library/collections.html#collections.OrderedDict).

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

Deprecated since version 3.9: [`collections.OrderedDict`](https://python-all.ru/3.10/library/collections.html#collections.OrderedDict) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.ChainMap`](https://python-all.ru/3.10/library/collections.html#collections.ChainMap).

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

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

Deprecated since version 3.9: [`collections.ChainMap`](https://python-all.ru/3.10/library/collections.html#collections.ChainMap) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.Counter`](https://python-all.ru/3.10/library/collections.html#collections.Counter).

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

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

Deprecated since version 3.9: [`collections.Counter`](https://python-all.ru/3.10/library/collections.html#collections.Counter) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.deque`](https://python-all.ru/3.10/library/collections.html#collections.deque).

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

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

Deprecated since version 3.9: [`collections.deque`](https://python-all.ru/3.10/library/collections.html#collections.deque) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### Другие конкретные типы

#### `class typing.IO`

#### `class typing.TextIO`

#### `class typing.BinaryIO`

Обобщённый тип `IO[AnyStr]` и его подклассы `TextIO(IO[str])` и `BinaryIO(IO[bytes])` представляют типы потоков ввода-вывода, такие как возвращаемые [`open()`](https://python-all.ru/3.10/library/functions.html#open).

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

#### `class typing.Pattern`

#### `class typing.Match`

Эти псевдонимы типов соответствуют возвращаемым типам из [`re.compile()`](https://python-all.ru/3.10/library/re.html#re.compile) и [`re.match()`](https://python-all.ru/3.10/library/re.html#re.match). Эти типы (и соответствующие функции) являются обобщёнными по `AnyStr` и могут быть конкретизированы записью `Pattern[str]`, `Pattern[bytes]`, `Match[str]` или `Match[bytes]`.

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

Устарело с версии 3.9: Классы `Pattern` и `Match` из [`re`](https://python-all.ru/3.10/library/re.html#module-re) теперь поддерживают `[]`. См. [**PEP 585**](https://python-all.ru/3.10/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.Text`

`Text` – это псевдоним для `str`. Он предоставляется для обеспечения совместимости с кодом Python 2: в Python 2 `Text` является псевдонимом для `unicode`.

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

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

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

### Абстрактные базовые классы

#### Соответствуют коллекциям из [`collections.abc`](https://python-all.ru/3.10/library/collections.abc.html#module-collections.abc)

#### `class typing.AbstractSet(Collection[T_co])`

Обобщённая версия [`collections.abc.Set`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Set).

Deprecated since version 3.9: [`collections.abc.Set`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Set) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.ByteString(Sequence[int])`

Обобщённая версия [`collections.abc.ByteString`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.ByteString).

Этот тип представляет типы [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.10/library/stdtypes.html#bytearray) и [`memoryview`](https://python-all.ru/3.10/library/stdtypes.html#memoryview) последовательностей байтов.

В качестве сокращения для этого типа [`bytes`](https://python-all.ru/3.10/library/stdtypes.html#bytes) можно использовать для аннотации аргументов любого из упомянутых выше типов.

Deprecated since version 3.9: [`collections.abc.ByteString`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.ByteString) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.abc.Collection`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Collection)

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

Deprecated since version 3.9: [`collections.abc.Collection`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Collection) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.Container(Generic[T_co])`

Обобщённая версия [`collections.abc.Container`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Container).

Deprecated since version 3.9: [`collections.abc.Container`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Container) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.abc.ItemsView`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.ItemsView).

Deprecated since version 3.9: [`collections.abc.ItemsView`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.ItemsView) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.abc.KeysView`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.KeysView).

Deprecated since version 3.9: [`collections.abc.KeysView`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.KeysView) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.abc.Mapping`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Mapping). Этот тип можно использовать следующим образом:

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

Deprecated since version 3.9: [`collections.abc.Mapping`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Mapping) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.MappingView(Sized)`

Обобщённая версия [`collections.abc.MappingView`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.MappingView).

Deprecated since version 3.9: [`collections.abc.MappingView`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.MappingView) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.abc.MutableMapping`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.MutableMapping).

Deprecated since version 3.9: [`collections.abc.MutableMapping`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.MutableMapping) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.MutableSequence(Sequence[T])`

Обобщённая версия [`collections.abc.MutableSequence`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.MutableSequence).

Deprecated since version 3.9: [`collections.abc.MutableSequence`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.MutableSequence) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.MutableSet(AbstractSet[T])`

Обобщённая версия [`collections.abc.MutableSet`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.MutableSet).

Deprecated since version 3.9: [`collections.abc.MutableSet`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.MutableSet) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.abc.Sequence`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Sequence).

Deprecated since version 3.9: [`collections.abc.Sequence`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Sequence) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

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

Обобщённая версия [`collections.abc.ValuesView`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.ValuesView).

Deprecated since version 3.9: [`collections.abc.ValuesView`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.ValuesView) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### Соответствует другим типам в [`collections.abc`](https://python-all.ru/3.10/library/collections.abc.html#module-collections.abc)

#### `class typing.Iterable(Generic[T_co])`

Обобщённая версия [`collections.abc.Iterable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Iterable).

Deprecated since version 3.9: [`collections.abc.Iterable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Iterable) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.Iterator(Iterable[T_co])`

Обобщённая версия [`collections.abc.Iterator`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Iterator).

Deprecated since version 3.9: [`collections.abc.Iterator`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Iterator) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])`

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

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

Обратите внимание: в отличие от многих других обобщённых типов в модуле typing, `SendType` из [`Generator`](https://python-all.ru/3.10/library/typing.html#typing.Generator) ведёт себя контравариантно, а не ковариантно или инвариантно.

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

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

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

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

Deprecated since version 3.9: [`collections.abc.Generator`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Generator) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.Hashable`

Псевдоним для [`collections.abc.Hashable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Hashable).

#### `class typing.Reversible(Iterable[T_co])`

Обобщённая версия [`collections.abc.Reversible`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Reversible).

Deprecated since version 3.9: [`collections.abc.Reversible`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Reversible) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.Sized`

Псевдоним для [`collections.abc.Sized`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Sized).

#### Асинхронное программирование

#### `class typing.Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co])`

Обобщённая версия [`collections.abc.Coroutine`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Coroutine). Вариантность и порядок переменных типа соответствуют таковым у [`Generator`](https://python-all.ru/3.10/library/typing.html#typing.Generator), например:

```python
from collections.abc import Coroutine
c: Coroutine[list[str], str, int]  # Некоторая корутина, определённая в другом месте.
x = c.send('hi')                   # Выведенный тип 'x' – list[str].
async def bar() -> None:
    y = await c                    # Выведенный тип 'y' – int.
```

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

Deprecated since version 3.9: [`collections.abc.Coroutine`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Coroutine) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])`

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

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

В отличие от обычных генераторов, асинхронные генераторы не могут возвращать значение, поэтому параметр типа `ReturnType` отсутствует. Как и в случае с [`Generator`](https://python-all.ru/3.10/library/typing.html#typing.Generator), `SendType` ведёт себя контравариантно.

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

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

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

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

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

Deprecated since version 3.9: [`collections.abc.AsyncGenerator`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.AsyncGenerator) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.AsyncIterable(Generic[T_co])`

Обобщённая версия [`collections.abc.AsyncIterable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.AsyncIterable).

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

Deprecated since version 3.9: [`collections.abc.AsyncIterable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.AsyncIterable) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.AsyncIterator(AsyncIterable[T_co])`

Обобщённая версия [`collections.abc.AsyncIterator`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.AsyncIterator).

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

Deprecated since version 3.9: [`collections.abc.AsyncIterator`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.AsyncIterator) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.Awaitable(Generic[T_co])`

Обобщённая версия [`collections.abc.Awaitable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Awaitable).

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

Deprecated since version 3.9: [`collections.abc.Awaitable`](https://python-all.ru/3.10/library/collections.abc.html#collections.abc.Awaitable) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### Типы контекстных менеджеров

#### `class typing.ContextManager(Generic[T_co])`

Обобщённая версия [`contextlib.AbstractContextManager`](https://python-all.ru/3.10/library/contextlib.html#contextlib.AbstractContextManager).

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

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

Deprecated since version 3.9: [`contextlib.AbstractContextManager`](https://python-all.ru/3.10/library/contextlib.html#contextlib.AbstractContextManager) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

#### `class typing.AsyncContextManager(Generic[T_co])`

Обобщённая версия [`contextlib.AbstractAsyncContextManager`](https://python-all.ru/3.10/library/contextlib.html#contextlib.AbstractAsyncContextManager).

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

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

Deprecated since version 3.9: [`contextlib.AbstractAsyncContextManager`](https://python-all.ru/3.10/library/contextlib.html#contextlib.AbstractAsyncContextManager) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.10/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.10/library/stdtypes.html#types-genericalias).

### Протоколы

Эти протоколы декорированы [`runtime_checkable()`](https://python-all.ru/3.10/library/typing.html#typing.runtime_checkable).

#### `class typing.SupportsAbs`

ABC с одним абстрактным методом `__abs__`, ковариантным по типу возвращаемого значения.

#### `class typing.SupportsBytes`

ABC с одним абстрактным методом `__bytes__`.

#### `class typing.SupportsComplex`

ABC с одним абстрактным методом `__complex__`.

#### `class typing.SupportsFloat`

ABC с одним абстрактным методом `__float__`.

#### `class typing.SupportsIndex`

ABC с одним абстрактным методом `__index__`.

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

#### `class typing.SupportsInt`

ABC с одним абстрактным методом `__int__`.

#### `class typing.SupportsRound`

ABC с одним абстрактным методом `__round__` ковариантным по возвращаемому типу.

### Функции и декораторы

#### `typing.cast(typ, val)`

Приводит значение к типу.

Это возвращает значение без изменений. Для проверщика типов это сигнализирует, что возвращаемое значение имеет указанный тип, но во время выполнения мы намеренно ничего не проверяем (мы хотим, чтобы это было как можно быстрее).

#### `@typing.overload`

Декоратор `@overload` позволяет описывать функции и методы, поддерживающие несколько различных комбинаций типов аргументов. За серией определений, декорированных `@overload`, должно следовать ровно одно определение без `@overload` (для той же функции/метода). Определения с `@overload` предназначены только для проверки типов, так как они будут перезаписаны определением без `@overload`, которое используется во время выполнения, но должно игнорироваться проверщиком типов. Во время выполнения прямой вызов функции, декорированной `@overload`, вызовет [`NotImplementedError`](https://python-all.ru/3.10/library/exceptions.html#NotImplementedError). Пример перегрузки, дающей более точный тип, чем можно выразить с помощью объединения или переменной типа:

```python
@overload
def process(response: None) -> None:
    ...
@overload
def process(response: int) -> tuple[int, str]:
    ...
@overload
def process(response: bytes) -> str:
    ...
def process(response):
    <actual implementation>
```

Подробнее и сравнение с другими семантиками типизации см. [**PEP 484**](https://python-all.ru/3.10/library/typing.html).

#### `@typing.final`

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

```python
class Base:
    @final
    def done(self) -> None:
        ...
class Sub(Base):
    def done(self) -> None:  # Ошибка, выдаваемая проверщиком типов
        ...

@final
class Leaf:
    ...
class Other(Leaf):  # Ошибка, выдаваемая проверщиком типов
    ...
```

Проверка этих свойств во время выполнения не выполняется. Подробнее см. [**PEP 591**](https://python-all.ru/3.10/library/typing.html).

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

#### `@typing.no_type_check`

Декоратор, указывающий, что аннотации не являются подсказками типов.

Это работает как декоратор класса или функции [декоратор](https://python-all.ru/3.10/glossary.html#term-decorator). В случае класса он рекурсивно применяется ко всем методам, определённым в этом классе (но не к методам, определённым в его суперклассах или подклассах).

Это изменяет функцию(и) на месте.

#### `@typing.no_type_check_decorator`

Декоратор, придающий другому декоратору эффект [`no_type_check()`](https://python-all.ru/3.10/library/typing.html#typing.no_type_check).

Он оборачивает декоратор чем-то, что оборачивает декорированную функцию в [`no_type_check()`](https://python-all.ru/3.10/library/typing.html#typing.no_type_check).

#### `@typing.type_check_only`

Декоратор, помечающий класс или функцию как недоступные во время выполнения.

Сам этот декоратор недоступен во время выполнения. Он в основном предназначен для пометки классов, определённых в файлах заглушек типов (type stub), если реализация возвращает экземпляр закрытого класса:

```python
@type_check_only
class Response:  # приватный или недоступный во время выполнения
    code: int
    def get_header(self, name: str) -> str: ...

def fetch_response() -> Response: ...
```

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

### Вспомогательные функции для интроспекции

#### `typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False)`

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

Это часто совпадает с `obj.__annotations__`. Кроме того, прямые ссылки, закодированные как строковые литералы, обрабатываются путём вычисления их в пространствах имён `globals` и `locals`. При необходимости `Optional[t]` добавляется для аннотаций функций и методов, если задано значение по умолчанию, равное `None`. Для класса `C` возвращается словарь, построенный объединением всех `__annotations__` по `C.__mro__` в обратном порядке.

Функция рекурсивно заменяет все `Annotated[T, ...]` на `T`, если только `include_extras` не установлено в `True` (см. [`Annotated`](https://python-all.ru/3.10/library/typing.html#typing.Annotated) для получения дополнительной информации). Например:

```python
class Student(NamedTuple):
    name: Annotated[str, 'some marker']

get_type_hints(Student) == {'name': str}
get_type_hints(Student, include_extras=False) == {'name': str}
get_type_hints(Student, include_extras=True) == {
    'name': Annotated[str, 'some marker']
}
```

> **Примечание**
>
> [`get_type_hints()`](https://python-all.ru/3.10/library/typing.html#typing.get_type_hints) не работает с импортированными [псевдонимами типов](https://python-all.ru/3.10/library/typing.html#type-aliases), которые содержат прямые ссылки. Включение отложенного вычисления аннотаций ([**PEP 563**](https://python-all.ru/3.10/library/typing.html)) может устранить необходимость в большинстве прямых ссылок.

Изменено в версии 3.9: Добавлен параметр `include_extras` в рамках [**PEP 593**](https://python-all.ru/3.10/library/typing.html).

#### `typing.get_args(tp)`

#### `typing.get_origin(tp)`

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

Для объекта typing вида `X[Y, Z, ...]` эти функции возвращают `X` и `(Y, Z, ...)`. Если `X` является обобщённым псевдонимом для встроенного класса или класса [`collections`](https://python-all.ru/3.10/library/collections.html#module-collections), он нормализуется до исходного класса. Если `X` является объединением или [`Literal`](https://python-all.ru/3.10/library/typing.html#typing.Literal), содержащимся в другом обобщённом типе, порядок `(Y, Z, ...)` может отличаться от порядка исходных аргументов `[Y, Z, ...]` из-за кэширования типов. Для неподдерживаемых объектов возвращают `None` и `()` соответственно. Примеры:

```python
assert get_origin(Dict[str, int]) is dict
assert get_args(Dict[int, str]) == (int, str)

assert get_origin(Union[int, str]) is Union
assert get_args(Union[int, str]) == (int, str)
```

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

#### `typing.is_typeddict(tp)`

Проверяет, является ли тип [`TypedDict`](https://python-all.ru/3.10/library/typing.html#typing.TypedDict).

Например:

```python
class Film(TypedDict):
    title: str
    year: int

is_typeddict(Film)  # => True
is_typeddict(list | str)  # => False
```

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

#### `class typing.ForwardRef`

Класс, используемый для внутреннего представления типов строковых прямых ссылок. Например, `List["SomeClass"]` неявно преобразуется в `List[ForwardRef("SomeClass")]`. Этот класс не должен создаваться пользователем, но может использоваться инструментами интроспекции.

> **Примечание**
>
> обобщённые типы [**PEP 585**](https://python-all.ru/3.10/library/typing.html), такие как `list["SomeClass"]`, не будут неявно преобразовываться в `list[ForwardRef("SomeClass")]` и, следовательно, не будут автоматически разрешаться в `list[SomeClass]`.

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

### Константа

#### `typing.TYPE_CHECKING`

Специальная константа, которая считается `True` сторонними статическими проверщиками типов. Во время выполнения она равна `False`. Применение:

```python
if TYPE_CHECKING:
    import expensive_mod

def fun(arg: 'expensive_mod.SomeType') -> None:
    local_var: expensive_mod.AnotherType = other_fun()
```

Первую аннотацию типа необходимо заключать в кавычки, превращая её в «прямую ссылку» (forward reference), чтобы скрыть ссылку `expensive_mod` от интерпретатора во время выполнения. Аннотации типов для локальных переменных не вычисляются, поэтому вторую аннотацию не нужно заключать в кавычки.

> **Примечание**
>
> Если используется `from __future__ import annotations`, аннотации не вычисляются во время определения функции. Вместо этого они сохраняются как строки в `__annotations__`. Это избавляет от необходимости заключать аннотацию в кавычки (см. [**PEP 563**](https://python-all.ru/3.10/library/typing.html)).

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