typing.md
1> **Источник:** https://python-all.ru/3.11/library/typing.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`typing`](https://python-all.ru/3.11/library/typing.html#module-typing) – Поддержка аннотаций типов89Новое в версии 3.5.1011**Исходный код:** [Lib/typing.py](https://python-all.ru/src/3.11/Lib/typing.py)1213> **Примечание**14>15> Среда выполнения Python не проверяет аннотации типов функций и переменных. Они могут использоваться сторонними инструментами, такими как [проверщики типов](https://python-all.ru/3.11/glossary.html#term-static-type-checker), IDE, линтеры и т. д.1617---1819Этот модуль предоставляет поддержку аннотаций типов во время выполнения. Оригинальную спецификацию системы аннотаций см. в [**PEP 484**](https://python-all.ru/3.11/library/typing.html). Упрощённое введение в аннотации типов – в [**PEP 483**](https://python-all.ru/3.11/library/typing.html).2021Функция ниже принимает и возвращает строку и аннотирована следующим образом:2223```python24def greeting(name: str) -> str:25 return 'Hello ' + name26```2728В функции `greeting` аргумент `name` ожидается типа [`str`](https://python-all.ru/3.11/library/stdtypes.html#str), а возвращаемый тип – [`str`](https://python-all.ru/3.11/library/stdtypes.html#str). Подтипы допускаются в качестве аргументов.2930Новые функции часто добавляются в модуль `typing`. Пакет [typing\_extensions](https://python-all.ru/3.11/library/typing.html) предоставляет бэкпорты этих новых функций для старых версий Python.3132Сводку устаревших возможностей и график их устаревания см. в [График устаревания основных возможностей](https://python-all.ru/3.11/library/typing.html#deprecation-timeline-of-major-features).3334> **См. также**35>36> **[«Шпаргалка по аннотациям типов»](https://python-all.ru/3.11/library/typing.html)**37>38> Краткий обзор аннотаций типов (размещён в документации mypy)39>40> **Раздел «Type System Reference» [документации mypy](https://python-all.ru/3.11/library/typing.html)**41>42> Система типов Python стандартизирована через PEP, поэтому данное руководство должно в целом подходить для большинства проверщиков типов Python. (Некоторые части могут по-прежнему относиться только к mypy.)43>44> **[«Статическая типизация в Python»](https://python-all.ru/3.11/library/typing.html)**45>46> Независимая от проверщика типов документация, написанная сообществом, с подробным описанием возможностей системы типов, полезных инструментов, связанных с типизацией, и лучших практик типизации.4748## Соответствующие PEP4950С момента появления аннотаций типов в [**PEP 484**](https://python-all.ru/3.11/library/typing.html) и [**PEP 483**](https://python-all.ru/3.11/library/typing.html) ряд PEP расширили и улучшили инфраструктуру Python для аннотаций типов:5152Полный список PEP5354- **[**PEP 526**](https://python-all.ru/3.11/library/typing.html): Синтаксис аннотаций переменных**5556 *Вводит* синтаксис аннотирования переменных вне определений функций, а также [`ClassVar`](https://python-all.ru/3.11/library/typing.html#typing.ClassVar)57- **[**PEP 544**](https://python-all.ru/3.11/library/typing.html): Протоколы: структурная типизация (статическая утиная типизация)**5859 *Вводит* [`Protocol`](https://python-all.ru/3.11/library/typing.html#typing.Protocol) и декоратор [`@runtime_checkable`](https://python-all.ru/3.11/library/typing.html#typing.runtime_checkable)60- **[**PEP 585**](https://python-all.ru/3.11/library/typing.html): Обобщённые типы в стандартных коллекциях**6162 *Вводит* [`types.GenericAlias`](https://python-all.ru/3.11/library/types.html#types.GenericAlias) и возможность использовать классы стандартной библиотеки как [обобщённые типы](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias)63- **[**PEP 586**](https://python-all.ru/3.11/library/typing.html): Литеральные типы**6465 *Вводит* [`Literal`](https://python-all.ru/3.11/library/typing.html#typing.Literal)66- **[**PEP 589**](https://python-all.ru/3.11/library/typing.html): TypedDict: аннотации типов для словарей с фиксированным набором ключей**6768 *Вводит* [`TypedDict`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict)69- **[**PEP 591**](https://python-all.ru/3.11/library/typing.html): Добавление квалификатора final в typing**7071 *Вводит* [`Final`](https://python-all.ru/3.11/library/typing.html#typing.Final) и декоратор [`@final`](https://python-all.ru/3.11/library/typing.html#typing.final)72- **[**PEP 593**](https://python-all.ru/3.11/library/typing.html): Гибкие аннотации функций и переменных**7374 *Вводит* [`Annotated`](https://python-all.ru/3.11/library/typing.html#typing.Annotated)75- **[**PEP 604**](https://python-all.ru/3.11/library/typing.html): Разрешение записи объединённых типов как `X | Y`**7677 *Вводит* [`types.UnionType`](https://python-all.ru/3.11/library/types.html#types.UnionType) и возможность использовать бинарный оператор ИЛИ `|` для обозначения [объединения типов](https://python-all.ru/3.11/library/stdtypes.html#types-union)78- **[**PEP 612**](https://python-all.ru/3.11/library/typing.html): Переменные спецификации параметров**7980 *Вводит* [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec) и [`Concatenate`](https://python-all.ru/3.11/library/typing.html#typing.Concatenate)81- **[**PEP 613**](https://python-all.ru/3.11/library/typing.html): Явные псевдонимы типов**8283 *Вводит* [`TypeAlias`](https://python-all.ru/3.11/library/typing.html#typing.TypeAlias)84- **[**PEP 646**](https://python-all.ru/3.11/library/typing.html): Вариативные обобщения**8586 *Вводит* [`TypeVarTuple`](https://python-all.ru/3.11/library/typing.html#typing.TypeVarTuple)87- **[**PEP 647**](https://python-all.ru/3.11/library/typing.html): Защитники типов, определяемые пользователем**8889 *Представлен* [`TypeGuard`](https://python-all.ru/3.11/library/typing.html#typing.TypeGuard)90- **[**PEP 655**](https://python-all.ru/3.11/library/typing.html): Помечение отдельных элементов TypedDict как обязательных или потенциально отсутствующих**9192 *Представлен* [`Required`](https://python-all.ru/3.11/library/typing.html#typing.Required) и [`NotRequired`](https://python-all.ru/3.11/library/typing.html#typing.NotRequired)93- **[**PEP 673**](https://python-all.ru/3.11/library/typing.html): тип Self**9495 *Представлен* [`Self`](https://python-all.ru/3.11/library/typing.html#typing.Self)96- **[**PEP 675**](https://python-all.ru/3.11/library/typing.html): произвольный тип литеральной строки**9798 *Представлен* [`LiteralString`](https://python-all.ru/3.11/library/typing.html#typing.LiteralString)99- **[**PEP 681**](https://python-all.ru/3.11/library/typing.html): преобразования классов данных**100101 *Представлен* декоратор [`@dataclass_transform`](https://python-all.ru/3.11/library/typing.html#typing.dataclass_transform)102103## Псевдонимы типов104105Псевдоним типа определяется присваиванием типа псевдониму. В этом примере `Vector` и `list[float]` будут рассматриваться как взаимозаменяемые синонимы:106107```python108Vector = list[float]109110def scale(scalar: float, vector: Vector) -> Vector:111 return [scalar * num for num in vector]112113# проходит проверку типов; список чисел с плавающей точкой считается Vector.114new_vector = scale(2.0, [1.0, -4.2, 5.4])115```116117Псевдонимы типов полезны для упрощения сложных сигнатур типов. Например:118119```python120from collections.abc import Sequence121122ConnectionOptions = dict[str, str]123Address = tuple[str, int]124Server = tuple[Address, ConnectionOptions]125126def broadcast_message(message: str, servers: Sequence[Server]) -> None:127 ...128129# Статическая проверка типов будет считать предыдущую сигнатуру типа как130# полностью эквивалентную этой.131def broadcast_message(132 message: str,133 servers: Sequence[tuple[tuple[str, int], dict[str, str]]]) -> None:134 ...135```136137Псевдонимы типов могут быть помечены [`TypeAlias`](https://python-all.ru/3.11/library/typing.html#typing.TypeAlias), чтобы явно указать, что это объявление псевдонима типа, а не обычное присваивание переменной:138139```python140from typing import TypeAlias141142Vector: TypeAlias = list[float]143```144145## NewType146147Используйте вспомогательную функцию [`NewType`](https://python-all.ru/3.11/library/typing.html#typing.NewType) для создания отдельных типов:148149```python150from typing import NewType151152UserId = NewType('UserId', int)153some_id = UserId(524313)154```155156Статический проверщик типов будет рассматривать новый тип как подкласс исходного типа. Это полезно для выявления логических ошибок:157158```python159def get_user_name(user_id: UserId) -> str:160 ...161162# проходит проверку типов163user_a = get_user_name(UserId(42351))164165# не проходит проверку типов; int не является UserId166user_b = get_user_name(-1)167```168169Можно по-прежнему выполнять все операции `int` над переменной типа `UserId`, но результат всегда будет типа `int`. Это позволяет передавать `UserId` везде, где может ожидаться `int`, но предотвращает случайное создание `UserId` недопустимым способом:170171```python172# 'output' имеет тип 'int', а не 'UserId'173output = UserId(23413) + UserId(54341)174```175176Обратите внимание, что эти проверки выполняются только статическим проверщиком типов. Во время выполнения оператор `Derived = NewType('Derived', Base)` сделает `Derived` вызываемым объектом, который немедленно возвращает любой переданный ему параметр. Это означает, что выражение `Derived(some_value)` не создаёт новый класс и не вносит значительных накладных расходов по сравнению с обычным вызовом функции.177178Точнее, выражение `some_value is Derived(some_value)` во время выполнения всегда истинно.179180Недопустимо создание подтипа `Derived`:181182```python183from typing import NewType184185UserId = NewType('UserId', int)186187# Завершается ошибкой во время выполнения и не проходит проверку типов188class AdminUserId(UserId): pass189```190191Однако можно создать [`NewType`](https://python-all.ru/3.11/library/typing.html#typing.NewType) на основе «производного» `NewType`:192193```python194from typing import NewType195196UserId = NewType('UserId', int)197198ProUserId = NewType('ProUserId', UserId)199```200201и проверка типов для `ProUserId` будет работать как ожидается.202203Подробнее см. [**PEP 484**](https://python-all.ru/3.11/library/typing.html).204205> **Примечание**206>207> Напомним, что использование псевдонима типа объявляет два типа *эквивалентными* друг другу. Использование `Alias = Original` заставит статический анализатор типов считать `Alias` *точно эквивалентным* `Original` во всех случаях. Это полезно, когда требуется упростить сложные сигнатуры типов.208>209> В отличие от этого, `NewType` объявляет один тип *подтипом* другого. Использование `Derived = NewType('Derived', Original)` заставит статический анализатор типов считать `Derived` *подклассом* `Original`, что означает, что значение типа `Original` не может использоваться там, где ожидается значение типа `Derived`. Это полезно для предотвращения логических ошибок с минимальными затратами времени выполнения.210211Новое в версии 3.5.2.212213Изменено в версии 3.10: `NewType` теперь является классом, а не функцией. В результате имеются некоторые дополнительные расходы во время выполнения при вызове `NewType` по сравнению с обычной функцией.214215Изменено в версии 3.11: Производительность вызова `NewType` восстановлена до уровня Python 3.9.216217## Аннотация вызываемых объектов218219Функции – или другие [вызываемые](https://python-all.ru/3.11/glossary.html#term-callable) объекты – могут быть аннотированы с помощью [`collections.abc.Callable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Callable) или [`typing.Callable`](https://python-all.ru/3.11/library/typing.html#typing.Callable). `Callable[[int], str]` означает функцию, которая принимает один параметр типа [`int`](https://python-all.ru/3.11/library/functions.html#int) и возвращает [`str`](https://python-all.ru/3.11/library/stdtypes.html#str).220221Например:222223```python224from collections.abc import Callable, Awaitable225226def feeder(get_next_item: Callable[[], str]) -> None:227 ... # Тело228229def async_query(on_success: Callable[[int], None],230 on_error: Callable[[int, Exception], None]) -> None:231 ... # Тело232233async def on_update(value: str) -> None:234 ... # Тело235236callback: Callable[[str], Awaitable[None]] = on_update237```238239Синтаксис индексации всегда должен использоваться ровно с двумя значениями: списком аргументов и типом возвращаемого значения. Список аргументов должен быть списком типов, [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec), [`Concatenate`](https://python-all.ru/3.11/library/typing.html#typing.Concatenate) или многоточием. Тип возвращаемого значения должен быть единственным типом.240241Если в качестве списка аргументов указано литеральное многоточие `...`, это означает, что принимается вызываемый объект с произвольным списком параметров:242243```python244def concat(x: str, y: str) -> str:245 return x + y246247x: Callable[..., str]248x = str # ОК249x = concat # Тоже ОК250```251252`Callable` не может выражать сложные сигнатуры, такие как функции, принимающие переменное количество аргументов, [перегруженные функции](https://python-all.ru/3.11/library/typing.html#overload) или функции, имеющие только ключевые параметры. Однако эти сигнатуры можно выразить, определив класс [`Protocol`](https://python-all.ru/3.11/library/typing.html#typing.Protocol) с методом [`__call__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__call__):253254```python255from collections.abc import Iterable256from typing import Protocol257258class Combiner(Protocol):259 def __call__(self, *vals: bytes, maxlen: int | None = None) -> list[bytes]: ...260261def batch_proc(data: Iterable[bytes], cb_results: Combiner) -> bytes:262 for item in data:263 ...264265def good_cb(*vals: bytes, maxlen: int | None = None) -> list[bytes]:266 ...267def bad_cb(*vals: bytes, maxitems: int | None) -> list[bytes]:268 ...269270batch_proc([], good_cb) # ОК271batch_proc([], bad_cb) # Ошибка! Аргумент 2 имеет несовместимый тип из-за272 # другого имени и вида в колбэке273```274275Объекты, принимающие другие вызываемые объекты в качестве аргументов, могут указать, что их типы параметров зависят друг от друга, с помощью [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec). Кроме того, если такой вызываемый объект добавляет или удаляет аргументы из других вызываемых объектов, может использоваться оператор [`Concatenate`](https://python-all.ru/3.11/library/typing.html#typing.Concatenate). Они имеют соответственно форму `Callable[ParamSpecVariable, ReturnType]` и `Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType]`.276277Changed in version 3.10: `Callable` now supports [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec) and [`Concatenate`](https://python-all.ru/3.11/library/typing.html#typing.Concatenate). See [**PEP 612**](https://python-all.ru/3.11/library/typing.html) for more details.278279> **См. также**280>281> В документации к [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec) и [`Concatenate`](https://python-all.ru/3.11/library/typing.html#typing.Concatenate) приведены примеры использования в `Callable`.282283## Обобщённые типы284285Поскольку информацию о типах объектов, хранящихся в контейнерах, невозможно статически вывести обобщённым способом, многие классы контейнеров в стандартной библиотеке поддерживают индексацию для указания ожидаемых типов элементов контейнера.286287```python288from collections.abc import Mapping, Sequence289290class Employee: ...291292# Sequence[Employee] означает, что все элементы последовательности293# должны быть экземплярами "Employee".294# Mapping[str, str] означает, что все ключи и все значения в отображении295# должны быть строками.296def notify_by_email(employees: Sequence[Employee],297 overrides: Mapping[str, str]) -> None: ...298```299300Обобщённые типы можно параметризовать с помощью фабрики, доступной в typing под названием [`TypeVar`](https://python-all.ru/3.11/library/typing.html#typing.TypeVar).301302```python303from collections.abc import Sequence304from typing import TypeVar305306T = TypeVar('T') # Объявить переменную типа "T"307308def first(l: Sequence[T]) -> T: # Функция универсальна (обобщена) по TypeVar "T"309 return l[0]310```311312## Аннотация кортежей313314Для большинства контейнеров в Python система типов предполагает, что все элементы в контейнере будут одного типа. Например:315316```python317from collections.abc import Mapping318319# Проверка типов выведет, что все элементы в ``x`` должны иметь тип int.320x: list[int] = []321322# Ошибка проверки типов: ``list`` принимает только один аргумент типа:323y: list[int, str] = [1, 'foo']324325# Проверка типов выведет, что все ключи в ``z`` должны быть строками,326# а все значения в ``z`` должны быть строками или int.327z: Mapping[str, str | int] = {}328```329330[`list`](https://python-all.ru/3.11/library/stdtypes.html#list) принимает только один аргумент типа, поэтому анализатор типов выдал бы ошибку на присваивании `y` выше. Аналогично, [`Mapping`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Mapping) принимает только два аргумента типа: первый указывает тип ключей, а второй – тип значений.331332Однако, в отличие от большинства других контейнеров Python, в идиоматическом коде Python часто встречаются кортежи, элементы которых не все одного типа. По этой причине кортежи обрабатываются особым образом в системе типов Python. [`tuple`](https://python-all.ru/3.11/library/stdtypes.html#tuple) принимает *любое количество* аргументов типа:333334```python335# OK: ``x`` присваивается кортежу длины 1, единственный элемент которого – int.336x: tuple[int] = (5,)337338# OK: ``y`` присваивается кортежу длины 2;339# элемент 1 – int, элемент 2 – str.340y: tuple[int, str] = (5, "foo")341342# Ошибка: аннотация типа указывает на кортеж длины 1,343# но ``z`` был присвоен кортеж длины 3.344z: tuple[int] = (1, 2, 3)345```346347Для обозначения кортежа, который может быть *любой* длины, и в котором все элементы одного типа `T`, используйте `tuple[T, ...]`. Для обозначения пустого кортежа используйте `tuple[()]`. Использование простого `tuple` в качестве аннотации эквивалентно использованию `tuple[Any, ...]`:348349```python350x: tuple[int, ...] = (1, 2)351# Эти переприсваивания OK: ``tuple[int, ...]`` указывает, что x может быть любой длины.352x = (1, 2, 3)353x = ()354# Это переприсваивание – ошибка: все элементы в ``x`` должны быть int.355x = ("foo", "bar")356357# ``y`` может быть присвоен только пустому кортежу.358y: tuple[()] = ()359360z: tuple = ("foo", "bar")361# Эти переприсваивания OK: простой ``tuple`` эквивалентен ``tuple[Any, ...]``.362z = (1, 2, 3)363z = ()364```365366## Тип объектов классов367368Переменная, аннотированная `C`, может принимать значение типа `C`. Напротив, переменная, аннотированная `type[C]` (или [`typing.Type[C]`](https://python-all.ru/3.11/library/typing.html#typing.Type)), может принимать значения, которые сами являются классами – в частности, она будет принимать *объект класса* `C`. Например:369370```python371a = 3 # Имеет тип ``int``.372b = int # Имеет тип ``type[int]``.373c = type(a) # Также имеет тип ``type[int]``.374```375376Обратите внимание, что `type[C]` ковариантен:377378```python379class User: ...380class ProUser(User): ...381class TeamUser(User): ...382383def make_new_user(user_class: type[User]) -> User:384 # ...385 return user_class()386387make_new_user(User) # ОК388make_new_user(ProUser) # Также OK: ``type[ProUser]`` – подтип ``type[User]``.389make_new_user(TeamUser) # По-прежнему допустимо.390make_new_user(User()) # Ошибка: ожидался ``type[User]``, но получен ``User``.391make_new_user(int) # Ошибка: ``type[int]`` не является подтипом ``type[User]``.392```393394Единственными допустимыми параметрами для [`type`](https://python-all.ru/3.11/library/functions.html#type) являются классы, [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any), [переменные типа](https://python-all.ru/3.11/library/typing.html#generics) и объединения любых из этих типов. Например:395396```python397def new_non_team_user(user_class: type[BasicUser | ProUser]): ...398399new_non_team_user(BasicUser) # ОК400new_non_team_user(ProUser) # ОК401new_non_team_user(TeamUser) # Ошибка: ``type[TeamUser]`` не является подтипом402 # ``type[BasicUser | ProUser]``.403new_non_team_user(User) # Тоже ошибка.404```405406`type[Any]` эквивалентно [`type`](https://python-all.ru/3.11/library/functions.html#type), который является корнем [иерархии метаклассов](https://python-all.ru/3.11/reference/datamodel.html#metaclasses) Python.407408## Пользовательские обобщённые типы409410Пользовательский класс можно определить как обобщённый класс.411412```python413from typing import TypeVar, Generic414from logging import Logger415416T = TypeVar('T')417418class LoggedVar(Generic[T]):419 def __init__(self, value: T, name: str, logger: Logger) -> None:420 self.name = name421 self.logger = logger422 self.value = value423424 def set(self, new: T) -> None:425 self.log('Set ' + repr(self.value))426 self.value = new427428 def get(self) -> T:429 self.log('Get ' + repr(self.value))430 return self.value431432 def log(self, message: str) -> None:433 self.logger.info('%s: %s', self.name, message)434```435436`Generic[T]` в качестве базового класса определяет, что класс `LoggedVar` принимает один параметр типа `T`. Это также делает `T` допустимым типом внутри тела класса.437438Базовый класс [`Generic`](https://python-all.ru/3.11/library/typing.html#typing.Generic) определяет [`__class_getitem__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__class_getitem__) так, что `LoggedVar[T]` является допустимым типом:439440```python441from collections.abc import Iterable442443def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:444 for var in vars:445 var.set(0)446```447448Обобщённый тип может иметь любое количество переменных типа. Все разновидности [`TypeVar`](https://python-all.ru/3.11/library/typing.html#typing.TypeVar) допустимы в качестве параметров обобщённого типа:449450```python451from typing import TypeVar, Generic, Sequence452453T = TypeVar('T', contravariant=True)454B = TypeVar('B', bound=Sequence[bytes], covariant=True)455S = TypeVar('S', int, str)456457class WeirdTrio(Generic[T, B, S]):458 ...459```460461Каждый аргумент-переменная типа для [`Generic`](https://python-all.ru/3.11/library/typing.html#typing.Generic) должен быть уникальным. Поэтому такой код некорректен:462463```python464from typing import TypeVar, Generic465...466467T = TypeVar('T')468469class Pair(Generic[T, T]): # INVALID470 ...471```472473Можно использовать множественное наследование с [`Generic`](https://python-all.ru/3.11/library/typing.html#typing.Generic):474475```python476from collections.abc import Sized477from typing import TypeVar, Generic478479T = TypeVar('T')480481class LinkedList(Sized, Generic[T]):482 ...483```484485При наследовании от обобщённых классов некоторые параметры типа могут быть фиксированными:486487```python488from collections.abc import Mapping489from typing import TypeVar490491T = TypeVar('T')492493class MyDict(Mapping[str, T]):494 ...495```496497В этом случае `MyDict` имеет один параметр – `T`.498499Использование обобщённого класса без указания параметров типа подразумевает [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any) для каждой позиции. В следующем примере `MyIterable` не является обобщённым, но неявно наследуется от `Iterable[Any]`:500501```python502from collections.abc import Iterable503504class MyIterable(Iterable): # То же, что и Iterable[Any].505 ...506```507508Также поддерживаются пользовательские псевдонимы обобщённых типов. Примеры:509510```python511from collections.abc import Iterable512from typing import TypeVar513S = TypeVar('S')514Response = Iterable[S] | int515516# Тип возвращаемого значения здесь такой же, как Iterable[str] | int517def response(query: str) -> Response[str]:518 ...519520T = TypeVar('T', int, float, complex)521Vec = Iterable[tuple[T, T]]522523def inproduct(v: Vec[T]) -> T: # То же, что и Iterable[tuple[T, T]]524 return sum(x*y for x, y in v)525```526527Изменено в версии 3.7: [`Generic`](https://python-all.ru/3.11/library/typing.html#typing.Generic) больше не имеет собственного метакласса.528529Пользовательские обобщённые типы для выражений параметров также поддерживаются через переменные спецификации параметров в форме `Generic[P]`. Поведение согласуется с описанными выше переменными типов, так как переменные спецификации параметров обрабатываются модулем typing как специализированные переменные типов. Единственное исключение состоит в том, что список типов может использоваться для подстановки [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec):530531```python532>>> from typing import Generic, ParamSpec, TypeVar533534>>> T = TypeVar('T')535>>> P = ParamSpec('P')536537>>> class Z(Generic[T, P]): ...538...539>>> Z[int, [dict, float]]540__main__.Z[int, (<class 'dict'>, <class 'float'>)]541```542543Кроме того, обобщённый (generic) с единственной переменной спецификации параметра будет принимать списки параметров в виде `X[[Type1, Type2, ...]]`, а также `X[Type1, Type2, ...]` из эстетических соображений. Внутренне последний преобразуется в первый, поэтому следующие эквивалентны:544545```python546>>> class X(Generic[P]): ...547...548>>> X[int, str]549__main__.X[(<class 'int'>, <class 'str'>)]550>>> X[[int, str]]551__main__.X[(<class 'int'>, <class 'str'>)]552```553554Обратите внимание: обобщения с [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec) могут не иметь корректного `__parameters__` после подстановки в некоторых случаях, поскольку они предназначены в первую очередь для статической проверки типов.555556Изменено в версии 3.10: [`Generic`](https://python-all.ru/3.11/library/typing.html#typing.Generic) теперь можно параметризовать по выражениям параметров. Подробнее см. [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec) и [**PEP 612**](https://python-all.ru/3.11/library/typing.html).557558Пользовательский обобщённый класс может иметь ABC в качестве базовых классов без конфликта метаклассов. Обобщённые метаклассы не поддерживаются. Результат параметризации обобщённых типов кэшируется, и большинство типов в модуле typing являются [хэшируемыми](https://python-all.ru/3.11/glossary.html#term-hashable) и сравнимыми на равенство.559560## Тип [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any)561562Особым видом типа является [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any). Статический проверяющий типов будет считать каждый тип совместимым с [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any), а [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any) – совместимым с каждым типом.563564Это означает, что над значением типа [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any) можно выполнять любые операции или вызовы методов и присваивать его любой переменной:565566```python567from typing import Any568569a: Any = None570a = [] # ОК571a = 2 # ОК572573s: str = ''574s = a # ОК575576def foo(item: Any) -> int:577 # Проходит проверку типов; 'item' может быть любого типа,578 # и этот тип может иметь метод 'bar'579 item.bar()580 ...581```582583Обратите внимание: при присваивании значения типа [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any) более точному типу проверка типов не выполняется. Например, статический анализатор типов не сообщил об ошибке при присваивании `a` переменной `s`, хотя `s` была объявлена как тип [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) и во время выполнения получает значение [`int`](https://python-all.ru/3.11/library/functions.html#int)!584585Кроме того, все функции без указания типа возврата или типов параметров по умолчанию неявно используют [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any):586587```python588def legacy_parser(text):589 ...590 return data591592# Статический проверщик типов будет рассматривать вышеприведенное593# как имеющее ту же сигнатуру, что и:594def legacy_parser(text: Any) -> Any:595 ...596 return data597```598599Такое поведение позволяет использовать [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any) в качестве *запасного выхода*, когда нужно смешивать динамически и статически типизированный код.600601Сравните поведение [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any) с поведением [`object`](https://python-all.ru/3.11/library/functions.html#object). Как и [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any), каждый тип является подтипом [`object`](https://python-all.ru/3.11/library/functions.html#object). Однако, в отличие от [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any), обратное неверно: [`object`](https://python-all.ru/3.11/library/functions.html#object) *не* является подтипом любого другого типа.602603Это означает, что когда тип значения – [`object`](https://python-all.ru/3.11/library/functions.html#object), проверяющий типы будет отклонять почти все операции над ним, а присваивание его переменной (или использование в качестве возвращаемого значения) более специализированного типа является ошибкой типа. Например:604605```python606def hash_a(item: object) -> int:607 # Не проходит проверку типов; у объекта нет метода 'magic'.608 item.magic()609 ...610611def hash_b(item: Any) -> int:612 # Проходит проверку типов613 item.magic()614 ...615616# Проходит проверку типов, так как int и str являются подклассами object617hash_a(42)618hash_a("foo")619620# Проходит проверку типов, так как Any совместим со всеми типами621hash_b(42)622hash_b("foo")623```624625Используйте [`object`](https://python-all.ru/3.11/library/functions.html#object), чтобы указать, что значение может быть любого типа в типобезопасной манере. Используйте [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any), чтобы указать, что значение динамически типизировано.626627## Номинальная и структурная типизация628629Изначально [**PEP 484**](https://python-all.ru/3.11/library/typing.html) определял систему статической типизации Python как использующую *номинальное подтипирование*. Это означает, что класс `A` разрешён там, где ожидается класс `B`, если и только если `A` является подклассом `B`.630631Ранее это требование также применялось к абстрактным базовым классам, таким как [`Iterable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Iterable). Проблема такого подхода в том, что класс должен быть явно помечен для их поддержки, что непитонично и не похоже на то, что обычно делается в идиоматическом динамически типизированном коде Python. Например, следующее соответствует [**PEP 484**](https://python-all.ru/3.11/library/typing.html):632633```python634from collections.abc import Sized, Iterable, Iterator635636class Bucket(Sized, Iterable[int]):637 ...638 def __len__(self) -> int: ...639 def __iter__(self) -> Iterator[int]: ...640```641642[**PEP 544**](https://python-all.ru/3.11/library/typing.html) позволяет решить эту проблему, разрешая пользователям писать приведённый выше код без явных базовых классов в определении класса, что позволяет `Bucket` неявно считаться подтипом как `Sized`, так и `Iterable[int]` статическими проверяющими типов. Это называется *структурной подтипизацией* (или статической утиной типизацией):643644```python645from collections.abc import Iterator, Iterable646647class Bucket: # Примечание: базовые классы отсутствуют648 ...649 def __len__(self) -> int: ...650 def __iter__(self) -> Iterator[int]: ...651652def collect(items: Iterable[int]) -> int: ...653result = collect(Bucket()) # Проходит проверку типов654```655656Более того, наследуя специальный класс [`Protocol`](https://python-all.ru/3.11/library/typing.html#typing.Protocol), пользователь может определять новые пользовательские протоколы, чтобы в полной мере использовать структурное подтипирование (см. примеры ниже).657658## Содержимое модуля659660Модуль `typing` определяет следующие классы, функции и декораторы.661662### Специальные примитивы типизации663664#### Специальные типы665666Их можно использовать в качестве типов в аннотациях. Они не поддерживают подписку с помощью `[]`.667668#### `typing.Any`669670Специальный тип, указывающий на неограниченный тип.671672- Каждый тип совместим с [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any).673- [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any) совместим с каждым типом.674675Изменено в версии 3.11: [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any) теперь можно использовать в качестве базового класса. Это может быть полезно для предотвращения ошибок проверки типов в классах, которые могут использовать утиную типизацию где угодно или являются сильно динамичными.676677#### `typing.AnyStr`678679[Ограниченная переменная типа](https://python-all.ru/3.11/library/typing.html#typing-constrained-typevar).680681Определение:682683```python684AnyStr = TypeVar('AnyStr', str, bytes)685```686687`AnyStr` предназначен для функций, которые могут принимать аргументы типа [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes), но не допускают их смешивания.688689Например:690691```python692def concat(a: AnyStr, b: AnyStr) -> AnyStr:693 return a + b694695concat("foo", "bar") # OK, результат имеет тип 'str'696concat(b"foo", b"bar") # OK, результат имеет тип 'bytes'697concat("foo", b"bar") # Ошибка, нельзя смешивать str и bytes698```699700Обратите внимание, что, несмотря на название, `AnyStr` не имеет никакого отношения к типу [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any) и не означает «любая строка». В частности, `AnyStr` и `str | bytes` отличаются друг от друга и имеют разные сценарии использования:701702```python703# Неверное использование AnyStr:704# Переменная типа используется только один раз в сигнатуре функции,705# поэтому не может быть «решена» проверщиком типов706def greet_bad(cond: bool) -> AnyStr:707 return "hi there!" if cond else b"greetings!"708709# Лучший способ аннотировать эту функцию:710def greet_proper(cond: bool) -> str | bytes:711 return "hi there!" if cond else b"greetings!"712```713714#### `typing.LiteralString`715716Специальный тип, включающий только строковые литералы.717718Любой строковый литерал совместим с `LiteralString`, как и другой `LiteralString`. Однако объект, типизированный просто как `str`, – нет. Строка, созданная композицией объектов типа `LiteralString`, также приемлема как `LiteralString`.719720Пример:721722```python723def run_query(sql: LiteralString) -> None:724 ...725726def caller(arbitrary_string: str, literal_string: LiteralString) -> None:727 run_query("SELECT * FROM students") # ОК728 run_query(literal_string) # ОК729 run_query("SELECT * FROM " + literal_string) # ОК730 run_query(arbitrary_string) # ошибка проверки типов731 run_query( # ошибка проверки типов732 f"SELECT * FROM students WHERE name = {arbitrary_string}"733 )734```735736`LiteralString` полезен для чувствительных API, где произвольные пользовательские строки могут создавать проблемы. Например, два приведённых выше случая, которые вызывают ошибки проверки типов, могут быть уязвимы для SQL-инъекций.737738Подробнее см. [**PEP 675**](https://python-all.ru/3.11/library/typing.html).739740Новое в версии 3.11.741742#### `typing.Never`743744[Нижний тип](https://python-all.ru/3.11/library/typing.html) – тип, не имеющий членов.745746Это можно использовать для определения функции, которая никогда не должна вызываться, или функции, которая никогда не возвращает результат:747748```python749from typing import Never750751def never_call_me(arg: Never) -> None:752 pass753754def int_or_str(arg: int | str) -> None:755 never_call_me(arg) # ошибка проверки типов756 match arg:757 case int():758 print("It's an int")759 case str():760 print("It's a str")761 case _:762 never_call_me(arg) # OK, аргумент имеет тип Never763```764765Новое в версии 3.11: В более старых версиях Python для выражения той же концепции может использоваться [`NoReturn`](https://python-all.ru/3.11/library/typing.html#typing.NoReturn). `Never` был добавлен, чтобы сделать предполагаемый смысл более явным.766767#### `typing.NoReturn`768769Специальный тип, указывающий, что функция никогда не возвращает результат.770771Например:772773```python774from typing import NoReturn775776def stop() -> NoReturn:777 raise RuntimeError('no way')778```779780`NoReturn` также может использоваться как [нижний тип](https://python-all.ru/3.11/library/typing.html), тип, не имеющий значений. Начиная с Python 3.11, для этой концепции следует использовать тип [`Never`](https://python-all.ru/3.11/library/typing.html#typing.Never). Инструменты проверки типов должны считать их эквивалентными.781782Новое в версии 3.6.2.783784#### `typing.Self`785786Специальный тип для представления текущего вложенного класса.787788Например:789790```python791from typing import Self, reveal_type792793class Foo:794 def return_self(self) -> Self:795 ...796 return self797798class SubclassOfFoo(Foo): pass799800reveal_type(Foo().return_self()) # Раскрытый тип – "Foo"801reveal_type(SubclassOfFoo().return_self()) # Раскрытый тип – "SubclassOfFoo"802```803804Эта аннотация семантически эквивалентна следующему, хотя и в более краткой форме:805806```python807from typing import TypeVar808809Self = TypeVar("Self", bound="Foo")810811class Foo:812 def return_self(self: Self) -> Self:813 ...814 return self815```816817В общем случае, если что-то возвращает `self`, как в примерах выше, следует использовать `Self` в качестве аннотации возвращаемого типа. Если `Foo.return_self` был аннотирован как возвращающий `"Foo"`, то анализатор типов выведет, что объект, возвращённый из `SubclassOfFoo.return_self`, имеет тип `Foo` , а не `SubclassOfFoo`.818819Другие распространённые случаи использования включают:820821- [`classmethod`](https://python-all.ru/3.11/library/functions.html#classmethod), которые используются как альтернативные конструкторы и возвращают экземпляры параметра `cls`.822- Аннотирование метода [`__enter__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__enter__), который возвращает self.823824Не следует использовать `Self` в качестве аннотации возвращаемого типа, если метод не гарантирует возврат экземпляра подкласса при наследовании класса:825826```python827class Eggs:828 # Self здесь была бы некорректной аннотацией возврата,829 # так как возвращаемый объект всегда является экземпляром Eggs,830 # даже в подклассах.831 def returns_eggs(self) -> "Eggs":832 return Eggs()833```834835См. [**PEP 673**](https://python-all.ru/3.11/library/typing.html) для получения дополнительных сведений.836837Новое в версии 3.11.838839#### `typing.TypeAlias`840841Специальная аннотация для явного объявления [псевдонима типа](https://python-all.ru/3.11/library/typing.html#type-aliases).842843Например:844845```python846from typing import TypeAlias847848Factors: TypeAlias = list[int]849```850851`TypeAlias` особенно полезен для аннотирования псевдонимов, использующих прямые ссылки, поскольку средствам проверки типов может быть трудно отличить их от обычных присваиваний переменных:852853```python854from typing import Generic, TypeAlias, TypeVar855856T = TypeVar("T")857858# "Box" ещё не существует,859# поэтому для прямой ссылки приходится использовать кавычки.860# Использование ``TypeAlias`` сообщает тайпчекеру, что это объявление псевдонима типа,861# а не присваивание переменной строкового значения.862BoxOfStrings: TypeAlias = "Box[str]"863864class Box(Generic[T]):865 @classmethod866 def make_box_of_strings(cls) -> BoxOfStrings: ...867```868869См. [**PEP 613**](https://python-all.ru/3.11/library/typing.html) для получения дополнительных сведений.870871Новое в версии 3.10.872873#### Специальные формы874875Их можно использовать в качестве типов в аннотациях. Они все поддерживают индексацию с помощью `[]`, но каждый из них имеет уникальный синтаксис.876877#### `typing.Union`878879Тип объединения; `Union[X, Y]` эквивалентно `X | Y` и означает X или Y.880881Для определения объединения используйте, например, `Union[int, str]` или сокращённую запись `int | str`. Рекомендуется использовать сокращённую запись. Подробности:882883- Аргументы должны быть типами, и их должно быть как минимум один.884- Объединения объединений разворачиваются, например:885886 ```python887 Union[Union[int, str], float] == Union[int, str, float]888 ```889- Объединения из одного аргумента исчезают, например:890891 ```python892 Union[int] == int # Конструктор на самом деле возвращает int893 ```894- Повторяющиеся аргументы пропускаются, например:895896 ```python897 Union[int, str, int] == Union[int, str] == int | str898 ```899- При сравнении объединений порядок аргументов игнорируется, например:900901 ```python902 Union[int, str] == Union[str, int]903 ```904- Нельзя наследовать или создавать экземпляр `Union`.905- Нельзя записать `Union[X][Y]`.906907Изменено в версии 3.7: Явные подклассы не удаляются из объединений во время выполнения.908909Изменено в версии 3.10: Объединения теперь можно записывать как `X | Y`. См. [выражения типов объединений](https://python-all.ru/3.11/library/stdtypes.html#types-union).910911#### `typing.Optional`912913`Optional[X]` эквивалентен `X | None` (или `Union[X, None]`).914915Обратите внимание, что это не то же самое, что необязательный аргумент, который имеет значение по умолчанию. Необязательный аргумент с значением по умолчанию не требует квалификатора `Optional` в своей аннотации типа только потому, что он необязателен. Например:916917```python918def foo(arg: int = 0) -> None:919 ...920```921922С другой стороны, если явное значение `None` допускается, то использование `Optional` уместно, независимо от того, является ли аргумент необязательным или нет. Например:923924```python925def foo(arg: Optional[int] = None) -> None:926 ...927```928929Изменено в версии 3.10: Optional теперь можно записывать как `X | None`. См. [выражения типов объединений](https://python-all.ru/3.11/library/stdtypes.html#types-union).930931#### `typing.Concatenate`932933Специальная форма для аннотирования функций высшего порядка.934935`Concatenate` может использоваться совместно с [Callable](https://python-all.ru/3.11/library/typing.html#annotating-callables) и [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec) для аннотации вызываемого объекта высшего порядка, который добавляет, удаляет или преобразует параметры другого вызываемого объекта. Использование имеет форму `Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]`. `Concatenate` в настоящее время допустим только в качестве первого аргумента [Callable](https://python-all.ru/3.11/library/typing.html#annotating-callables). Последний параметр `Concatenate` должен быть [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec) или многоточием (`...`).936937Например, чтобы аннотировать декоратор `with_lock`, который предоставляет [`threading.Lock`](https://python-all.ru/3.11/library/threading.html#threading.Lock) декорируемой функции, можно использовать `Concatenate`, чтобы указать, что `with_lock` ожидает вызываемый объект, который принимает `Lock` в качестве первого аргумента, и возвращает вызываемый объект с другой сигнатурой типа. В этом случае [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec) указывает на то, что типы параметров возвращаемого вызываемого объекта зависят от типов параметров передаваемого вызываемого объекта:938939```python940from collections.abc import Callable941from threading import Lock942from typing import Concatenate, ParamSpec, TypeVar943944P = ParamSpec('P')945R = TypeVar('R')946947# Используйте эту блокировку, чтобы гарантировать, что только один поток выполняет функцию948# в любой момент времени.949my_lock = Lock()950951def with_lock(f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:952 '''Типобезопасный декоратор, предоставляющий блокировку.'''953 def inner(*args: P.args, **kwargs: P.kwargs) -> R:954 # Передайте блокировку в качестве первого аргумента.955 return f(my_lock, *args, **kwargs)956 return inner957958@with_lock959def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:960 '''Складывайте список чисел потокобезопасным способом.'''961 with lock:962 return sum(numbers)963964# Нам не нужно передавать блокировку вручную благодаря декоратору.965sum_threadsafe([1.1, 2.2, 3.3])966```967968Новое в версии 3.10.969970> **См. также**971>972> - [**PEP 612**](https://python-all.ru/3.11/library/typing.html) – Переменные спецификации параметров (PEP, в котором были введены `ParamSpec` и `Concatenate`)973> - [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec)974> - [Аннотация вызываемых объектов](https://python-all.ru/3.11/library/typing.html#annotating-callables)975976#### `typing.Literal`977978Специальная форма типизации для определения «литеральных типов».979980`Literal` можно использовать, чтобы указать проверяющим типа, что аннотированный объект имеет значение, эквивалентное одному из предоставленных литералов.981982Например:983984```python985def validate_simple(data: Any) -> Literal[True]: # всегда возвращает True986 ...987988Mode: TypeAlias = Literal['r', 'rb', 'w', 'wb']989def open_helper(file: str, mode: Mode) -> str:990 ...991992open_helper('/some/path', 'r') # Проходит проверку типов993open_helper('/other/path', 'typo') # Ошибка в тайпчекере994```995996`Literal[...]` нельзя наследовать. Во время выполнения произвольное значение допускается в качестве аргумента типа для `Literal[...]`, но проверяющие типа могут накладывать ограничения. См. [**PEP 586**](https://python-all.ru/3.11/library/typing.html) для получения дополнительных сведений о литеральных типах.997998Новое в версии 3.8.9991000Изменено в версии 3.9.1: `Literal` теперь дедуплицирует параметры. Сравнения на равенство объектов `Literal` больше не зависят от порядка. Объекты `Literal` теперь будут вызывать исключение [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError) при сравнении на равенство, если один из их параметров не является [хешируемым](https://python-all.ru/3.11/glossary.html#term-hashable).10011002#### `typing.ClassVar`10031004Специальная конструкция типа для пометки переменных класса.10051006Как представлено в [**PEP 526**](https://python-all.ru/3.11/library/typing.html), аннотация переменной, обёрнутая в ClassVar, указывает, что данный атрибут предназначен для использования в качестве переменной класса и не должен устанавливаться на экземплярах этого класса. Использование:10071008```python1009class Starship:1010 stats: ClassVar[dict[str, int]] = {} # переменная класса1011 damage: int = 10 # переменная экземпляра1012```10131014[`ClassVar`](https://python-all.ru/3.11/library/typing.html#typing.ClassVar) принимает только типы и не может быть дополнительно индексирован.10151016[`ClassVar`](https://python-all.ru/3.11/library/typing.html#typing.ClassVar) сам по себе не является классом и не должен использоваться с [`isinstance()`](https://python-all.ru/3.11/library/functions.html#isinstance) или [`issubclass()`](https://python-all.ru/3.11/library/functions.html#issubclass). [`ClassVar`](https://python-all.ru/3.11/library/typing.html#typing.ClassVar) не меняет поведение Python во время выполнения, но может использоваться сторонними проверяющими типов. Например, проверяющий типов может отметить следующий код как ошибочный:10171018```python1019enterprise_d = Starship(3000)1020enterprise_d.stats = {} # Ошибка: установка переменной класса на экземпляре1021Starship.stats = {} # Это корректно.1022```10231024Новое в версии 3.5.3.10251026#### `typing.Final`10271028Специальная конструкция типизации для указания проверяющим типам, что имена являются финальными.10291030Финальные имена нельзя переназначать ни в какой области видимости. Финальные имена, объявленные в области класса, нельзя переопределять в подклассах.10311032Например:10331034```python1035MAX_SIZE: Final = 90001036MAX_SIZE += 1 # Ошибка, выдаваемая проверщиком типов10371038class Connection:1039 TIMEOUT: Final[int] = 1010401041class FastConnector(Connection):1042 TIMEOUT = 1 # Ошибка, выдаваемая проверщиком типов1043```10441045Проверка этих свойств во время выполнения не выполняется. Подробнее см. [**PEP 591**](https://python-all.ru/3.11/library/typing.html).10461047Новое в версии 3.8.10481049#### `typing.Required`10501051Специальная конструкция типизации для пометки ключа [`TypedDict`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict) как обязательного.10521053В основном это полезно для `total=False` TypedDict. Подробнее см. [`TypedDict`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict) и [**PEP 655**](https://python-all.ru/3.11/library/typing.html).10541055Новое в версии 3.11.10561057#### `typing.NotRequired`10581059Специальная конструкция типизации для пометки ключа [`TypedDict`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict) как потенциально отсутствующего.10601061Подробнее см. [`TypedDict`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict) и [**PEP 655**](https://python-all.ru/3.11/library/typing.html).10621063Новое в версии 3.11.10641065#### `typing.Annotated`10661067Специальная форма типизации для добавления контекстно-зависимых метаданных к аннотации.10681069Добавляет метаданные `x` к заданному типу `T` с помощью аннотации `Annotated[T, x]`. Метаданные, добавленные с помощью `Annotated`, могут использоваться инструментами статического анализа или во время выполнения. Во время выполнения метаданные хранятся в атрибуте `__metadata__`.10701071Если библиотека или инструмент встречает аннотацию `Annotated[T, x]` и не имеет специальной логики для метаданных, он должен игнорировать метаданные и просто рассматривать аннотацию как `T`. Таким образом, `Annotated` может быть полезна для кода, который хочет использовать аннотации для целей, выходящих за рамки системы статической типизации Python.10721073Использование `Annotated[T, x]` в качестве аннотации по-прежнему допускает статическую проверку типов для `T`, поскольку проверяющие типы просто игнорируют метаданные `x`. Таким образом, `Annotated` отличается от декоратора [`@no_type_check`](https://python-all.ru/3.11/library/typing.html#typing.no_type_check), который также можно использовать для добавления аннотаций за пределами системы типизации, но полностью отключает проверку типов для функции или класса.10741075Ответственность за интерпретацию метаданных лежит на инструменте или библиотеке, встречающей аннотацию `Annotated`. Инструмент или библиотека, встречающие тип `Annotated`, могут просмотреть элементы метаданных, чтобы определить, представляют ли они интерес (например, с помощью [`isinstance()`](https://python-all.ru/3.11/library/functions.html#isinstance)).10761077#### `Annotated[<type>, <metadata>]`10781079Вот пример того, как можно использовать `Annotated` для добавления метаданных к аннотациям типов при выполнении анализа диапазонов:10801081```python1082@dataclass1083class ValueRange:1084 lo: int1085 hi: int10861087T1 = Annotated[int, ValueRange(-10, 5)]1088T2 = Annotated[T1, ValueRange(-20, 3)]1089```10901091Подробности синтаксиса:10921093- Первый аргумент `Annotated` должен быть допустимым типом1094- Можно указать несколько элементов метаданных (`Annotated` поддерживает вариативные аргументы):10951096 ```python1097 @dataclass1098 class ctype:1099 kind: str11001101 Annotated[int, ValueRange(3, 10), ctype("char")]1102 ```11031104 Инструмент, потребляющий аннотации, сам решает, разрешено ли клиенту добавлять несколько элементов метаданных к одной аннотации и как объединять эти аннотации.1105- `Annotated` должен индексироваться как минимум двумя аргументами ( `Annotated[int]` недопустимо)1106- Порядок элементов метаданных сохраняется и важен для проверки равенства:11071108 ```python1109 assert Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[1110 int, ctype("char"), ValueRange(3, 10)1111 ]1112 ```1113- Вложенные типы `Annotated` уплощаются. Порядок элементов метаданных начинается с самой внутренней аннотации:11141115 ```python1116 assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[1117 int, ValueRange(3, 10), ctype("char")1118 ]1119 ```1120- Дублирующиеся элементы метаданных не удаляются:11211122 ```python1123 assert Annotated[int, ValueRange(3, 10)] != Annotated[1124 int, ValueRange(3, 10), ValueRange(3, 10)1125 ]1126 ```1127- `Annotated` можно использовать с вложенными и обобщёнными псевдонимами:11281129 ```python1130 @dataclass1131 class MaxLen:1132 value: int11331134 T = TypeVar("T")1135 Vec: TypeAlias = Annotated[list[tuple[T, T]], MaxLen(10)]11361137 assert Vec[int] == Annotated[list[tuple[int, int]], MaxLen(10)]1138 ```1139- `Annotated` нельзя использовать с распакованным [`TypeVarTuple`](https://python-all.ru/3.11/library/typing.html#typing.TypeVarTuple):11401141 ```python1142 Variadic: TypeAlias = Annotated[*Ts, Ann1] # НЕДОПУСТИМО1143 ```11441145 Это будет эквивалентно:11461147 ```python1148 Annotated[T1, T2, T3, ..., Ann1]1149 ```11501151 где `T1`, `T2` и т.д. являются [`TypeVars`](https://python-all.ru/3.11/library/typing.html#typing.TypeVar). Это было бы недопустимо: в Annotated следует передавать только один тип.1152- По умолчанию [`get_type_hints()`](https://python-all.ru/3.11/library/typing.html#typing.get_type_hints) удаляет метаданные из аннотаций. Передайте `include_extras=True`, чтобы сохранить метаданные:11531154 ```pycon1155 >>> from typing import Annotated, get_type_hints1156 >>> def func(x: Annotated[int, "metadata"]) -> None: pass1157 ...1158 >>> get_type_hints(func)1159 {'x': <class 'int'>, 'return': <class 'NoneType'>}1160 >>> get_type_hints(func, include_extras=True)1161 {'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}1162 ```1163- Во время выполнения метаданные, связанные с типом `Annotated`, можно получить через атрибут `__metadata__`:11641165 ```pycon1166 >>> from typing import Annotated1167 >>> X = Annotated[int, "very", "important", "metadata"]1168 >>> X1169 typing.Annotated[int, 'very', 'important', 'metadata']1170 >>> X.__metadata__1171 ('very', 'important', 'metadata')1172 ```11731174> **См. также**1175>1176> **[**PEP 593**](https://python-all.ru/3.11/library/typing.html) – Гибкие аннотации функций и переменных**1177>1178> PEP, вводящий `Annotated` в стандартную библиотеку.11791180Новое в версии 3.9.11811182#### `typing.TypeGuard`11831184Специальная конструкция типов для пометки пользовательских функций-охранников типа.11851186`TypeGuard` можно использовать для аннотации возвращаемого типа пользовательской функции-охранника типа. `TypeGuard` принимает только один аргумент типа. Во время выполнения функции, отмеченные таким образом, должны возвращать логическое значение.11871188`TypeGuard` направлен на использование *сужения типа* – метода, используемого статическими проверками типов для определения более точного типа выражения в потоке кода программы. Обычно сужение типа выполняется путем анализа условного потока кода и применения сужения к блоку кода. Условное выражение в этом случае иногда называют «охранником типа»:11891190```python1191def is_str(val: str | float):1192 # защита типа "isinstance"1193 if isinstance(val, str):1194 # Тип ``val`` сужается до ``str``1195 ...1196 else:1197 # Иначе тип ``val`` сужается до ``float``.1198 ...1199```12001201Иногда бывает удобно использовать пользовательскую логическую функцию в качестве охранника типа. Такая функция должна использовать `TypeGuard[...]` в качестве своего возвращаемого типа, чтобы предупредить статические проверки типов об этом намерении.12021203Использование `-> TypeGuard` сообщает статическому анализатору типов, что для данной функции:120412051. Возвращаемое значение – boolean.12062. Если возвращаемое значение – `True`, то тип аргумента – это тип внутри `TypeGuard`.12071208Например:12091210```python1211def is_str_list(val: list[object]) -> TypeGuard[list[str]]:1212 '''Определяет, все ли объекты в списке являются строками'''1213 return all(isinstance(x, str) for x in val)12141215def func1(val: list[object]):1216 if is_str_list(val):1217 # Тип ``val`` сужается до ``list[str]``.1218 print(" ".join(val))1219 else:1220 # Тип ``val`` остаётся как ``list[object]``.1221 print("Not a list of strings!")1222```12231224Если `is_str_list` является методом класса или экземпляра, то тип в `TypeGuard` соответствует типу второго параметра после `cls` или `self`.12251226Короче говоря, форма `def foo(arg: TypeA) -> TypeGuard[TypeB]: ...` означает, что если `foo(arg)` возвращает `True`, то `arg` сужается с `TypeA` до `TypeB`.12271228> **Примечание**1229>1230> `TypeB` не обязательно должен быть более узкой формой `TypeA` – он может быть даже более широкой формой. Основная причина – допускать такие ситуации, как сужение `list[object]` до `list[str]`, даже если последний не является подтипом первого, поскольку `list` инвариантен. Ответственность за написание типобезопасных охранников типа возлагается на пользователя.12311232`TypeGuard` также работает с переменными типа. См. [**PEP 647**](https://python-all.ru/3.11/library/typing.html) для подробностей.12331234Новое в версии 3.10.12351236#### `typing.Unpack`12371238Оператор typing для концептуальной пометки объекта как распакованного.12391240Например, использование оператора распаковки `*` для [кортежа переменных типа](https://python-all.ru/3.11/library/typing.html#typevartuple) эквивалентно использованию `Unpack`, чтобы пометить кортеж переменных типа как распакованный:12411242```python1243Ts = TypeVarTuple('Ts')1244tup: tuple[*Ts]1245# Фактически делает:1246tup: tuple[Unpack[Ts]]1247```12481249На самом деле, `Unpack` и `*` можно использовать взаимозаменяемо в контексте типов [`typing.TypeVarTuple`](https://python-all.ru/3.11/library/typing.html#typing.TypeVarTuple) и [`builtins.tuple`](https://python-all.ru/3.11/library/stdtypes.html#tuple). В старых версиях Python можно встретить явное использование `Unpack`, когда `*` нельзя было применять в определённых местах:12501251```python1252# В старых версиях Python TypeVarTuple и Unpack1253# находятся в пакете обратной совместимости `typing_extensions`.1254from typing_extensions import TypeVarTuple, Unpack12551256Ts = TypeVarTuple('Ts')1257tup: tuple[*Ts] # Синтаксическая ошибка на Python <= 3.10!1258tup: tuple[Unpack[Ts]] # Семантически эквивалентно и обратно совместимо1259```12601261Новое в версии 3.11.12621263#### Построение обобщённых типов12641265Следующие классы не следует использовать напрямую в качестве аннотаций. Их предназначение – быть строительными блоками для создания обобщённых типов.12661267#### `class typing.Generic`12681269Абстрактный базовый класс для обобщённых типов.12701271Обобщённый тип обычно объявляется наследованием от экземпляра этого класса с одной или несколькими переменными типа. Например, обобщённый тип отображения может быть определён так:12721273```python1274class Mapping(Generic[KT, VT]):1275 def __getitem__(self, key: KT) -> VT:1276 ...1277 # И т.д.1278```12791280Затем этот класс можно использовать следующим образом:12811282```python1283X = TypeVar('X')1284Y = TypeVar('Y')12851286def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:1287 try:1288 return mapping[key]1289 except KeyError:1290 return default1291```12921293#### `class typing.TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False)`12941295Переменная типа.12961297Использование:12981299```python1300T = TypeVar('T') # Может быть чем угодно1301S = TypeVar('S', bound=str) # Может быть любым подтипом str1302A = TypeVar('A', str, bytes) # Должно быть ровно str или bytes1303```13041305Переменные типа существуют в первую очередь для статических проверок типов. Они служат параметрами для обобщённых типов, а также для определений обобщённых функций и псевдонимов типов. Дополнительную информацию об обобщённых типах см. в [`Generic`](https://python-all.ru/3.11/library/typing.html#typing.Generic). Обобщённые функции работают следующим образом:13061307```python1308def repeat(x: T, n: int) -> Sequence[T]:1309 """Возвращает список, содержащий n ссылок на x."""1310 return [x]*n13111312def print_capitalized(x: S) -> S:1313 """Печатает x с заглавной буквы и возвращает x."""1314 print(x.capitalize())1315 return x13161317def concatenate(x: A, y: A) -> A:1318 """Складывает две строки или два объекта bytes."""1319 return x + y1320```13211322Обратите внимание, что переменные типа могут быть *связаны*, *ограничены* или ни тем, ни другим, но не могут быть одновременно и связаны, *и* ограничены.13231324Переменные типа могут быть помечены как ковариантные или контравариантные путём передачи `covariant=True` или `contravariant=True`. См. [**PEP 484**](https://python-all.ru/3.11/library/typing.html) для получения дополнительных сведений. По умолчанию переменные типа инвариантны.13251326Связанные переменные типа и ограниченные переменные типа имеют разную семантику в нескольких важных аспектах. Использование *связанной* переменной типа означает, что `TypeVar` будет разрешена с использованием наиболее конкретного типа:13271328```python1329x = print_capitalized('a string')1330reveal_type(x) # выявленный тип – str13311332class StringSubclass(str):1333 pass13341335y = print_capitalized(StringSubclass('another string'))1336reveal_type(y) # раскрытый тип – StringSubclass13371338z = print_capitalized(45) # ошибка: int не является подтипом str1339```13401341Переменные типа могут быть связаны с конкретными типами, абстрактными типами (ABC или протоколами) и даже объединениями типов:13421343```python1344U = TypeVar('U', bound=str|bytes) # Может быть любым подтипом объединения str|bytes1345V = TypeVar('V', bound=SupportsAbs) # Может быть чем угодно с методом __abs__1346```13471348Однако использование переменной типа с *ограничениями* означает, что `TypeVar` может быть выведен только как один из заданных ограничений:13491350```python1351a = concatenate('one', 'two')1352reveal_type(a) # выявленный тип – str13531354b = concatenate(StringSubclass('one'), StringSubclass('two'))1355reveal_type(b) # выявленный тип – str, несмотря на то что передан StringSubclass13561357c = concatenate('one', b'two') # ошибка: типовая переменная 'A' может быть либо str, либо bytes в вызове функции, но не обоими одновременно1358```13591360Во время выполнения `isinstance(x, T)` вызовет [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError).13611362#### `__name__`13631364Имя переменной типа.13651366#### `__covariant__`13671368Определяет, помечена ли переменная типа как ковариантная.13691370#### `__contravariant__`13711372Определяет, помечена ли переменная типа как контравариантная.13731374#### `__bound__`13751376Граница переменной типа, если она есть.13771378#### `__constraints__`13791380Кортеж, содержащий ограничения переменной типа, если они есть.13811382#### `class typing.TypeVarTuple(name)`13831384Кортежная переменная типа. Специализированная форма [переменной типа](https://python-all.ru/3.11/library/typing.html#typevar), которая позволяет использовать *вариативные* обобщения.13851386Использование:13871388```python1389T = TypeVar("T")1390Ts = TypeVarTuple("Ts")13911392def move_first_element_to_last(tup: tuple[T, *Ts]) -> tuple[*Ts, T]:1393 return (*tup[1:], tup[0])1394```13951396Обычная переменная типа позволяет параметризацию одним типом. Кортежная переменная типа, напротив, позволяет параметризацию *произвольным* количеством типов, действуя как *произвольное* количество переменных типа, упакованных в кортеж. Например:13971398```python1399# T привязан к int, Ts привязан к ()1400# Возвращаемое значение – (1,), тип которого tuple[int]1401move_first_element_to_last(tup=(1,))14021403# T привязан к int, Ts привязан к (str,)1404# Возвращаемое значение – ('spam', 1), тип которого tuple[str, int]1405move_first_element_to_last(tup=(1, 'spam'))14061407# T привязан к int, Ts привязан к (str, float)1408# Возвращаемое значение – ('spam', 3.0, 1), тип которого tuple[str, float, int]1409move_first_element_to_last(tup=(1, 'spam', 3.0))14101411# Это не проходит проверку типов (и завершается ошибкой во время выполнения)1412# потому что tuple[()] несовместим с tuple[T, *Ts]1413# (требуется хотя бы один элемент)1414move_first_element_to_last(tup=())1415```14161417Обратите внимание на использование оператора распаковки `*` в `tuple[T, *Ts]`. Концептуально можно представить `Ts` как кортеж переменных типа `(T1, T2, ...)`. Тогда `tuple[T, *Ts]` станет `tuple[T, *(T1, T2, ...)]`, что эквивалентно `tuple[T, T1, T2, ...]`. (Обратите внимание, что в более старых версиях Python это могло быть записано с использованием [`Unpack`](https://python-all.ru/3.11/library/typing.html#typing.Unpack), например, `Unpack[Ts]`.)14181419Кортежные переменные типа *всегда* должны быть распакованы. Это помогает отличать кортежные переменные типа от обычных:14201421```python1422x: Ts # Недействительно1423x: tuple[Ts] # Недействительно1424x: tuple[*Ts] # Правильный способ сделать это1425```14261427Кортежные переменные типа можно использовать в тех же контекстах, что и обычные переменные типа. Например, в определениях классов, аргументах и возвращаемых типах:14281429```python1430Shape = TypeVarTuple("Shape")1431class Array(Generic[*Shape]):1432 def __getitem__(self, key: tuple[*Shape]) -> float: ...1433 def __abs__(self) -> "Array[*Shape]": ...1434 def get_shape(self) -> tuple[*Shape]: ...1435```14361437Кортежные переменные типа можно без проблем комбинировать с обычными переменными типа:14381439```python1440DType = TypeVar('DType')1441Shape = TypeVarTuple('Shape')14421443class Array(Generic[DType, *Shape]): # Это нормально1444 pass14451446class Array2(Generic[*Shape, DType]): # Это тоже нормально1447 pass14481449class Height: ...1450class Width: ...14511452float_array_1d: Array[float, Height] = Array() # Совершенно нормально1453int_array_2d: Array[int, Height, Width] = Array() # Да, тоже нормально1454```14551456Однако обратите внимание, что в одном списке аргументов типа или параметров типа может присутствовать не более одной кортежной переменной типа:14571458```python1459x: tuple[*Ts, *Ts] # Недействительно1460class Array(Generic[*Shape, *Shape]): # Недействительно1461 pass1462```14631464Наконец, распакованная кортежная переменная типа может использоваться в качестве аннотации типа для `*args`:14651466```python1467def call_soon(1468 callback: Callable[[*Ts], None],1469 *args: *Ts1470) -> None:1471 ...1472 callback(*args)1473```14741475В отличие от нераспакованных аннотаций `*args`, например `*args: int`, которые указывают, что *все* аргументы имеют тип `int`, `*args: *Ts` позволяет ссылаться на типы *отдельных* аргументов в `*args`. Здесь это позволяет нам убедиться, что типы `*args`, передаваемых в `call_soon`, соответствуют типам (позиционных) аргументов `callback`.14761477Подробнее о кортежах переменных типа см. в [**PEP 646**](https://python-all.ru/3.11/library/typing.html).14781479#### `__name__`14801481Имя кортежа переменных типа.14821483Новое в версии 3.11.14841485#### `class typing.ParamSpec(name, *, bound=None, covariant=False, contravariant=False)`14861487Переменная спецификации параметров. Специализированная версия [переменных типа](https://python-all.ru/3.11/library/typing.html#typevar).14881489Использование:14901491```python1492P = ParamSpec('P')1493```14941495Переменные спецификации параметров существуют в первую очередь для статических проверок типов. Они используются для передачи типов параметров одного вызываемого объекта другому вызываемому объекту – шаблон, часто встречающийся в функциях высшего порядка и декораторах. Они допустимы только при использовании в `Concatenate`, или как первый аргумент `Callable`, или как параметры пользовательских обобщённых типов (Generics). См. [`Generic`](https://python-all.ru/3.11/library/typing.html#typing.Generic) для получения дополнительной информации об обобщённых типах.14961497Например, чтобы добавить базовое логирование в функцию, можно создать декоратор `add_logging` для логирования вызовов функций. Переменная спецификации параметров сообщает проверяющему типы, что вызываемый объект, переданный в декоратор, и новый вызываемый объект, возвращаемый им, имеют взаимозависимые параметры типа:14981499```python1500from collections.abc import Callable1501from typing import TypeVar, ParamSpec1502import logging15031504T = TypeVar('T')1505P = ParamSpec('P')15061507def add_logging(f: Callable[P, T]) -> Callable[P, T]:1508 '''Типобезопасный декоратор для добавления логирования в функцию.'''1509 def inner(*args: P.args, **kwargs: P.kwargs) -> T:1510 logging.info(f'{f.__name__} was called')1511 return f(*args, **kwargs)1512 return inner15131514@add_logging1515def add_two(x: float, y: float) -> float:1516 '''Складывает два числа.'''1517 return x + y1518```15191520Без `ParamSpec` самый простой способ аннотировать это ранее заключался в использовании [`TypeVar`](https://python-all.ru/3.11/library/typing.html#typing.TypeVar) с границей `Callable[..., Any]`. Однако это вызывает две проблемы:152115221. Проверяющий типы не может проверить типы функции `inner`, потому что `*args` и `**kwargs` должны быть типизированы как [`Any`](https://python-all.ru/3.11/library/typing.html#typing.Any).15232. [`cast()`](https://python-all.ru/3.11/library/typing.html#typing.cast) может потребоваться в теле декоратора `add_logging` при возврате функции `inner`, или статической проверке типов нужно указать игнорировать `return inner`.15241525#### `args`15261527#### `kwargs`15281529Поскольку `ParamSpec` захватывает как позиционные, так и ключевые параметры, `P.args` и `P.kwargs` можно использовать для разделения `ParamSpec` на составляющие. `P.args` представляет кортеж позиционных параметров в заданном вызове и должен использоваться только для аннотации `*args`. `P.kwargs` представляет отображение ключевых параметров на их значения в заданном вызове и должен использоваться только для аннотации `**kwargs`. Оба атрибута требуют, чтобы аннотируемый параметр находился в области видимости. Во время выполнения `P.args` и `P.kwargs` являются экземплярами соответственно [`ParamSpecArgs`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpecArgs) и [`ParamSpecKwargs`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpecKwargs).15301531#### `__name__`15321533Имя спецификации параметров.15341535Переменные спецификации параметров, созданные с помощью `covariant=True` или `contravariant=True`, можно использовать для объявления ковариантных или контравариантных обобщённых типов. Аргумент `bound` также принимается, как и в [`TypeVar`](https://python-all.ru/3.11/library/typing.html#typing.TypeVar). Однако фактическая семантика этих ключевых слов ещё не определена.15361537Новое в версии 3.10.15381539> **Примечание**1540>1541> Только переменные спецификации параметров, определённые в глобальной области видимости, могут быть pickled.15421543> **См. также**1544>1545> - [**PEP 612**](https://python-all.ru/3.11/library/typing.html) – Переменные спецификации параметров (PEP, в котором были введены `ParamSpec` и `Concatenate`)1546> - [`Concatenate`](https://python-all.ru/3.11/library/typing.html#typing.Concatenate)1547> - [Аннотация вызываемых объектов](https://python-all.ru/3.11/library/typing.html#annotating-callables)15481549#### `typing.ParamSpecArgs`15501551#### `typing.ParamSpecKwargs`15521553Атрибуты аргументов и именованных аргументов (keyword arguments) объекта [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec). Атрибут `P.args` объекта `ParamSpec` является экземпляром `ParamSpecArgs`, а `P.kwargs` – экземпляром `ParamSpecKwargs`. Они предназначены для интроспекции во время выполнения и не имеют особого значения для статических проверяющих типы.15541555Вызов [`get_origin()`](https://python-all.ru/3.11/library/typing.html#typing.get_origin) для любого из этих объектов вернёт исходный `ParamSpec`:15561557```pycon1558>>> from typing import ParamSpec, get_origin1559>>> P = ParamSpec("P")1560>>> get_origin(P.args) is P1561True1562>>> get_origin(P.kwargs) is P1563True1564```15651566Новое в версии 3.10.15671568#### Другие специальные директивы15691570Эти функции и классы не следует использовать напрямую в качестве аннотаций. Их предназначение – быть строительными блоками для создания и объявления типов.15711572#### `class typing.NamedTuple`15731574Типизированная версия [`collections.namedtuple()`](https://python-all.ru/3.11/library/collections.html#collections.namedtuple).15751576Использование:15771578```python1579class Employee(NamedTuple):1580 name: str1581 id: int1582```15831584Это эквивалентно:15851586```python1587Employee = collections.namedtuple('Employee', ['name', 'id'])1588```15891590Чтобы задать полю значение по умолчанию, можно присвоить его в теле класса:15911592```python1593class Employee(NamedTuple):1594 name: str1595 id: int = 315961597employee = Employee('Guido')1598assert employee.id == 31599```16001601Поля со значением по умолчанию должны следовать после полей без значения по умолчанию.16021603Полученный класс имеет дополнительный атрибут `__annotations__`, который содержит словарь, отображающий имена полей на их типы. (Имена полей находятся в атрибуте `_fields`, а значения по умолчанию – в атрибуте `_field_defaults`; оба они являются частью API [`namedtuple()`](https://python-all.ru/3.11/library/collections.html#collections.namedtuple).)16041605Подклассы `NamedTuple` также могут иметь докстринги и методы:16061607```python1608class Employee(NamedTuple):1609 """Представляет сотрудника."""1610 name: str1611 id: int = 316121613 def __repr__(self) -> str:1614 return f'<Employee {self.name}, id={self.id}>'1615```16161617Подклассы `NamedTuple` могут быть обобщёнными (generic):16181619```python1620class Group(NamedTuple, Generic[T]):1621 key: T1622 group: list[T]1623```16241625Обратно совместимое использование:16261627```python1628Employee = NamedTuple('Employee', [('name', str), ('id', int)])1629```16301631Изменено в версии 3.6: Добавлена поддержка синтаксиса аннотации переменных [**PEP 526**](https://python-all.ru/3.11/library/typing.html).16321633Изменено в версии 3.6.1: Добавлена поддержка значений по умолчанию, методов и строк документации.16341635Изменено в версии 3.8: Атрибуты `_field_types` и `__annotations__` теперь являются обычными словарями, а не экземплярами `OrderedDict`.16361637Изменено в версии 3.9: Атрибут `_field_types` удалён в пользу более стандартного атрибута `__annotations__`, который содержит ту же информацию.16381639Изменено в версии 3.11: Добавлена поддержка обобщённых именованных кортежей (generic namedtuples).16401641#### `class typing.NewType(name, tp)`16421643Вспомогательный класс для создания [отдельных типов с низкими накладными расходами](https://python-all.ru/3.11/library/typing.html#distinct).16441645`NewType` считается отдельным типом для проверщика типов. Однако во время выполнения вызов `NewType` возвращает свой аргумент без изменений.16461647Использование:16481649```python1650UserId = NewType('UserId', int) # Объявить NewType "UserId"1651first_user = UserId(1) # "UserId" возвращает аргумент без изменений во время выполнения1652```16531654#### `__module__`16551656Модуль, в котором определён новый тип.16571658#### `__name__`16591660Имя нового типа.16611662#### `__supertype__`16631664Тип, на котором основан новый тип.16651666Новое в версии 3.5.2.16671668Изменено в версии 3.10: `NewType` теперь является классом, а не функцией.16691670#### `class typing.Protocol(Generic)`16711672Базовый класс для протокольных классов.16731674Протокольные классы определяются следующим образом:16751676```python1677class Proto(Protocol):1678 def meth(self) -> int:1679 ...1680```16811682Такие классы в основном используются со статическими проверяющими типов, которые распознают структурную подтипизацию (статическую утиную типизацию), например:16831684```python1685class C:1686 def meth(self) -> int:1687 return 016881689def func(x: Proto) -> int:1690 return x.meth()16911692func(C()) # Проходит статическую проверку типов1693```16941695См. [**PEP 544**](https://python-all.ru/3.11/library/typing.html) для получения дополнительных сведений. Классы-протоколы, декорированные [`runtime_checkable()`](https://python-all.ru/3.11/library/typing.html#typing.runtime_checkable) (описано далее), действуют как простые протоколы времени выполнения, которые проверяют только наличие заданных атрибутов, игнорируя их сигнатуры типов.16961697Протокольные классы могут быть обобщёнными, например:16981699```python1700T = TypeVar("T")17011702class GenProto(Protocol[T]):1703 def meth(self) -> T:1704 ...1705```17061707Новое в версии 3.8.17081709#### `@typing.runtime_checkable`17101711Помечает протокольный класс как протокол времени выполнения.17121713Такой протокол может использоваться с [`isinstance()`](https://python-all.ru/3.11/library/functions.html#isinstance) и [`issubclass()`](https://python-all.ru/3.11/library/functions.html#issubclass). При применении к классу, не являющемуся протоколом, возникает [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError). Это позволяет выполнять простую структурную проверку, очень похожую на “one trick ponies” в [`collections.abc`](https://python-all.ru/3.11/library/collections.abc.html#module-collections.abc), таких как [`Iterable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Iterable). Например:17141715```python1716@runtime_checkable1717class Closable(Protocol):1718 def close(self): ...17191720assert isinstance(open('/some/file'), Closable)17211722@runtime_checkable1723class Named(Protocol):1724 name: str17251726import threading1727assert isinstance(threading.Thread(name='Bob'), Named)1728```17291730> **Примечание**1731>1732> `runtime_checkable()` будет проверять только наличие требуемых методов или атрибутов, но не их сигнатуры типов или сами типы. Например, [`ssl.SSLObject`](https://python-all.ru/3.11/library/ssl.html#ssl.SSLObject) является классом, поэтому он проходит проверку [`issubclass()`](https://python-all.ru/3.11/library/functions.html#issubclass) на соответствие [Callable](https://python-all.ru/3.11/library/typing.html#annotating-callables). Однако метод `ssl.SSLObject.__init__` существует только для того, чтобы вызвать [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError) с более информативным сообщением, что делает невозможным вызов (создание экземпляра) [`ssl.SSLObject`](https://python-all.ru/3.11/library/ssl.html#ssl.SSLObject).17331734> **Примечание**1735>1736> Проверка [`isinstance()`](https://python-all.ru/3.11/library/functions.html#isinstance) на соответствие протоколу с проверкой во время выполнения может быть удивительно медленной по сравнению с проверкой `isinstance()` для непротокольного класса. Рекомендуется использовать альтернативные идиомы, такие как вызовы [`hasattr()`](https://python-all.ru/3.11/library/functions.html#hasattr) для структурных проверок в коде, чувствительном к производительности.17371738Новое в версии 3.8.17391740#### `class typing.TypedDict(dict)`17411742Специальная конструкция для добавления подсказок типов к словарю. Во время выполнения это обычный [`dict`](https://python-all.ru/3.11/library/stdtypes.html#dict).17431744`TypedDict` объявляет тип словаря, который ожидает, что все его экземпляры будут иметь определённый набор ключей, где каждый ключ связан со значением согласованного типа. Это ожидание не проверяется во время выполнения, а обеспечивается только средствами проверки типов. Использование:17451746```python1747class Point2D(TypedDict):1748 x: int1749 y: int1750 label: str17511752a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # ОК1753b: Point2D = {'z': 3, 'label': 'bad'} # Не проходит проверку типов17541755assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')1756```17571758Чтобы разрешить использование этой возможности в старых версиях Python, которые не поддерживают [**PEP 526**](https://python-all.ru/3.11/library/typing.html), `TypedDict` поддерживает две дополнительные эквивалентные синтаксические формы:17591760- Использование литерала [`dict`](https://python-all.ru/3.11/library/stdtypes.html#dict) в качестве второго аргумента:17611762 ```python1763 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})1764 ```1765- Использование именованных аргументов:17661767 ```python1768 Point2D = TypedDict('Point2D', x=int, y=int, label=str)1769 ```17701771Устарело с версии 3.11, будет удалено в версии 3.13: Синтаксис именованных аргументов устарел в 3.11 и будет удалён в 3.13. Он также может не поддерживаться статическими проверщиками типов.17721773Функциональный синтаксис также следует использовать, когда какой-либо из ключей не является допустимым [идентификатором](https://python-all.ru/3.11/reference/lexical_analysis.html#identifiers), например, потому что они являются ключевыми словами или содержат дефисы. Пример:17741775```python1776# возбуждает SyntaxError1777class Point2D(TypedDict):1778 in: int # 'in' – ключевое слово1779 x-y: int # имя с дефисами17801781# ОК, функциональный синтаксис1782Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})1783```17841785По умолчанию все ключи должны присутствовать в `TypedDict`. Можно пометить отдельные ключи как необязательные с помощью [`NotRequired`](https://python-all.ru/3.11/library/typing.html#typing.NotRequired):17861787```python1788class Point2D(TypedDict):1789 x: int1790 y: int1791 label: NotRequired[str]17921793# Альтернативный синтаксис1794Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': NotRequired[str]})1795```17961797Это означает, что `Point2D` `TypedDict` может не содержать ключ `label`.17981799Также можно по умолчанию пометить все ключи как необязательные, указав totality `False`:18001801```python1802class Point2D(TypedDict, total=False):1803 x: int1804 y: int18051806# Альтернативный синтаксис1807Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False)1808```18091810Это означает, что `Point2D` `TypedDict` может не содержать любой из ключей. Средство проверки типов должно поддерживать только литерал `False` или `True` в качестве значения аргумента `total`. `True` – значение по умолчанию, и оно делает все элементы, определённые в теле класса, обязательными.18111812Отдельные ключи `total=False` `TypedDict` можно пометить как обязательные с помощью [`Required`](https://python-all.ru/3.11/library/typing.html#typing.Required):18131814```python1815class Point2D(TypedDict, total=False):1816 x: Required[int]1817 y: Required[int]1818 label: str18191820# Альтернативный синтаксис1821Point2D = TypedDict('Point2D', {1822 'x': Required[int],1823 'y': Required[int],1824 'label': str1825}, total=False)1826```18271828`TypedDict` может наследоваться от одного или нескольких других типов `TypedDict` с использованием синтаксиса на основе классов. Использование:18291830```python1831class Point3D(Point2D):1832 z: int1833```18341835`Point3D` содержит три элемента: `x`, `y` и `z`. Это эквивалентно следующему определению:18361837```python1838class Point3D(TypedDict):1839 x: int1840 y: int1841 z: int1842```18431844`TypedDict` не может наследоваться от класса, не являющегося `TypedDict`, за исключением [`Generic`](https://python-all.ru/3.11/library/typing.html#typing.Generic). Например:18451846```python1847class X(TypedDict):1848 x: int18491850class Y(TypedDict):1851 y: int18521853class Z(object): pass # Класс, не являющийся TypedDict18541855class XY(X, Y): pass # ОК18561857class XZ(X, Z): pass # вызывает TypeError1858```18591860`TypedDict` может быть обобщённым:18611862```python1863T = TypeVar("T")18641865class Group(TypedDict, Generic[T]):1866 key: T1867 group: list[T]1868```18691870`TypedDict` может быть проанализирован с помощью словарей аннотаций (см. [Лучшие практики работы с аннотациями](https://python-all.ru/3.11/howto/annotations.html#annotations-howto) для получения дополнительной информации о лучших практиках работы с аннотациями), [`__total__`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict.__total__), [`__required_keys__`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict.__required_keys__) и [`__optional_keys__`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict.__optional_keys__).18711872#### `__total__`18731874`Point2D.__total__` возвращает значение аргумента `total`. Пример:18751876```pycon1877>>> from typing import TypedDict1878>>> class Point2D(TypedDict): pass1879>>> Point2D.__total__1880True1881>>> class Point2D(TypedDict, total=False): pass1882>>> Point2D.__total__1883False1884>>> class Point3D(Point2D): pass1885>>> Point3D.__total__1886True1887```18881889Этот атрибут отражает *только* значение аргумента `total` текущего класса `TypedDict`, а не то, является ли класс семантически полным. Например, `TypedDict` с `__total__`, установленным в True, может иметь ключи, помеченные с помощью [`NotRequired`](https://python-all.ru/3.11/library/typing.html#typing.NotRequired), или наследовать от другого `TypedDict` с `total=False`. Поэтому для интроспекции обычно лучше использовать [`__required_keys__`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict.__required_keys__) и [`__optional_keys__`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict.__optional_keys__).18901891#### `__required_keys__`18921893Новое в версии 3.9.18941895#### `__optional_keys__`18961897`Point2D.__required_keys__` и `Point2D.__optional_keys__` возвращают объекты [`frozenset`](https://python-all.ru/3.11/library/stdtypes.html#frozenset), содержащие обязательные и необязательные ключи соответственно.18981899Ключи, помеченные [`Required`](https://python-all.ru/3.11/library/typing.html#typing.Required), всегда будут появляться в `__required_keys__`, а ключи, помеченные [`NotRequired`](https://python-all.ru/3.11/library/typing.html#typing.NotRequired), всегда будут появляться в `__optional_keys__`.19001901Для обратной совместимости с Python 3.10 и ниже также можно использовать наследование для объявления как обязательных, так и необязательных ключей в одном `TypedDict`. Это делается путём объявления `TypedDict` с одним значением аргумента `total`, а затем наследования от него в другом `TypedDict` с другим значением для `total`:19021903```pycon1904>>> class Point2D(TypedDict, total=False):1905... x: int1906... y: int1907...1908>>> class Point3D(Point2D):1909... z: int1910...1911>>> Point3D.__required_keys__ == frozenset({'z'})1912True1913>>> Point3D.__optional_keys__ == frozenset({'x', 'y'})1914True1915```19161917Новое в версии 3.9.19181919> **Примечание**1920>1921> Если используется `from __future__ import annotations` или аннотации заданы в виде строк, аннотации не вычисляются при определении `TypedDict`. Поэтому анализ во время выполнения, на который полагаются `__required_keys__` и `__optional_keys__`, может работать неправильно, и значения атрибутов могут быть неверными.19221923Смотрите [**PEP 589**](https://python-all.ru/3.11/library/typing.html) для дополнительных примеров и подробных правил использования `TypedDict`.19241925Новое в версии 3.8.19261927Изменено в версии 3.11: Добавлена поддержка пометки отдельных ключей как [`Required`](https://python-all.ru/3.11/library/typing.html#typing.Required) или [`NotRequired`](https://python-all.ru/3.11/library/typing.html#typing.NotRequired). См. [**PEP 655**](https://python-all.ru/3.11/library/typing.html).19281929Изменено в версии 3.11: Добавлена поддержка обобщённых `TypedDict`.19301931### Протоколы19321933Следующие протоколы предоставляются модулем typing. Все они декорированы [`@runtime_checkable`](https://python-all.ru/3.11/library/typing.html#typing.runtime_checkable).19341935#### `class typing.SupportsAbs`19361937ABC с одним абстрактным методом `__abs__`, ковариантным по типу возвращаемого значения.19381939#### `class typing.SupportsBytes`19401941ABC с одним абстрактным методом `__bytes__`.19421943#### `class typing.SupportsComplex`19441945ABC с одним абстрактным методом `__complex__`.19461947#### `class typing.SupportsFloat`19481949ABC с одним абстрактным методом `__float__`.19501951#### `class typing.SupportsIndex`19521953ABC с одним абстрактным методом `__index__`.19541955Новое в версии 3.8.19561957#### `class typing.SupportsInt`19581959ABC с одним абстрактным методом `__int__`.19601961#### `class typing.SupportsRound`19621963ABC с одним абстрактным методом `__round__` ковариантным по возвращаемому типу.19641965### Абстрактные базовые классы для работы с IO19661967#### `class typing.IO`19681969#### `class typing.TextIO`19701971#### `class typing.BinaryIO`19721973Обобщённый тип `IO[AnyStr]` и его подклассы `TextIO(IO[str])` и `BinaryIO(IO[bytes])` представляют типы потоков ввода-вывода, такие как возвращаемые [`open()`](https://python-all.ru/3.11/library/functions.html#open).19741975### Функции и декораторы19761977#### `typing.cast(typ, val)`19781979Приводит значение к типу.19801981Это возвращает значение без изменений. Для проверщика типов это сигнализирует, что возвращаемое значение имеет указанный тип, но во время выполнения мы намеренно ничего не проверяем (мы хотим, чтобы это было как можно быстрее).19821983#### `typing.assert_type(val, typ, /)`19841985Запросить у статического проверщика типов подтверждение, что *val* имеет выведенный тип *typ*.19861987Во время выполнения эта функция ничего не делает: она возвращает первый аргумент без изменений, без проверок или побочных эффектов, независимо от фактического типа аргумента.19881989Когда статический проверщик типов встречает вызов `assert_type()`, он выдает ошибку, если значение не относится к указанному типу:19901991```python1992def greet(name: str) -> None:1993 assert_type(name, str) # ОК, выведенный тип `name` – `str`1994 assert_type(name, int) # ошибка проверки типов1995```19961997Эта функция полезна для проверки того, что понимание скрипта проверщиком типов соответствует намерениям разработчика:19981999```python2000def complex_function(arg: object):2001 # Выполнить сложную логику сужения типа,2002 # после чего ожидается, что выведенный тип станет `int`2003 ...2004 # Проверить, правильно ли проверщик типов понимает нашу функцию2005 assert_type(arg, int)2006```20072008Новое в версии 3.11.20092010#### `typing.assert_never(arg, /)`20112012Попросить статический проверщик типов подтвердить, что строка кода недостижима.20132014Пример:20152016```python2017def int_or_str(arg: int | str) -> None:2018 match arg:2019 case int():2020 print("It's an int")2021 case str():2022 print("It's a str")2023 case _ as unreachable:2024 assert_never(unreachable)2025```20262027Здесь аннотации позволяют проверщику типов вывести, что последний случай никогда не выполнится, поскольку `arg` является либо [`int`](https://python-all.ru/3.11/library/functions.html#int), либо [`str`](https://python-all.ru/3.11/library/stdtypes.html#str), и оба варианта уже покрыты предыдущими случаями.20282029Если проверщик типов обнаружит, что вызов `assert_never()` достижим, он выдаст ошибку. Например, если бы аннотация типа для `arg` вместо этого была `int | str | float`, проверщик типов выдал бы ошибку, указывающую, что `unreachable` имеет тип [`float`](https://python-all.ru/3.11/library/functions.html#float). Для того чтобы вызов `assert_never` прошел проверку типов, выведенный тип переданного аргумента должен быть нижним типом [`Never`](https://python-all.ru/3.11/library/typing.html#typing.Never) и ничем иным.20302031Во время выполнения эта функция выбрасывает исключение при вызове.20322033> **См. также**2034>2035> В разделе [Unreachable Code and Exhaustiveness Checking](https://python-all.ru/3.11/library/typing.html) содержится дополнительная информация о проверке полноты с помощью статической типизации.20362037Новое в версии 3.11.20382039#### `typing.reveal_type(obj, /)`20402041Попросить статический проверщик типов показать выведенный тип выражения.20422043Когда статический проверщик типов встречает вызов этой функции, он выдает диагностическое сообщение с выведенным типом аргумента. Например:20442045```python2046x: int = 12047reveal_type(x) # Раскрытый тип – "builtins.int"2048```20492050Это может быть полезно для отладки того, как проверщик типов обрабатывает конкретный фрагмент кода.20512052Во время выполнения эта функция выводит тип аргумента во время выполнения в [`sys.stderr`](https://python-all.ru/3.11/library/sys.html#sys.stderr) и возвращает аргумент без изменений (что позволяет использовать вызов внутри выражения):20532054```python2055x = reveal_type(1) # выводит «Runtime type is int»2056print(x) # выводит "1"2057```20582059Обратите внимание, что тип во время выполнения может отличаться от статически выведенного типа (быть более или менее конкретным).20602061Большинство проверщиков типов поддерживают `reveal_type()` в любом месте, даже если имя не импортировано из `typing`. Однако импорт имени из `typing` позволяет коду выполняться без ошибок времени выполнения и более четко выражает намерения.20622063Новое в версии 3.11.20642065#### `@typing.dataclass_transform(*, eq_default=True, order_default=False, kw_only_default=False, field_specifiers=(), **kwargs)`20662067Декоратор для пометки объекта как предоставляющего поведение, подобное [`dataclass`](https://python-all.ru/3.11/library/dataclasses.html#dataclasses.dataclass).20682069`dataclass_transform` может использоваться для декорирования класса, метакласса или функции, которая сама является декоратором. Наличие `@dataclass_transform()` сообщает статическому проверщику типов, что декорированный объект выполняет во время выполнения «магию», преобразующую класс аналогично [`@dataclasses.dataclass`](https://python-all.ru/3.11/library/dataclasses.html#dataclasses.dataclass).20702071Пример использования с функцией-декоратором:20722073```python2074T = TypeVar("T")20752076@dataclass_transform()2077def create_model(cls: type[T]) -> type[T]:2078 ...2079 return cls20802081@create_model2082class CustomerModel:2083 id: int2084 name: str2085```20862087На базовом классе:20882089```python2090@dataclass_transform()2091class ModelBase: ...20922093class CustomerModel(ModelBase):2094 id: int2095 name: str2096```20972098На метаклассе:20992100```python2101@dataclass_transform()2102class ModelMeta(type): ...21032104class ModelBase(metaclass=ModelMeta): ...21052106class CustomerModel(ModelBase):2107 id: int2108 name: str2109```21102111Классы `CustomerModel`, определенные выше, будут обрабатываться проверщиками типов аналогично классам, созданным с помощью [`@dataclasses.dataclass`](https://python-all.ru/3.11/library/dataclasses.html#dataclasses.dataclass). Например, проверщики типов будут предполагать, что эти классы имеют методы `__init__`, которые принимают `id` и `name`.21122113Декорированный класс, метакласс или функция могут принимать следующие булевы аргументы, которые, как будет считать проверщик типов, имеют тот же эффект, что и для декоратора [`@dataclasses.dataclass`](https://python-all.ru/3.11/library/dataclasses.html#dataclasses.dataclass): `init`, `eq`, `order`, `unsafe_hash`, `frozen`, `match_args`, `kw_only` и `slots`. Значения этих аргументов (`True` или `False`) должны быть статически вычислимыми.21142115Аргументы декоратора `dataclass_transform` могут использоваться для настройки поведения по умолчанию декорированного класса, метакласса или функции:21162117**Параметры:**21182119- **eq\_default** ([*bool*](https://python-all.ru/3.11/library/functions.html#bool)) – Указывает, предполагается ли параметр `eq` равным `True` или `False`, если он опущен вызывающей стороной. По умолчанию `True`.2120- **order\_default** ([*bool*](https://python-all.ru/3.11/library/functions.html#bool)) – Указывает, предполагается ли параметр `order` равным `True` или `False`, если он опущен вызывающей стороной. По умолчанию `False`.2121- **kw\_only\_default** ([*bool*](https://python-all.ru/3.11/library/functions.html#bool)) – Указывает, предполагается ли параметр `kw_only` равным `True` или `False`, если он опущен вызывающей стороной. По умолчанию `False`.2122- **field\_specifiers** ([*tuple*](https://python-all.ru/3.11/library/stdtypes.html#tuple)*\[*[*Callable*](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Callable)*\[**...**,* *Any**\]**,* *...**\]*) – Задаёт статический список поддерживаемых классов или функций, описывающих поля, аналогично [`dataclasses.field()`](https://python-all.ru/3.11/library/dataclasses.html#dataclasses.field). По умолчанию `()`.2123- **\*\*kwargs** (*Any*) – Допускаются произвольные другие именованные аргументы, чтобы обеспечить возможность будущих расширений.21242125Проверщики типов распознают следующие необязательные параметры в спецификаторах полей:21262127| Имя параметра | Описание |2128| --- | --- |2129| `init` | Указывает, должно ли поле быть включено в синтезируемый метод `__init__`. Если не указано, `init` по умолчанию равно `True`. |2130| `default` | Предоставляет значение по умолчанию для поля. |2131| `default_factory` | Предоставляет колбэк времени выполнения, возвращающий значение по умолчанию для поля. Если не указаны ни `default`, ни `default_factory`, считается, что поле не имеет значения по умолчанию, и при создании экземпляра класса для него должно быть предоставлено значение. |2132| `factory` | Псевдоним для параметра `default_factory` в спецификаторах полей. |2133| `kw_only` | Указывает, должно ли поле быть помечено как keyword-only. Если `True`, поле будет keyword-only. Если `False`, оно не будет keyword-only. Если не указано, будет использовано значение параметра `kw_only` объекта, декорированного с помощью `dataclass_transform`, или, если оно не указано, значение `kw_only_default` на `dataclass_transform`. |2134| `alias` | Предоставляет альтернативное имя для поля. Это альтернативное имя используется в синтезируемом методе `__init__`. |21352136Во время выполнения этот декоратор записывает свои аргументы в атрибут `__dataclass_transform__` декорированного объекта. Других эффектов во время выполнения нет.21372138Подробнее см. [**PEP 681**](https://python-all.ru/3.11/library/typing.html).21392140Новое в версии 3.11.21412142#### `@typing.overload`21432144Декоратор для создания перегруженных функций и методов.21452146Декоратор `@overload` позволяет описывать функции и методы, поддерживающие несколько различных комбинаций типов аргументов. За серией определений, декорированных `@overload`, должно следовать ровно одно определение, не декорированное `@overload` (для той же функции/метода).21472148Определения, декорированные `@overload`, предназначены только для проверщика типов, поскольку они будут перезаписаны определением, не декорированным `@overload`. Определение, не декорированное `@overload`, в свою очередь, будет использоваться во время выполнения, но должно игнорироваться проверщиком типов. Во время выполнения прямой вызов функции, декорированной `@overload`, вызовет [`NotImplementedError`](https://python-all.ru/3.11/library/exceptions.html#NotImplementedError).21492150Пример перегрузки, которая даёт более точный тип, чем можно выразить с помощью объединения или переменной типа:21512152```python2153@overload2154def process(response: None) -> None:2155 ...2156@overload2157def process(response: int) -> tuple[int, str]:2158 ...2159@overload2160def process(response: bytes) -> str:2161 ...2162def process(response):2163 ... # здесь находится фактическая реализация2164```21652166Подробнее и сравнение с другими семантиками типизации см. [**PEP 484**](https://python-all.ru/3.11/library/typing.html).21672168Изменено в версии 3.11: Перегруженные функции теперь можно интроспектировать во время выполнения с помощью [`get_overloads()`](https://python-all.ru/3.11/library/typing.html#typing.get_overloads).21692170#### `typing.get_overloads(func)`21712172Возвращает последовательность определений, декорированных [`@overload`](https://python-all.ru/3.11/library/typing.html#typing.overload), для *func*.21732174*func* – это объект функции для реализации перегруженной функции. Например, если дано определение `process` в документации для [`@overload`](https://python-all.ru/3.11/library/typing.html#typing.overload), `get_overloads(process)` вернёт последовательность из трёх объектов функций для трёх определённых перегрузок. Если вызвана для функции без перегрузок, `get_overloads()` возвращает пустую последовательность.21752176`get_overloads()` можно использовать для интроспекции перегруженной функции во время выполнения.21772178Новое в версии 3.11.21792180#### `typing.clear_overloads()`21812182Очищает все зарегистрированные перегрузки во внутреннем реестре.21832184Это можно использовать для освобождения памяти, занятой реестром.21852186Новое в версии 3.11.21872188#### `@typing.final`21892190Декоратор для указания окончательных методов и окончательных классов.21912192Декорирование метода с помощью `@final` указывает проверщику типов, что метод не может быть переопределён в подклассе. Декорирование класса с помощью `@final` указывает, что от него нельзя наследовать.21932194Например:21952196```python2197class Base:2198 @final2199 def done(self) -> None:2200 ...2201class Sub(Base):2202 def done(self) -> None: # Ошибка, выдаваемая проверщиком типов2203 ...22042205@final2206class Leaf:2207 ...2208class Other(Leaf): # Ошибка, выдаваемая проверщиком типов2209 ...2210```22112212Проверка этих свойств во время выполнения не выполняется. Подробнее см. [**PEP 591**](https://python-all.ru/3.11/library/typing.html).22132214Новое в версии 3.8.22152216Изменено в версии 3.11: Декоратор теперь будет пытаться установить атрибут `__final__` в значение `True` на декорированном объекте. Таким образом, проверку вида `if getattr(obj, "__final__", False)` можно использовать во время выполнения, чтобы определить, был ли объект `obj` помечен как окончательный (final). Если декорированный объект не поддерживает установку атрибутов, декоратор возвращает объект без изменений, не вызывая исключения.22172218#### `@typing.no_type_check`22192220Декоратор, указывающий, что аннотации не являются подсказками типов.22212222Это работает как [декоратор](https://python-all.ru/3.11/glossary.html#term-decorator) класса или функции. Для класса он применяется рекурсивно ко всем методам и классам, определённым в этом классе (но не к методам, определённым в его суперклассах или подклассах). Средства проверки типов будут игнорировать все аннотации в функции или классе с этим декоратором.22232224`@no_type_check` изменяет декорированный объект на месте.22252226#### `@typing.no_type_check_decorator`22272228Декоратор, придающий другому декоратору эффект [`no_type_check()`](https://python-all.ru/3.11/library/typing.html#typing.no_type_check).22292230Он оборачивает декоратор чем-то, что оборачивает декорированную функцию в [`no_type_check()`](https://python-all.ru/3.11/library/typing.html#typing.no_type_check).22312232#### `@typing.type_check_only`22332234Декоратор для пометки класса или функции как недоступных во время выполнения.22352236Сам этот декоратор недоступен во время выполнения. Он в основном предназначен для пометки классов, определённых в файлах заглушек типов (type stub), если реализация возвращает экземпляр закрытого класса:22372238```python2239@type_check_only2240class Response: # приватный или недоступный во время выполнения2241 code: int2242 def get_header(self, name: str) -> str: ...22432244def fetch_response() -> Response: ...2245```22462247Обратите внимание, что возврат экземпляров закрытых классов не рекомендуется. Обычно предпочтительнее делать такие классы открытыми.22482249### Вспомогательные функции для интроспекции22502251#### `typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False)`22522253Возвращает словарь, содержащий аннотации типов для функции, метода, модуля или объекта класса.22542255Это часто то же самое, что и `obj.__annotations__`. Кроме того, прямые ссылки, закодированные как строковые литералы, обрабатываются путём их вычисления в пространствах имён `globals` и `locals`. Для класса `C` возвращает словарь, построенный слиянием всех `__annotations__` вдоль `C.__mro__` в обратном порядке.22562257Функция рекурсивно заменяет все `Annotated[T, ...]` на `T`, если только `include_extras` не установлено в `True` (см. [`Annotated`](https://python-all.ru/3.11/library/typing.html#typing.Annotated) для получения дополнительной информации). Например:22582259```python2260class Student(NamedTuple):2261 name: Annotated[str, 'some marker']22622263assert get_type_hints(Student) == {'name': str}2264assert get_type_hints(Student, include_extras=False) == {'name': str}2265assert get_type_hints(Student, include_extras=True) == {2266 'name': Annotated[str, 'some marker']2267}2268```22692270> **Примечание**2271>2272> [`get_type_hints()`](https://python-all.ru/3.11/library/typing.html#typing.get_type_hints) не работает с импортированными [псевдонимами типов](https://python-all.ru/3.11/library/typing.html#type-aliases), которые содержат прямые ссылки. Включение отложенного вычисления аннотаций ([**PEP 563**](https://python-all.ru/3.11/library/typing.html)) может устранить необходимость в большинстве прямых ссылок.22732274Изменено в версии 3.9: Добавлен параметр `include_extras` в рамках [**PEP 593**](https://python-all.ru/3.11/library/typing.html). См. документацию по [`Annotated`](https://python-all.ru/3.11/library/typing.html#typing.Annotated) для получения дополнительных сведений.22752276Изменено в версии 3.11: Ранее `Optional[t]` добавлялась для аннотаций функций и методов, если было установлено значение по умолчанию, равное `None`. Теперь аннотация возвращается без изменений.22772278#### `typing.get_origin(tp)`22792280Возвращает неиндексированную версию типа: для объекта typing вида `X[Y, Z, ...]` возвращает `X`.22812282Если `X` – это псевдоним из модуля typing для встроенного класса или класса [`collections`](https://python-all.ru/3.11/library/collections.html#module-collections), он будет нормализован до исходного класса. Если `X` является экземпляром [`ParamSpecArgs`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpecArgs) или [`ParamSpecKwargs`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpecKwargs), возвращается базовый [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec). Для неподдерживаемых объектов возвращается `None`.22832284Примеры:22852286```python2287assert get_origin(str) is None2288assert get_origin(Dict[str, int]) is dict2289assert get_origin(Union[int, str]) is Union2290P = ParamSpec('P')2291assert get_origin(P.args) is P2292assert get_origin(P.kwargs) is P2293```22942295Новое в версии 3.8.22962297#### `typing.get_args(tp)`22982299Возвращает аргументы типа после выполнения всех подстановок: для объекта typing вида `X[Y, Z, ...]` возвращает `(Y, Z, ...)`.23002301Если `X` является объединением (union) или [`Literal`](https://python-all.ru/3.11/library/typing.html#typing.Literal) содержится в другом обобщённом типе, порядок `(Y, Z, ...)` может отличаться от порядка исходных аргументов `[Y, Z, ...]` из-за кеширования типов. Для неподдерживаемых объектов возвращается `()`.23022303Примеры:23042305```python2306assert get_args(int) == ()2307assert get_args(Dict[int, str]) == (int, str)2308assert get_args(Union[int, str]) == (int, str)2309```23102311Новое в версии 3.8.23122313#### `typing.is_typeddict(tp)`23142315Проверяет, является ли тип [`TypedDict`](https://python-all.ru/3.11/library/typing.html#typing.TypedDict).23162317Например:23182319```python2320class Film(TypedDict):2321 title: str2322 year: int23232324assert is_typeddict(Film)2325assert not is_typeddict(list | str)23262327# TypedDict – это фабрика для создания типизированных словарей,2328# а не сам типизированный словарь2329assert not is_typeddict(TypedDict)2330```23312332Новое в версии 3.10.23332334#### `class typing.ForwardRef`23352336Класс для внутреннего представления строковых прямых ссылок в typing.23372338Например, `List["SomeClass"]` неявно преобразуется в `List[ForwardRef("SomeClass")]`. `ForwardRef` не должен создаваться пользователем, но может использоваться инструментами интроспекции.23392340> **Примечание**2341>2342> обобщённые типы [**PEP 585**](https://python-all.ru/3.11/library/typing.html), такие как `list["SomeClass"]`, не будут неявно преобразовываться в `list[ForwardRef("SomeClass")]` и, следовательно, не будут автоматически разрешаться в `list[SomeClass]`.23432344Новое в версии 3.7.4.23452346### Константа23472348#### `typing.TYPE_CHECKING`23492350Специальная константа, которая, как считается, равна `True` для сторонних статических анализаторов типов. Во время выполнения её значение – `False`.23512352Использование:23532354```python2355if TYPE_CHECKING:2356 import expensive_mod23572358def fun(arg: 'expensive_mod.SomeType') -> None:2359 local_var: expensive_mod.AnotherType = other_fun()2360```23612362Первую аннотацию типа необходимо заключать в кавычки, превращая её в «прямую ссылку» (forward reference), чтобы скрыть ссылку `expensive_mod` от интерпретатора во время выполнения. Аннотации типов для локальных переменных не вычисляются, поэтому вторую аннотацию не нужно заключать в кавычки.23632364> **Примечание**2365>2366> Если используется `from __future__ import annotations`, аннотации не вычисляются во время определения функции. Вместо этого они сохраняются как строки в `__annotations__`. Это избавляет от необходимости заключать аннотацию в кавычки (см. [**PEP 563**](https://python-all.ru/3.11/library/typing.html)).23672368Новое в версии 3.5.2.23692370### Устаревшие псевдонимы23712372Этот модуль определяет несколько устаревших псевдонимов для уже существующих классов стандартной библиотеки. Изначально они были включены в модуль typing для поддержки параметризации этих обобщённых классов с помощью `[]`. Однако эти псевдонимы стали избыточными в Python 3.9, когда соответствующие существующие классы были расширены для поддержки `[]` (см. [**PEP 585**](https://python-all.ru/3.11/library/typing.html)).23732374Избыточные типы считаются устаревшими начиная с Python 3.9. Однако, хотя псевдонимы могут быть удалены в какой-то момент, их удаление в настоящее время не планируется. Поэтому в настоящее время интерпретатор не выдаёт предупреждений об устаревании для этих псевдонимов.23752376Если в какой-то момент будет принято решение удалить эти устаревшие псевдонимы, интерпретатор будет выдавать предупреждение об устаревании как минимум за два релиза до удаления. Псевдонимы гарантированно останутся в модуле typing без предупреждений об устаревании как минимум до Python 3.14.23772378Проверяющим типы рекомендуется отмечать использование устаревших типов, если проверяемая программа нацелена на минимальную версию Python 3.9 или новее.23792380#### Псевдонимы встроенных типов23812382#### `class typing.Dict(dict, MutableMapping[KT, VT])`23832384Устаревший псевдоним [`dict`](https://python-all.ru/3.11/library/stdtypes.html#dict).23852386Обратите внимание, что для аннотации аргументов предпочтительнее использовать абстрактный тип коллекции, такой как [`Mapping`](https://python-all.ru/3.11/library/typing.html#typing.Mapping), а не [`dict`](https://python-all.ru/3.11/library/stdtypes.html#dict) или `typing.Dict`.23872388Этот тип можно использовать следующим образом:23892390```python2391def count_words(text: str) -> Dict[str, int]:2392 ...2393```23942395Deprecated since version 3.9: [`builtins.dict`](https://python-all.ru/3.11/library/stdtypes.html#dict) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).23962397#### `class typing.List(list, MutableSequence[T])`23982399Устаревший псевдоним [`list`](https://python-all.ru/3.11/library/stdtypes.html#list).24002401Обратите внимание, что для аннотации аргументов предпочтительнее использовать абстрактный тип коллекции, такой как [`Sequence`](https://python-all.ru/3.11/library/typing.html#typing.Sequence) или [`Iterable`](https://python-all.ru/3.11/library/typing.html#typing.Iterable), а не [`list`](https://python-all.ru/3.11/library/stdtypes.html#list) или `typing.List`.24022403Этот тип можно использовать следующим образом:24042405```python2406T = TypeVar('T', int, float)24072408def vec2(x: T, y: T) -> List[T]:2409 return [x, y]24102411def keep_positives(vector: Sequence[T]) -> List[T]:2412 return [item for item in vector if item > 0]2413```24142415Deprecated since version 3.9: [`builtins.list`](https://python-all.ru/3.11/library/stdtypes.html#list) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).24162417#### `class typing.Set(set, MutableSet[T])`24182419Устаревший псевдоним [`builtins.set`](https://python-all.ru/3.11/library/stdtypes.html#set).24202421Обратите внимание, что для аннотации аргументов предпочтительнее использовать абстрактный тип коллекции, такой как [`AbstractSet`](https://python-all.ru/3.11/library/typing.html#typing.AbstractSet), а не [`set`](https://python-all.ru/3.11/library/stdtypes.html#set) или `typing.Set`.24222423Deprecated since version 3.9: [`builtins.set`](https://python-all.ru/3.11/library/stdtypes.html#set) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).24242425#### `class typing.FrozenSet(frozenset, AbstractSet[T_co])`24262427Устаревший псевдоним [`builtins.frozenset`](https://python-all.ru/3.11/library/stdtypes.html#frozenset).24282429Deprecated since version 3.9: [`builtins.frozenset`](https://python-all.ru/3.11/library/stdtypes.html#frozenset) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).24302431#### `typing.Tuple`24322433Устаревший псевдоним для [`tuple`](https://python-all.ru/3.11/library/stdtypes.html#tuple).24342435[`tuple`](https://python-all.ru/3.11/library/stdtypes.html#tuple) и `Tuple` являются особыми случаями в системе типов; см. [Аннотирование кортежей](https://python-all.ru/3.11/library/typing.html#annotating-tuples) для получения дополнительной информации.24362437Deprecated since version 3.9: [`builtins.tuple`](https://python-all.ru/3.11/library/stdtypes.html#tuple) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).24382439#### `class typing.Type(Generic[CT_co])`24402441Устаревший псевдоним [`type`](https://python-all.ru/3.11/library/functions.html#type).24422443См. [Тип объектов класса](https://python-all.ru/3.11/library/typing.html#type-of-class-objects) для подробностей об использовании [`type`](https://python-all.ru/3.11/library/functions.html#type) или `typing.Type` в аннотациях типов.24442445Новое в версии 3.5.2.24462447Deprecated since version 3.9: [`builtins.type`](https://python-all.ru/3.11/library/functions.html#type) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).24482449#### Псевдонимы типов в [`collections`](https://python-all.ru/3.11/library/collections.html#module-collections)24502451#### `class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])`24522453Устаревший псевдоним [`collections.defaultdict`](https://python-all.ru/3.11/library/collections.html#collections.defaultdict).24542455Новое в версии 3.5.2.24562457Deprecated since version 3.9: [`collections.defaultdict`](https://python-all.ru/3.11/library/collections.html#collections.defaultdict) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).24582459#### `class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])`24602461Устаревший псевдоним [`collections.OrderedDict`](https://python-all.ru/3.11/library/collections.html#collections.OrderedDict).24622463Добавлено в версии 3.7.2.24642465Deprecated since version 3.9: [`collections.OrderedDict`](https://python-all.ru/3.11/library/collections.html#collections.OrderedDict) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).24662467#### `class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])`24682469Устаревший псевдоним [`collections.ChainMap`](https://python-all.ru/3.11/library/collections.html#collections.ChainMap).24702471Новое в версии 3.6.1.24722473Deprecated since version 3.9: [`collections.ChainMap`](https://python-all.ru/3.11/library/collections.html#collections.ChainMap) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).24742475#### `class typing.Counter(collections.Counter, Dict[T, int])`24762477Устаревший псевдоним [`collections.Counter`](https://python-all.ru/3.11/library/collections.html#collections.Counter).24782479Новое в версии 3.6.1.24802481Deprecated since version 3.9: [`collections.Counter`](https://python-all.ru/3.11/library/collections.html#collections.Counter) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).24822483#### `class typing.Deque(deque, MutableSequence[T])`24842485Устаревший псевдоним [`collections.deque`](https://python-all.ru/3.11/library/collections.html#collections.deque).24862487Новое в версии 3.6.1.24882489Deprecated since version 3.9: [`collections.deque`](https://python-all.ru/3.11/library/collections.html#collections.deque) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).24902491#### Псевдонимы для других конкретных типов24922493#### `class typing.Pattern`24942495#### `class typing.Match`24962497Устаревшие псевдонимы, соответствующие типам возвращаемых значений из [`re.compile()`](https://python-all.ru/3.11/library/re.html#re.compile) и [`re.match()`](https://python-all.ru/3.11/library/re.html#re.match).24982499Эти типы (и соответствующие функции) являются обобщёнными относительно [`AnyStr`](https://python-all.ru/3.11/library/typing.html#typing.AnyStr). `Pattern` может быть специализирован как `Pattern[str]` или `Pattern[bytes]`; `Match` может быть специализирован как `Match[str]` или `Match[bytes]`.25002501Устарело с версии 3.8, будет удалено в версии 3.13: Пространство имён `typing.re` устарело и будет удалено. Эти типы следует импортировать напрямую из `typing`.25022503Устарело с версии 3.9: Классы `Pattern` и `Match` из [`re`](https://python-all.ru/3.11/library/re.html#module-re) теперь поддерживают `[]`. См. [**PEP 585**](https://python-all.ru/3.11/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25042505#### `class typing.Text`25062507Устаревший псевдоним для [`str`](https://python-all.ru/3.11/library/stdtypes.html#str).25082509`Text` предоставляется для обеспечения совместимости с кодом Python 2: в Python 2 `Text` является псевдонимом для `unicode`.25102511Используйте `Text`, чтобы указать, что значение должно содержать строку Unicode, совместимую как с Python 2, так и с Python 3:25122513```python2514def add_unicode_checkmark(text: Text) -> Text:2515 return text + u' \u2713'2516```25172518Новое в версии 3.5.2.25192520Устарело с версии 3.11: Python 2 больше не поддерживается, и большинство проверщиков типов также больше не поддерживают проверку типов для кода Python 2. Удаление псевдонима в настоящее время не планируется, но пользователям рекомендуется использовать [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) вместо `Text`.25212522#### Псевдонимы для контейнерных ABC в [`collections.abc`](https://python-all.ru/3.11/library/collections.abc.html#module-collections.abc)25232524#### `class typing.AbstractSet(Collection[T_co])`25252526Устаревший псевдоним [`collections.abc.Set`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Set).25272528Deprecated since version 3.9: [`collections.abc.Set`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Set) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25292530#### `class typing.ByteString(Sequence[int])`25312532Этот тип представляет типы [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.11/library/stdtypes.html#bytearray) и [`memoryview`](https://python-all.ru/3.11/library/stdtypes.html#memoryview) последовательностей байтов.25332534Устарело с версии 3.9, будет удалено в версии 3.14: Предпочтительнее использовать `typing_extensions.Buffer` или объединение наподобие `bytes | bytearray | memoryview`.25352536#### `class typing.Collection(Sized, Iterable[T_co], Container[T_co])`25372538Устаревший псевдоним [`collections.abc.Collection`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Collection).25392540Новое в версии 3.6.25412542Deprecated since version 3.9: [`collections.abc.Collection`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Collection) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25432544#### `class typing.Container(Generic[T_co])`25452546Устаревший псевдоним [`collections.abc.Container`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Container).25472548Deprecated since version 3.9: [`collections.abc.Container`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Container) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25492550#### `class typing.ItemsView(MappingView, AbstractSet[tuple[KT_co, VT_co]])`25512552Устаревший псевдоним [`collections.abc.ItemsView`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.ItemsView).25532554Deprecated since version 3.9: [`collections.abc.ItemsView`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.ItemsView) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25552556#### `class typing.KeysView(MappingView, AbstractSet[KT_co])`25572558Устаревший псевдоним [`collections.abc.KeysView`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.KeysView).25592560Deprecated since version 3.9: [`collections.abc.KeysView`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.KeysView) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25612562#### `class typing.Mapping(Collection[KT], Generic[KT, VT_co])`25632564Устаревший псевдоним [`collections.abc.Mapping`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Mapping).25652566Этот тип можно использовать следующим образом:25672568```python2569def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:2570 return word_list[word]2571```25722573Deprecated since version 3.9: [`collections.abc.Mapping`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Mapping) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25742575#### `class typing.MappingView(Sized)`25762577Устаревший псевдоним [`collections.abc.MappingView`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.MappingView).25782579Deprecated since version 3.9: [`collections.abc.MappingView`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.MappingView) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25802581#### `class typing.MutableMapping(Mapping[KT, VT])`25822583Устаревший псевдоним [`collections.abc.MutableMapping`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.MutableMapping).25842585Deprecated since version 3.9: [`collections.abc.MutableMapping`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.MutableMapping) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25862587#### `class typing.MutableSequence(Sequence[T])`25882589Устаревший псевдоним [`collections.abc.MutableSequence`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.MutableSequence).25902591Deprecated since version 3.9: [`collections.abc.MutableSequence`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.MutableSequence) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25922593#### `class typing.MutableSet(AbstractSet[T])`25942595Устаревший псевдоним [`collections.abc.MutableSet`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.MutableSet).25962597Deprecated since version 3.9: [`collections.abc.MutableSet`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.MutableSet) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).25982599#### `class typing.Sequence(Reversible[T_co], Collection[T_co])`26002601Устаревший псевдоним [`collections.abc.Sequence`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Sequence).26022603Deprecated since version 3.9: [`collections.abc.Sequence`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Sequence) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).26042605#### `class typing.ValuesView(MappingView, Collection[_VT_co])`26062607Устаревший псевдоним [`collections.abc.ValuesView`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.ValuesView).26082609Deprecated since version 3.9: [`collections.abc.ValuesView`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.ValuesView) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).26102611#### Псевдонимы для асинхронных ABC в [`collections.abc`](https://python-all.ru/3.11/library/collections.abc.html#module-collections.abc)26122613#### `class typing.Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])`26142615Устаревший псевдоним [`collections.abc.Coroutine`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Coroutine).26162617Вариативность и порядок переменных типа соответствуют тому же, что и в [`Generator`](https://python-all.ru/3.11/library/typing.html#typing.Generator), например:26182619```python2620from collections.abc import Coroutine2621c: Coroutine[list[str], str, int] # Некоторая корутина, определённая в другом месте.2622x = c.send('hi') # Выведенный тип 'x' – list[str].2623async def bar() -> None:2624 y = await c # Выведенный тип 'y' – int.2625```26262627Новое в версии 3.5.3.26282629Deprecated since version 3.9: [`collections.abc.Coroutine`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Coroutine) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).26302631#### `class typing.AsyncGenerator(AsyncIterator[YieldType], Generic[YieldType, SendType])`26322633Устаревший псевдоним [`collections.abc.AsyncGenerator`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.AsyncGenerator).26342635Асинхронный генератор можно аннотировать обобщённым типом `AsyncGenerator[YieldType, SendType]`. Например:26362637```python2638async def echo_round() -> AsyncGenerator[int, float]:2639 sent = yield 02640 while sent >= 0.0:2641 rounded = await round(sent)2642 sent = yield rounded2643```26442645В отличие от обычных генераторов, асинхронные генераторы не могут возвращать значение, поэтому параметр типа `ReturnType` отсутствует. Как и в случае с [`Generator`](https://python-all.ru/3.11/library/typing.html#typing.Generator), `SendType` ведёт себя контравариантно.26462647Если генератор только выдаёт значения, установите `SendType` в `None`:26482649```python2650async def infinite_stream(start: int) -> AsyncGenerator[int, None]:2651 while True:2652 yield start2653 start = await increment(start)2654```26552656В качестве альтернативы аннотируйте генератор как имеющий тип возвращаемого значения либо `AsyncIterable[YieldType]`, либо `AsyncIterator[YieldType]`:26572658```python2659async def infinite_stream(start: int) -> AsyncIterator[int]:2660 while True:2661 yield start2662 start = await increment(start)2663```26642665Новое в версии 3.6.1.26662667Deprecated since version 3.9: [`collections.abc.AsyncGenerator`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.AsyncGenerator) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).26682669#### `class typing.AsyncIterable(Generic[T_co])`26702671Устаревший псевдоним [`collections.abc.AsyncIterable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.AsyncIterable).26722673Новое в версии 3.5.2.26742675Deprecated since version 3.9: [`collections.abc.AsyncIterable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.AsyncIterable) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).26762677#### `class typing.AsyncIterator(AsyncIterable[T_co])`26782679Устаревший псевдоним [`collections.abc.AsyncIterator`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.AsyncIterator).26802681Новое в версии 3.5.2.26822683Deprecated since version 3.9: [`collections.abc.AsyncIterator`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.AsyncIterator) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).26842685#### `class typing.Awaitable(Generic[T_co])`26862687Устаревший псевдоним [`collections.abc.Awaitable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Awaitable).26882689Новое в версии 3.5.2.26902691Deprecated since version 3.9: [`collections.abc.Awaitable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Awaitable) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).26922693#### Псевдонимы для других ABC в [`collections.abc`](https://python-all.ru/3.11/library/collections.abc.html#module-collections.abc)26942695#### `class typing.Iterable(Generic[T_co])`26962697Устаревший псевдоним [`collections.abc.Iterable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Iterable).26982699Deprecated since version 3.9: [`collections.abc.Iterable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Iterable) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).27002701#### `class typing.Iterator(Iterable[T_co])`27022703Устаревший псевдоним [`collections.abc.Iterator`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Iterator).27042705Deprecated since version 3.9: [`collections.abc.Iterator`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Iterator) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).27062707#### `typing.Callable`27082709Устаревший псевдоним [`collections.abc.Callable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Callable).27102711See [Annotating callable objects](https://python-all.ru/3.11/library/typing.html#annotating-callables) for details on how to use [`collections.abc.Callable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Callable) and `typing.Callable` in type annotations.27122713Deprecated since version 3.9: [`collections.abc.Callable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Callable) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).27142715Changed in version 3.10: `Callable` now supports [`ParamSpec`](https://python-all.ru/3.11/library/typing.html#typing.ParamSpec) and [`Concatenate`](https://python-all.ru/3.11/library/typing.html#typing.Concatenate). See [**PEP 612**](https://python-all.ru/3.11/library/typing.html) for more details.27162717#### `class typing.Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])`27182719Устаревший псевдоним [`collections.abc.Generator`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Generator).27202721Генератор можно аннотировать обобщённым типом `Generator[YieldType, SendType, ReturnType]`. Например:27222723```python2724def echo_round() -> Generator[int, float, str]:2725 sent = yield 02726 while sent >= 0:2727 sent = yield round(sent)2728 return 'Done'2729```27302731Обратите внимание: в отличие от многих других обобщённых типов в модуле typing, `SendType` из [`Generator`](https://python-all.ru/3.11/library/typing.html#typing.Generator) ведёт себя контравариантно, а не ковариантно или инвариантно.27322733Если ваш генератор будет только выдавать значения, установите `SendType` и `ReturnType` в `None`:27342735```python2736def infinite_stream(start: int) -> Generator[int, None, None]:2737 while True:2738 yield start2739 start += 12740```27412742В качестве альтернативы аннотируйте генератор как имеющий тип возвращаемого значения либо `Iterable[YieldType]`, либо `Iterator[YieldType]`:27432744```python2745def infinite_stream(start: int) -> Iterator[int]:2746 while True:2747 yield start2748 start += 12749```27502751Deprecated since version 3.9: [`collections.abc.Generator`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Generator) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).27522753#### `class typing.Hashable`27542755Псевдоним для [`collections.abc.Hashable`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Hashable).27562757#### `class typing.Reversible(Iterable[T_co])`27582759Устаревший псевдоним [`collections.abc.Reversible`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Reversible).27602761Deprecated since version 3.9: [`collections.abc.Reversible`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Reversible) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).27622763#### `class typing.Sized`27642765Псевдоним для [`collections.abc.Sized`](https://python-all.ru/3.11/library/collections.abc.html#collections.abc.Sized).27662767#### Псевдонимы для [`contextlib`](https://python-all.ru/3.11/library/contextlib.html#module-contextlib) ABCs27682769#### `class typing.ContextManager(Generic[T_co])`27702771Устаревший псевдоним [`contextlib.AbstractContextManager`](https://python-all.ru/3.11/library/contextlib.html#contextlib.AbstractContextManager).27722773Новое в версии 3.5.4.27742775Deprecated since version 3.9: [`contextlib.AbstractContextManager`](https://python-all.ru/3.11/library/contextlib.html#contextlib.AbstractContextManager) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).27762777#### `class typing.AsyncContextManager(Generic[T_co])`27782779Устаревший псевдоним [`contextlib.AbstractAsyncContextManager`](https://python-all.ru/3.11/library/contextlib.html#contextlib.AbstractAsyncContextManager).27802781Новое в версии 3.6.2.27822783Deprecated since version 3.9: [`contextlib.AbstractAsyncContextManager`](https://python-all.ru/3.11/library/contextlib.html#contextlib.AbstractAsyncContextManager) now supports subscripting (`[]`). See [**PEP 585**](https://python-all.ru/3.11/library/typing.html) and [Generic Alias Type](https://python-all.ru/3.11/library/stdtypes.html#types-genericalias).27842785## Хронология устаревания основных возможностей27862787Некоторые возможности в `typing` устарели и могут быть удалены в будущей версии Python. Для удобства ниже приведена таблица с основными устаревшими элементами. Она может изменяться, и в ней перечислены не все устаревшие возможности.27882789| Возможность | Устарело в | Планируемое удаление | PEP/issue |2790| --- | --- | --- | --- |2791| `typing.io` и `typing.re` подмодули | 3.8 | 3.13 | [bpo-38291](https://python-all.ru/3.11/library/typing.html) |2792| `typing` версии стандартных коллекций | 3.9 | Не определено (см. [устаревшие псевдонимы](https://python-all.ru/3.11/library/typing.html#deprecated-typing-aliases) для дополнительной информации) | [**PEP 585**](https://python-all.ru/3.11/library/typing.html) |2793| [`typing.ByteString`](https://python-all.ru/3.11/library/typing.html#typing.ByteString) | 3.9 | 3.14 | [gh-91896](https://python-all.ru/3.11/library/typing.html) |2794| [`typing.Text`](https://python-all.ru/3.11/library/typing.html#typing.Text) | 3.11 | Не определено | [gh-92332](https://python-all.ru/3.11/library/typing.html) |2795