> **Источник:** https://python-all.ru/3.9/library/typing.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # [`typing`](https://python-all.ru/3.9/library/typing.html#module-typing) – Поддержка аннотаций типов Новое в версии 3.5. **Исходный код:** [Lib/typing.py](https://python-all.ru/src/3.9/Lib/typing.py) > **Примечание** > > Среда выполнения Python не проверяет аннотации типов функций и переменных. Они могут использоваться сторонними инструментами, такими как средства проверки типов, IDE, линтеры и т. д. --- Данный модуль предоставляет поддержку аннотаций типов на уровне выполнения. Самая базовая поддержка включает типы [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), [`Union`](https://python-all.ru/3.9/library/typing.html#typing.Union), [`Callable`](https://python-all.ru/3.9/library/typing.html#typing.Callable), [`TypeVar`](https://python-all.ru/3.9/library/typing.html#typing.TypeVar) и [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic). Полную спецификацию см. в [**PEP 484**](https://python-all.ru/3.9/library/typing.html). Для упрощённого введения в аннотации типов см. [**PEP 483**](https://python-all.ru/3.9/library/typing.html). Функция ниже принимает и возвращает строку и аннотирована следующим образом: ```python def greeting(name: str) -> str: return 'Hello ' + name ``` В функции `greeting` аргумент `name` ожидается типа [`str`](https://python-all.ru/3.9/library/stdtypes.html#str), а возвращаемый тип – [`str`](https://python-all.ru/3.9/library/stdtypes.html#str). Подтипы допускаются в качестве аргументов. Новые функции часто добавляются в модуль `typing`. Пакет [typing\_extensions](https://python-all.ru/3.9/library/typing.html) предоставляет бэкпорты этих новых функций для старых версий Python. ## Соответствующие PEP С момента первого появления аннотаций типов в [**PEP 484**](https://python-all.ru/3.9/library/typing.html) и [**PEP 483**](https://python-all.ru/3.9/library/typing.html) ряд PEP изменил и расширил инфраструктуру Python для аннотаций типов. К ним относятся: - **[**PEP 526**](https://python-all.ru/3.9/library/typing.html): Синтаксис аннотаций переменных** *Вводит* синтаксис аннотирования переменных вне определений функций, а также [`ClassVar`](https://python-all.ru/3.9/library/typing.html#typing.ClassVar) - **[**PEP 544**](https://python-all.ru/3.9/library/typing.html): Протоколы: структурная типизация (статическая утиная типизация)** *Вводит* [`Protocol`](https://python-all.ru/3.9/library/typing.html#typing.Protocol) и декоратор [`@runtime_checkable`](https://python-all.ru/3.9/library/typing.html#typing.runtime_checkable) - **[**PEP 585**](https://python-all.ru/3.9/library/typing.html): Обобщённые типы в стандартных коллекциях** *Вводит* [`types.GenericAlias`](https://python-all.ru/3.9/library/types.html#types.GenericAlias) и возможность использовать классы стандартной библиотеки как [обобщённые типы](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias) - **[**PEP 586**](https://python-all.ru/3.9/library/typing.html): Литеральные типы** *Представлен* [`Literal`](https://python-all.ru/3.9/library/typing.html#typing.Literal) - **[**PEP 589**](https://python-all.ru/3.9/library/typing.html): TypedDict: аннотации типов для словарей с фиксированным набором ключей** *Представлен* [`TypedDict`](https://python-all.ru/3.9/library/typing.html#typing.TypedDict) - **[**PEP 591**](https://python-all.ru/3.9/library/typing.html): Добавление квалификатора final в typing** *Вводит* [`Final`](https://python-all.ru/3.9/library/typing.html#typing.Final) и декоратор [`@final`](https://python-all.ru/3.9/library/typing.html#typing.final) - **[**PEP 593**](https://python-all.ru/3.9/library/typing.html): Гибкие аннотации функций и переменных** *Представлен* [`Annotated`](https://python-all.ru/3.9/library/typing.html#typing.Annotated) ## Псевдонимы типов Псевдоним типа определяется присваиванием типа псевдониму. В этом примере `Vector` и `list[float]` будут рассматриваться как взаимозаменяемые синонимы: ```python Vector = list[float] def scale(scalar: float, vector: Vector) -> Vector: return [scalar * num for num in vector] # Проходит проверку типов; список чисел с плавающей запятой считается Vector. new_vector = scale(2.0, [1.0, -4.2, 5.4]) ``` Псевдонимы типов полезны для упрощения сложных сигнатур типов. Например: ```python from collections.abc import Sequence ConnectionOptions = dict[str, str] Address = tuple[str, int] Server = tuple[Address, ConnectionOptions] def broadcast_message(message: str, servers: Sequence[Server]) -> None: ... # Статическая проверка типов будет считать предыдущую сигнатуру типа как # полностью эквивалентную этой. def broadcast_message( message: str, servers: Sequence[tuple[tuple[str, int], dict[str, str]]]) -> None: ... ``` Обратите внимание, что `None` как аннотация типа является особым случаем и заменяется на `type(None)`. ## NewType Используйте вспомогательную функцию [`NewType()`](https://python-all.ru/3.9/library/typing.html#typing.NewType) для создания отдельных типов: ```python from typing import NewType UserId = NewType('UserId', int) some_id = UserId(524313) ``` Статический проверщик типов будет рассматривать новый тип как подкласс исходного типа. Это полезно для выявления логических ошибок: ```python def get_user_name(user_id: UserId) -> str: ... # Проходит проверку типов. user_a = get_user_name(UserId(42351)) # Не проходит проверку типов; int не является UserId. user_b = get_user_name(-1) ``` Можно по-прежнему выполнять все операции `int` над переменной типа `UserId`, но результат всегда будет типа `int`. Это позволяет передавать `UserId` везде, где может ожидаться `int`, но предотвращает случайное создание `UserId` недопустимым способом: ```python # 'output' имеет тип 'int', а не 'UserId' output = UserId(23413) + UserId(54341) ``` Обратите внимание, что эти проверки выполняются только статическим проверяющим типы. Во время выполнения выражение `Derived = NewType('Derived', Base)` делает `Derived` вызываемым объектом, который немедленно возвращает любой переданный ему параметр. Это означает, что выражение `Derived(some_value)` не создаёт новый класс и не вносит никаких накладных расходов сверх обычного вызова функции. Точнее, выражение `some_value is Derived(some_value)` во время выполнения всегда истинно. Это также означает, что невозможно создать подтип `Derived`, поскольку во время выполнения это тождественная функция, а не реальный тип: ```python from typing import NewType UserId = NewType('UserId', int) # Завершается ошибкой во время выполнения и не проходит проверку типов. class AdminUserId(UserId): pass ``` Однако можно создать [`NewType()`](https://python-all.ru/3.9/library/typing.html#typing.NewType) на основе «производного» `NewType`: ```python from typing import NewType UserId = NewType('UserId', int) ProUserId = NewType('ProUserId', UserId) ``` и проверка типов для `ProUserId` будет работать как ожидается. Подробнее см. [**PEP 484**](https://python-all.ru/3.9/library/typing.html). > **Примечание** > > Напомним, что использование псевдонима типа объявляет два типа *эквивалентными* друг другу. Использование `Alias = Original` заставит статический анализатор типов считать `Alias` *точно эквивалентным* `Original` во всех случаях. Это полезно, когда требуется упростить сложные сигнатуры типов. > > В отличие от этого, `NewType` объявляет один тип *подтипом* другого. Использование `Derived = NewType('Derived', Original)` заставит статический анализатор типов считать `Derived` *подклассом* `Original`, что означает, что значение типа `Original` не может использоваться там, где ожидается значение типа `Derived`. Это полезно для предотвращения логических ошибок с минимальными затратами времени выполнения. Новое в версии 3.5.2. ## Callable Фреймворки, ожидающие функции обратного вызова с определённой сигнатурой, могут быть аннотированы с помощью `Callable[[Arg1Type, Arg2Type], ReturnType]`. Например: ```python from collections.abc import Callable def feeder(get_next_item: Callable[[], str]) -> None: # Тело def async_query(on_success: Callable[[int], None], on_error: Callable[[int, Exception], None]) -> None: # Тело async def on_update(value: str) -> None: # Тело callback: Callable[[str], Awaitable[None]] = on_update ``` Можно объявить возвращаемый тип вызываемого объекта, не указывая сигнатуру вызова, заменив список аргументов многоточием в аннотации типа: `Callable[..., ReturnType]`. ## Обобщённые типы Поскольку информацию о типах объектов, хранящихся в контейнерах, нельзя статически вывести обобщённым способом, абстрактные базовые классы были расширены для поддержки параметризации типами, чтобы обозначить ожидаемые типы элементов контейнера. ```python from collections.abc import Mapping, Sequence def notify_by_email(employees: Sequence[Employee], overrides: Mapping[str, str]) -> None: ... ``` Обобщённые типы можно параметризовать с помощью фабрики, доступной в typing под названием [`TypeVar`](https://python-all.ru/3.9/library/typing.html#typing.TypeVar). ```python from collections.abc import Sequence from typing import TypeVar T = TypeVar('T') # Объявить переменную типа def first(l: Sequence[T]) -> T: # Обобщённая функция return l[0] ``` ## Пользовательские обобщённые типы Пользовательский класс можно определить как обобщённый класс. ```python from typing import TypeVar, Generic from logging import Logger T = TypeVar('T') class LoggedVar(Generic[T]): def __init__(self, value: T, name: str, logger: Logger) -> None: self.name = name self.logger = logger self.value = value def set(self, new: T) -> None: self.log('Set ' + repr(self.value)) self.value = new def get(self) -> T: self.log('Get ' + repr(self.value)) return self.value def log(self, message: str) -> None: self.logger.info('%s: %s', self.name, message) ``` `Generic[T]` в качестве базового класса определяет, что класс `LoggedVar` принимает один параметр типа `T`. Это также делает `T` допустимым типом внутри тела класса. Базовый класс [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic) определяет [`__class_getitem__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__class_getitem__) так, что `LoggedVar[t]` является допустимым типом: ```python from collections.abc import Iterable def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None: for var in vars: var.set(0) ``` Обобщённый тип может иметь любое количество переменных типа. Все разновидности [`TypeVar`](https://python-all.ru/3.9/library/typing.html#typing.TypeVar) допустимы в качестве параметров обобщённого типа: ```python from typing import TypeVar, Generic, Sequence T = TypeVar('T', contravariant=True) B = TypeVar('B', bound=Sequence[bytes], covariant=True) S = TypeVar('S', int, str) class WeirdTrio(Generic[T, B, S]): ... ``` Каждый аргумент-переменная типа для [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic) должен быть уникальным. Поэтому такой код некорректен: ```python from typing import TypeVar, Generic ... T = TypeVar('T') class Pair(Generic[T, T]): # НЕДОПУСТИМО ... ``` Можно использовать множественное наследование с [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic): ```python from collections.abc import Sized from typing import TypeVar, Generic T = TypeVar('T') class LinkedList(Sized, Generic[T]): ... ``` При наследовании от обобщённых классов некоторые переменные типа могут быть зафиксированы: ```python from collections.abc import Mapping from typing import TypeVar T = TypeVar('T') class MyDict(Mapping[str, T]): ... ``` В этом случае `MyDict` имеет один параметр – `T`. Использование обобщённого класса без указания параметров типа подразумевает [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) для каждой позиции. В следующем примере `MyIterable` не является обобщённым, но неявно наследуется от `Iterable[Any]`: ```python from collections.abc import Iterable class MyIterable(Iterable): # То же, что и Iterable[Any]. ``` Пользовательские обобщённые псевдонимы типов также поддерживаются. Примеры: ```python from collections.abc import Iterable from typing import TypeVar, Union S = TypeVar('S') Response = Union[Iterable[S], int] # Тип возврата здесь такой же, как Union[Iterable[str], int] def response(query: str) -> Response[str]: ... T = TypeVar('T', int, float, complex) Vec = Iterable[tuple[T, T]] def inproduct(v: Vec[T]) -> T: # То же, что и Iterable[tuple[T, T]] return sum(x*y for x, y in v) ``` Изменено в версии 3.7: [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic) больше не имеет собственного метакласса. Пользовательский обобщённый класс может иметь ABC в качестве базовых классов без конфликта метаклассов. Обобщённые метаклассы не поддерживаются. Результат параметризации обобщений кэшируется, и большинство типов в модуле typing являются хешируемыми и сравнимыми на равенство. ## Тип [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) Особым видом типа является [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any). Статический проверяющий типов будет считать каждый тип совместимым с [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), а [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) – совместимым с каждым типом. Это означает, что над значением типа [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) можно выполнять любые операции или вызовы методов и присваивать его любой переменной: ```python from typing import Any a: Any = None a = [] # ОК a = 2 # ОК s: str = '' s = a # ОК def foo(item: Any) -> int: # Проходит проверку типов; 'item' может быть любого типа, # и этот тип может иметь метод 'bar' item.bar() ... ``` Обратите внимание, что никакая проверка типов не выполняется при присваивании значения типа [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) более точному типу. Например, статический проверяющий типы не сообщил об ошибке при присваивании `a` переменной `s`, хотя `s` был объявлен как тип [`str`](https://python-all.ru/3.9/library/stdtypes.html#str) и получает значение [`int`](https://python-all.ru/3.9/library/functions.html#int) во время выполнения! Кроме того, все функции без указания типа возврата или типов параметров по умолчанию неявно используют [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any): ```python def legacy_parser(text): ... return data # Статический проверщик типов будет рассматривать вышеприведенное # как имеющее ту же сигнатуру, что и: def legacy_parser(text: Any) -> Any: ... return data ``` Такое поведение позволяет использовать [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) в качестве *запасного выхода*, когда нужно смешивать динамически и статически типизированный код. Сравните поведение [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) с поведением [`object`](https://python-all.ru/3.9/library/functions.html#object). Как и [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), каждый тип является подтипом [`object`](https://python-all.ru/3.9/library/functions.html#object). Однако, в отличие от [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), обратное неверно: [`object`](https://python-all.ru/3.9/library/functions.html#object) *не* является подтипом любого другого типа. Это означает, что когда тип значения – [`object`](https://python-all.ru/3.9/library/functions.html#object), проверяющий типы будет отклонять почти все операции над ним, а присваивание его переменной (или использование в качестве возвращаемого значения) более специализированного типа является ошибкой типа. Например: ```python def hash_a(item: object) -> int: # Завершается ошибкой; у объекта нет метода 'magic'. item.magic() ... def hash_b(item: Any) -> int: # Проходит проверку типов. item.magic() ... # Проходит проверку типов, так как int и str являются подклассами object. hash_a(42) hash_a("foo") # Проходит проверку типов, так как Any совместим со всеми типами. hash_b(42) hash_b("foo") ``` Используйте [`object`](https://python-all.ru/3.9/library/functions.html#object), чтобы указать, что значение может быть любого типа в типобезопасной манере. Используйте [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), чтобы указать, что значение динамически типизировано. ## Номинальная и структурная типизация Изначально [**PEP 484**](https://python-all.ru/3.9/library/typing.html) определял систему статической типизации Python как использующую *номинальное подтипирование*. Это означает, что класс `A` разрешён там, где ожидается класс `B`, если и только если `A` является подклассом `B`. Ранее это требование также применялось к абстрактным базовым классам, таким как [`Iterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterable). Проблема такого подхода в том, что класс должен быть явно помечен для их поддержки, что непитонично и не похоже на то, что обычно делается в идиоматическом динамически типизированном коде Python. Например, следующее соответствует [**PEP 484**](https://python-all.ru/3.9/library/typing.html): ```python from collections.abc import Sized, Iterable, Iterator class Bucket(Sized, Iterable[int]): ... def __len__(self) -> int: ... def __iter__(self) -> Iterator[int]: ... ``` [**PEP 544**](https://python-all.ru/3.9/library/typing.html) позволяет решить эту проблему, разрешая пользователям писать приведённый выше код без явных базовых классов в определении класса, что позволяет `Bucket` неявно считаться подтипом как `Sized`, так и `Iterable[int]` статическими проверяющими типов. Это называется *структурной подтипизацией* (или статической утиной типизацией): ```python from collections.abc import Iterator, Iterable class Bucket: # Примечание: базовые классы отсутствуют ... def __len__(self) -> int: ... def __iter__(self) -> Iterator[int]: ... def collect(items: Iterable[int]) -> int: ... result = collect(Bucket()) # Проходит проверку типов ``` Более того, наследуя специальный класс [`Protocol`](https://python-all.ru/3.9/library/typing.html#typing.Protocol), пользователь может определять новые пользовательские протоколы, чтобы в полной мере использовать структурное подтипирование (см. примеры ниже). ## Содержимое модуля Модуль определяет следующие классы, функции и декораторы. > **Примечание** > > Данный модуль определяет несколько типов, которые являются подклассами уже существующих классов стандартной библиотеки и которые также расширяют [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic) для поддержки переменных типа внутри `[]`. Эти типы стали избыточными в Python 3.9, когда соответствующие существовавшие классы были расширены для поддержки `[]`. > > Избыточные типы объявлены устаревшими начиная с Python 3.9, но интерпретатор не будет выдавать предупреждений об устаревании. Ожидается, что средства проверки типов будут помечать устаревшие типы, если проверяемая программа нацелена на Python 3.9 или новее. > > Устаревшие типы будут удалены из модуля [`typing`](https://python-all.ru/3.9/library/typing.html#module-typing) в первой версии Python, выпущенной через 5 лет после выхода Python 3.9.0. Подробнее см. в [**PEP 585**](https://python-all.ru/3.9/library/typing.html)–*Аннотации обобщённых типов в стандартных коллекциях*. ### Специальные примитивы типизации #### Специальные типы Их можно использовать как типы в аннотациях, и они не поддерживают `[]`. #### `typing.Any` Специальный тип, указывающий на неограниченный тип. - Каждый тип совместим с [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any). - [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any) совместим с каждым типом. #### `typing.NoReturn` Специальный тип, указывающий, что функция никогда не возвращает значение. Например: ```python from typing import NoReturn def stop() -> NoReturn: raise RuntimeError('no way') ``` Новое в версии 3.5.4. Новое в версии 3.6.2. #### Специальные формы Их можно использовать как типы в аннотациях с помощью `[]`, каждый имеет уникальный синтаксис. #### `typing.Tuple` Тип кортежа; `Tuple[X, Y]` – это тип кортежа из двух элементов, где первый элемент имеет тип X, а второй – Y. Тип пустого кортежа может быть записан как `Tuple[()]`. Пример: `Tuple[T1, T2]` – это кортеж из двух элементов, соответствующих переменным типа T1 и T2. `Tuple[int, float, str]` – это кортеж из int, float и строки. Чтобы задать кортеж переменной длины из однотипных элементов, используйте литеральное многоточие, например `Tuple[int, ...]`. Простой [`Tuple`](https://python-all.ru/3.9/library/typing.html#typing.Tuple) эквивалентен `Tuple[Any, ...]`, а тот, в свою очередь, [`tuple`](https://python-all.ru/3.9/library/stdtypes.html#tuple). Устарело с версии 3.9: [`builtins.tuple`](https://python-all.ru/3.9/library/stdtypes.html#tuple) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `typing.Union` Тип объединения; `Union[X, Y]` означает либо X, либо Y. Чтобы определить объединение, используйте, например, `Union[int, str]`. Подробности: - Аргументы должны быть типами, и их должно быть как минимум один. - Объединения объединений разворачиваются, например: ```python Union[Union[int, str], float] == Union[int, str, float] ``` - Объединения из одного аргумента исчезают, например: ```python Union[int] == int # Конструктор на самом деле возвращает int ``` - Повторяющиеся аргументы пропускаются, например: ```python Union[int, str, int] == Union[int, str] ``` - При сравнении объединений порядок аргументов игнорируется, например: ```python Union[int, str] == Union[str, int] ``` - Нельзя создавать подкласс или экземпляр объединения. - Нельзя записать `Union[X][Y]`. - Можно использовать `Optional[X]` как сокращение для `Union[X, None]`. Изменено в версии 3.7: Явные подклассы не удаляются из объединений во время выполнения. #### `typing.Optional` Тип Optional. `Optional[X]` эквивалентно `Union[X, None]`. Обратите внимание, что это не то же самое, что необязательный аргумент, который имеет значение по умолчанию. Необязательный аргумент с значением по умолчанию не требует квалификатора `Optional` в своей аннотации типа только потому, что он необязателен. Например: ```python def foo(arg: int = 0) -> None: ... ``` С другой стороны, если явное значение `None` допускается, то использование `Optional` уместно, независимо от того, является ли аргумент необязательным или нет. Например: ```python def foo(arg: Optional[int] = None) -> None: ... ``` #### `typing.Callable` Тип Callable; `Callable[[int], str]` – это функция вида (int) -\> str. Синтаксис индексирования всегда должен использоваться ровно с двумя значениями: списком аргументов и типом возвращаемого значения. Список аргументов должен быть списком типов или многоточием; тип возвращаемого значения должен быть одним типом. Нет синтаксиса для указания необязательных или именованных аргументов; такие типы функций редко используются в качестве типов колбэков. `Callable[..., ReturnType]` (буквальное многоточие) можно использовать для аннотации вызываемого объекта, принимающего любое количество аргументов и возвращающего `ReturnType`. Обычное [`Callable`](https://python-all.ru/3.9/library/typing.html#typing.Callable) эквивалентно `Callable[..., Any]`, а в свою очередь – [`collections.abc.Callable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Callable). Устарело с версии 3.9: [`collections.abc.Callable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Callable) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Type(Generic[CT_co])` Переменная, аннотированная `C`, может принимать значение типа `C`. Напротив, переменная, аннотированная `Type[C]`, может принимать значения, которые сами являются классами – а именно, она принимает *объект класса* `C`. Например: ```python a = 3 # Имеет тип 'int' b = int # Имеет тип 'Type[int]' c = type(a) # Также имеет тип 'Type[int]' ``` Обратите внимание, что `Type[C]` ковариантен: ```python class User: ... class BasicUser(User): ... class ProUser(User): ... class TeamUser(User): ... # Принимает User, BasicUser, ProUser, TeamUser, ... def make_new_user(user_class: Type[User]) -> User: # ... return user_class() ``` Тот факт, что `Type[C]` ковариантен, подразумевает, что все подклассы `C` должны реализовывать те же сигнатуры конструктора и методов класса, что и `C`. Средство проверки типов должно отмечать нарушения этого, но также должно разрешать вызовы конструкторов в подклассах, которые соответствуют вызовам конструктора в указанном базовом классе. То, как средство проверки типов должно обрабатывать этот конкретный случай, может измениться в будущих версиях [**PEP 484**](https://python-all.ru/3.9/library/typing.html). Единственными допустимыми параметрами для [`Type`](https://python-all.ru/3.9/library/typing.html#typing.Type) являются классы, [`Any`](https://python-all.ru/3.9/library/typing.html#typing.Any), [переменные типа](https://python-all.ru/3.9/library/typing.html#generics) и объединения любых из этих типов. Например: ```python def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]): ... ``` `Type[Any]` эквивалентен `Type`, который в свою очередь эквивалентен `type`, корню метаклассовой иерархии Python. Новое в версии 3.5.2. Устарело с версии 3.9: [`builtins.type`](https://python-all.ru/3.9/library/functions.html#type) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `typing.Literal` Тип, который можно использовать для указания средствам проверки типов, что соответствующая переменная или параметр функции имеет значение, эквивалентное предоставленному литералу (или одному из нескольких литералов). Например: ```python def validate_simple(data: Any) -> Literal[True]: # всегда возвращает True ... MODE = Literal['r', 'rb', 'w', 'wb'] def open_helper(file: str, mode: MODE) -> str: ... open_helper('/some/path', 'r') # Проходит проверку типов open_helper('/other/path', 'typo') # Ошибка в тайпчекере ``` `Literal[...]` нельзя наследовать. Во время выполнения произвольное значение допускается в качестве аргумента типа для `Literal[...]`, но проверяющие типа могут накладывать ограничения. См. [**PEP 586**](https://python-all.ru/3.9/library/typing.html) для получения дополнительных сведений о литеральных типах. Новое в версии 3.8. Изменено в версии 3.9.1: `Literal` теперь дедуплицирует параметры. Сравнения на равенство объектов `Literal` больше не зависят от порядка. Объекты `Literal` теперь будут вызывать исключение [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError) при сравнении на равенство, если один из их параметров не является [хешируемым](https://python-all.ru/3.9/glossary.html#term-hashable). #### `typing.ClassVar` Специальная конструкция типа для пометки переменных класса. Как представлено в [**PEP 526**](https://python-all.ru/3.9/library/typing.html), аннотация переменной, обёрнутая в ClassVar, указывает, что данный атрибут предназначен для использования в качестве переменной класса и не должен устанавливаться на экземплярах этого класса. Использование: ```python class Starship: stats: ClassVar[dict[str, int]] = {} # переменная класса damage: int = 10 # переменная экземпляра ``` [`ClassVar`](https://python-all.ru/3.9/library/typing.html#typing.ClassVar) принимает только типы и не может быть дополнительно индексирован. [`ClassVar`](https://python-all.ru/3.9/library/typing.html#typing.ClassVar) сам по себе не является классом и не должен использоваться с [`isinstance()`](https://python-all.ru/3.9/library/functions.html#isinstance) или [`issubclass()`](https://python-all.ru/3.9/library/functions.html#issubclass). [`ClassVar`](https://python-all.ru/3.9/library/typing.html#typing.ClassVar) не меняет поведение Python во время выполнения, но может использоваться сторонними проверяющими типов. Например, проверяющий типов может отметить следующий код как ошибочный: ```python enterprise_d = Starship(3000) enterprise_d.stats = {} # Ошибка: установка переменной класса на экземпляре Starship.stats = {} # Это корректно. ``` Новое в версии 3.5.3. #### `typing.Final` Специальная конструкция типов для указания средствам проверки типов, что имя не может быть переприсвоено или переопределено в подклассе. Например: ```python MAX_SIZE: Final = 9000 MAX_SIZE += 1 # Ошибка, выдаваемая проверщиком типов class Connection: TIMEOUT: Final[int] = 10 class FastConnector(Connection): TIMEOUT = 1 # Ошибка, выдаваемая проверщиком типов ``` Проверка этих свойств во время выполнения не выполняется. Подробнее см. [**PEP 591**](https://python-all.ru/3.9/library/typing.html). Новое в версии 3.8. #### `typing.Annotated` Тип, введённый в [**PEP 593**](https://python-all.ru/3.9/library/typing.html) (`Flexible function and variable annotations`), для декорирования существующих типов контекстно-зависимыми метаданными (возможно, несколькими их частями, так как `Annotated` вариадичен). В частности, тип `T` можно аннотировать метаданными `x` с помощью аннотации типа `Annotated[T, x]`. Эти метаданные можно использовать как для статического анализа, так и во время выполнения. Если библиотека (или инструмент) встречает аннотацию типа `Annotated[T, x]` и не имеет специальной логики для метаданных `x`, она должна игнорировать их и просто обрабатывать тип как `T`. В отличие от функциональности `no_type_check`, которая в настоящее время существует в модуле `typing` и полностью отключает проверку типов аннотаций для функции или класса, тип `Annotated` позволяет как статическую проверку типов `T` (которая может безопасно игнорировать `x`), так и доступ к `x` во время выполнения в рамках конкретного приложения. В конечном счёте, ответственность за интерпретацию аннотаций (если вообще) лежит на инструменте или библиотеке, встречающей тип `Annotated`. Инструмент или библиотека, встречающие тип `Annotated`, могут просматривать аннотации, чтобы определить, представляют ли они интерес (например, с помощью `isinstance()`). Когда инструмент или библиотека не поддерживает аннотации или встречает неизвестную аннотацию, она должна просто игнорировать её и обрабатывать аннотированный тип как базовый тип. Инструмент, потребляющий аннотации, сам решает, разрешено ли клиенту иметь несколько аннотаций на одном типе и как объединять эти аннотации. Поскольку тип `Annotated` позволяет помещать несколько аннотаций одного (или разных) типа на любой узел, инструменты или библиотеки, потребляющие эти аннотации, отвечают за обработку возможных дубликатов. Например, если вы выполняете анализ диапазона значений, вы можете разрешить это: ```python T1 = Annotated[int, ValueRange(-10, 5)] T2 = Annotated[T1, ValueRange(-20, 3)] ``` Передача `include_extras=True` в [`get_type_hints()`](https://python-all.ru/3.9/library/typing.html#typing.get_type_hints) позволяет получить доступ к дополнительным аннотациям во время выполнения. Подробности синтаксиса: - Первый аргумент `Annotated` должен быть допустимым типом - Поддерживаются несколько аннотаций типов (`Annotated` поддерживает вариадические аргументы): ```python Annotated[int, ValueRange(3, 10), ctype("char")] ``` - `Annotated` должен вызываться как минимум с двумя аргументами ( `Annotated[int]` недействителен) - Порядок аннотаций сохраняется и важен для проверки на равенство: ```python Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[ int, ctype("char"), ValueRange(3, 10) ] ``` - Вложенные типы `Annotated` уплощаются, при этом метаданные упорядочиваются, начиная с самой внутренней аннотации: ```python Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[ int, ValueRange(3, 10), ctype("char") ] ``` - Дублирующиеся аннотации не удаляются: ```python Annotated[int, ValueRange(3, 10)] != Annotated[ int, ValueRange(3, 10), ValueRange(3, 10) ] ``` - `Annotated` можно использовать с вложенными и обобщёнными псевдонимами: ```python T = TypeVar('T') Vec = Annotated[list[tuple[T, T]], MaxLen(10)] V = Vec[int] V == Annotated[list[tuple[int, int]], MaxLen(10)] ``` Новое в версии 3.9. #### Построение обобщённых типов Они не используются в аннотациях. Это строительные блоки для создания обобщённых типов. #### `class typing.Generic` Абстрактный базовый класс для обобщённых типов. Обобщённый тип обычно объявляется наследованием от экземпляра этого класса с одной или несколькими переменными типа. Например, обобщённый тип отображения может быть определён так: ```python class Mapping(Generic[KT, VT]): def __getitem__(self, key: KT) -> VT: ... # И т.д. ``` Затем этот класс можно использовать следующим образом: ```python X = TypeVar('X') Y = TypeVar('Y') def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y: try: return mapping[key] except KeyError: return default ``` #### `class typing.TypeVar` Переменная типа. Использование: ```python T = TypeVar('T') # Может быть чем угодно S = TypeVar('S', bound=str) # Может быть любым подтипом str A = TypeVar('A', str, bytes) # Должно быть ровно str или bytes ``` Переменные типов существуют в первую очередь для пользы статических средств проверки типов. Они служат параметрами для обобщённых типов, а также для определений обобщённых функций. Смотрите [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic) для получения дополнительной информации об обобщённых типах. Обобщённые функции работают следующим образом: ```python def repeat(x: T, n: int) -> Sequence[T]: """Возвращает список, содержащий n ссылок на x.""" return [x]*n def print_capitalized(x: S) -> S: """Печатает x с заглавной буквы и возвращает x.""" print(x.capitalize()) return x def concatenate(x: A, y: A) -> A: """Складывает две строки или два объекта bytes.""" return x + y ``` Обратите внимание, что переменные типа могут быть *связаны*, *ограничены* или ни тем, ни другим, но не могут быть одновременно и связаны, *и* ограничены. Ограниченные переменные типов и связанные переменные типов имеют разную семантику в нескольких важных аспектах. Использование *ограниченной* переменной типа означает, что `TypeVar` может быть решена только как одна из заданных ограничений: ```python a = concatenate('one', 'two') # Ок, переменная 'a' имеет тип 'str' b = concatenate(StringSubclass('one'), StringSubclass('two')) # Выведенный тип переменной 'b' – 'str', # несмотря на передачу 'StringSubclass' c = concatenate('one', b'two') # ошибка: переменная типа 'A' может быть 'str' или 'bytes' при вызове функции, но не оба сразу ``` Использование *связанной* переменной типа, однако, означает, что `TypeVar` будет решена с использованием наиболее конкретного типа: ```python print_capitalized('a string') # Ок, результат имеет тип 'str' class StringSubclass(str): pass print_capitalized(StringSubclass('another string')) # Ок, результат имеет тип 'StringSubclass' print_capitalized(45) # ошибка: int не является подтипом str ``` Переменные типа могут быть связаны с конкретными типами, абстрактными типами (ABC или протоколами) и даже объединениями типов: ```python U = TypeVar('U', bound=str|bytes) # Может быть любым подтипом объединения str|bytes V = TypeVar('V', bound=SupportsAbs) # Может быть чем угодно с методом __abs__ ``` Связанные переменные типа особенно полезны для аннотирования [`classmethods`](https://python-all.ru/3.9/library/functions.html#classmethod), которые служат альтернативными конструкторами. В следующем примере (© [Raymond Hettinger](https://python-all.ru/3.9/library/typing.html)) переменная типа `C` привязана к классу `Circle` с помощью прямой ссылки. Использование этой переменной типа для аннотирования классового метода `with_circumference` вместо жёстко заданного возвращаемого типа `Circle` означает, что проверяющий типы может корректно вывести возвращаемый тип, даже если метод вызван на подклассе: ```python import math C = TypeVar('C', bound='Circle') class Circle: """Абстрактная окружность""" def __init__(self, radius: float) -> None: self.radius = radius # Используется переменная типа, чтобы показать, что возвращаемый тип # всегда будет экземпляром того, чем является ``cls`` @classmethod def with_circumference(cls: type[C], circumference: float) -> C: """Создать окружность с указанной длиной окружности""" radius = circumference / (math.pi * 2) return cls(radius) class Tire(Circle): """Специализированная окружность (из резины)""" MATERIAL = 'rubber' c = Circle.with_circumference(3) # Ок, переменная 'c' имеет тип 'Circle' t = Tire.with_circumference(4) # Ок, переменная 't' имеет тип 'Tire' (не 'Circle') ``` Во время выполнения `isinstance(x, T)` вызовет [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError). В общем, [`isinstance()`](https://python-all.ru/3.9/library/functions.html#isinstance) и [`issubclass()`](https://python-all.ru/3.9/library/functions.html#issubclass) не должны использоваться с типами. Переменные типа могут быть помечены как ковариантные или контравариантные путём передачи `covariant=True` или `contravariant=True`. См. [**PEP 484**](https://python-all.ru/3.9/library/typing.html) для получения дополнительных сведений. По умолчанию переменные типа инвариантны. #### `typing.AnyStr` `AnyStr` – это [`constrained type variable`](https://python-all.ru/3.9/library/typing.html#typing.TypeVar), определённый как `AnyStr = TypeVar('AnyStr', str, bytes)`. Предназначен для функций, которые могут принимать строки любого типа, не допуская смешивания разных типов строк. Например: ```python def concat(a: AnyStr, b: AnyStr) -> AnyStr: return a + b concat(u"foo", u"bar") # Ок, результат имеет тип 'unicode' concat(b"foo", b"bar") # Ок, результат имеет тип 'bytes' concat(u"foo", b"bar") # Ошибка, нельзя смешивать unicode и bytes ``` #### `class typing.Protocol(Generic)` Базовый класс для классов протоколов. Классы протоколов определяются следующим образом: ```python class Proto(Protocol): def meth(self) -> int: ... ``` Такие классы в основном используются со статическими проверяющими типов, которые распознают структурную подтипизацию (статическую утиную типизацию), например: ```python class C: def meth(self) -> int: return 0 def func(x: Proto) -> int: return x.meth() func(C()) # Проходит статическую проверку типов ``` Подробности см. в [**PEP 544**](https://python-all.ru/3.9/library/typing.html). Классы протоколов, декорированные [`runtime_checkable()`](https://python-all.ru/3.9/library/typing.html#typing.runtime_checkable) (описаны далее), действуют как упрощённые протоколы времени выполнения, которые проверяют только наличие заданных атрибутов, игнорируя их сигнатуры типов. Протокольные классы могут быть обобщёнными, например: ```python class GenProto(Protocol[T]): def meth(self) -> T: ... ``` Новое в версии 3.8. #### `@typing.runtime_checkable` Помечает протокольный класс как протокол времени выполнения. Такой протокол может использоваться с [`isinstance()`](https://python-all.ru/3.9/library/functions.html#isinstance) и [`issubclass()`](https://python-all.ru/3.9/library/functions.html#issubclass). При применении к классу, не являющемуся протоколом, возникает [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError). Это позволяет выполнять простую структурную проверку, очень похожую на “one trick ponies” в [`collections.abc`](https://python-all.ru/3.9/library/collections.abc.html#module-collections.abc), таких как [`Iterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterable). Например: ```python @runtime_checkable class Closable(Protocol): def close(self): ... assert isinstance(open('/some/file'), Closable) ``` > **Примечание** > > [`runtime_checkable()`](https://python-all.ru/3.9/library/typing.html#typing.runtime_checkable) будет проверять только наличие требуемых методов, но не их сигнатуры типов! Например, [`builtins.complex`](https://python-all.ru/3.9/library/functions.html#complex) реализует [`__float__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__float__), поэтому он проходит проверку [`issubclass()`](https://python-all.ru/3.9/library/functions.html#issubclass) на соответствие [`SupportsFloat`](https://python-all.ru/3.9/library/typing.html#typing.SupportsFloat). Однако метод `complex.__float__` существует только для того, чтобы вызвать [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError) с более информативным сообщением. Новое в версии 3.8. #### Другие специальные директивы Они не используются в аннотациях. Это строительные блоки для объявления типов. #### `class typing.NamedTuple` Типизированная версия [`collections.namedtuple()`](https://python-all.ru/3.9/library/collections.html#collections.namedtuple). Использование: ```python class Employee(NamedTuple): name: str id: int ``` Это эквивалентно: ```python Employee = collections.namedtuple('Employee', ['name', 'id']) ``` Чтобы задать полю значение по умолчанию, можно присвоить его в теле класса: ```python class Employee(NamedTuple): name: str id: int = 3 employee = Employee('Guido') assert employee.id == 3 ``` Поля со значением по умолчанию должны следовать после полей без значения по умолчанию. Полученный класс имеет дополнительный атрибут `__annotations__`, который содержит словарь, отображающий имена полей на их типы. (Имена полей находятся в атрибуте `_fields`, а значения по умолчанию – в атрибуте `_field_defaults`; оба они являются частью API [`namedtuple()`](https://python-all.ru/3.9/library/collections.html#collections.namedtuple).) Подклассы `NamedTuple` также могут иметь докстринги и методы: ```python class Employee(NamedTuple): """Представляет сотрудника.""" name: str id: int = 3 def __repr__(self) -> str: return f'' ``` Обратно совместимое использование: ```python Employee = NamedTuple('Employee', [('name', str), ('id', int)]) ``` Изменено в версии 3.6: Добавлена поддержка синтаксиса аннотации переменных [**PEP 526**](https://python-all.ru/3.9/library/typing.html). Изменено в версии 3.6.1: Добавлена поддержка значений по умолчанию, методов и строк документации. Изменено в версии 3.8: Атрибуты `_field_types` и `__annotations__` теперь являются обычными словарями, а не экземплярами `OrderedDict`. Изменено в версии 3.9: Атрибут `_field_types` удалён в пользу более стандартного атрибута `__annotations__`, который содержит ту же информацию. #### `typing.NewType(name, tp)` Вспомогательная функция для указания отдельного типа проверяющему типы, см. [NewType](https://python-all.ru/3.9/library/typing.html#distinct). Во время выполнения она возвращает функцию, которая возвращает свой аргумент. Использование: ```python UserId = NewType('UserId', int) first_user = UserId(1) ``` Новое в версии 3.5.2. #### `class typing.TypedDict(dict)` Специальная конструкция для добавления подсказок типов к словарю. Во время выполнения это обычный [`dict`](https://python-all.ru/3.9/library/stdtypes.html#dict). `TypedDict` объявляет тип словаря, который ожидает, что все его экземпляры будут иметь определённый набор ключей, где каждый ключ связан со значением согласованного типа. Это ожидание не проверяется во время выполнения, а обеспечивается только средствами проверки типов. Использование: ```python class Point2D(TypedDict): x: int y: int label: str a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # ОК b: Point2D = {'z': 3, 'label': 'bad'} # Не проходит проверку типов assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') ``` Чтобы разрешить использование этой возможности в старых версиях Python, которые не поддерживают [**PEP 526**](https://python-all.ru/3.9/library/typing.html), `TypedDict` поддерживает две дополнительные эквивалентные синтаксические формы: - Использование литерала [`dict`](https://python-all.ru/3.9/library/stdtypes.html#dict) в качестве второго аргумента: ```python Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) ``` - Использование именованных аргументов: ```python Point2D = TypedDict('Point2D', x=int, y=int, label=str) ``` Функциональный синтаксис также следует использовать, когда какой-либо из ключей не является допустимым [идентификатором](https://python-all.ru/3.9/reference/lexical_analysis.html#identifiers), например, потому что они являются ключевыми словами или содержат дефисы. Пример: ```python # возбуждает SyntaxError class Point2D(TypedDict): in: int # 'in' – ключевое слово x-y: int # имя с дефисами # ОК, функциональный синтаксис Point2D = TypedDict('Point2D', {'in': int, 'x-y': int}) ``` По умолчанию все ключи должны присутствовать в `TypedDict`. Это можно переопределить, указав totality. Использование: ```python class Point2D(TypedDict, total=False): x: int y: int # Альтернативный синтаксис Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False) ``` Это означает, что `Point2D` `TypedDict` может не содержать любой из ключей. Средство проверки типов должно поддерживать только литерал `False` или `True` в качестве значения аргумента `total`. `True` – значение по умолчанию, и оно делает все элементы, определённые в теле класса, обязательными. `TypedDict` может наследоваться от одного или нескольких других типов `TypedDict` с использованием синтаксиса на основе классов. Использование: ```python class Point3D(Point2D): z: int ``` `Point3D` содержит три элемента: `x`, `y` и `z`. Это эквивалентно следующему определению: ```python class Point3D(TypedDict): x: int y: int z: int ``` `TypedDict` не может наследоваться от не-`TypedDict` класса, включая [`Generic`](https://python-all.ru/3.9/library/typing.html#typing.Generic). Например: ```python class X(TypedDict): x: int class Y(TypedDict): y: int class Z(object): pass # Класс, не являющийся TypedDict class XY(X, Y): pass # ОК class XZ(X, Z): pass # вызывает TypeError T = TypeVar('T') class XT(X, Generic[T]): pass # вызывает TypeError ``` Объект `TypedDict` можно исследовать с помощью `__annotations__`, [`__total__`](https://python-all.ru/3.9/library/typing.html#typing.TypedDict.__total__), [`__required_keys__`](https://python-all.ru/3.9/library/typing.html#typing.TypedDict.__required_keys__) и [`__optional_keys__`](https://python-all.ru/3.9/library/typing.html#typing.TypedDict.__optional_keys__). #### `__total__` `Point2D.__total__` возвращает значение аргумента `total`. Пример: ```python >>> from typing import TypedDict >>> class Point2D(TypedDict): pass >>> Point2D.__total__ True >>> class Point2D(TypedDict, total=False): pass >>> Point2D.__total__ False >>> class Point3D(Point2D): pass >>> Point3D.__total__ True ``` #### `__required_keys__` #### `__optional_keys__` `Point2D.__required_keys__` и `Point2D.__optional_keys__` возвращают объекты [`frozenset`](https://python-all.ru/3.9/library/stdtypes.html#frozenset), содержащие обязательные и необязательные ключи соответственно. В настоящее время единственный способ объявить как обязательные, так и необязательные ключи в одном `TypedDict` – это смешанное наследование: объявить `TypedDict` с одним значением для аргумента `total`, а затем унаследовать его от другого `TypedDict` с другим значением для `total`. Использование: ```python >>> class Point2D(TypedDict, total=False): ... x: int ... y: int ... >>> class Point3D(Point2D): ... z: int ... >>> Point3D.__required_keys__ == frozenset({'z'}) True >>> Point3D.__optional_keys__ == frozenset({'x', 'y'}) True ``` Смотрите [**PEP 589**](https://python-all.ru/3.9/library/typing.html) для дополнительных примеров и подробных правил использования `TypedDict`. Новое в версии 3.8. ### Конкретные обобщённые коллекции #### Соответствующие встроенным типам #### `class typing.Dict(dict, MutableMapping[KT, VT])` Обобщённая версия [`dict`](https://python-all.ru/3.9/library/stdtypes.html#dict). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`Mapping`](https://python-all.ru/3.9/library/typing.html#typing.Mapping). Этот тип можно использовать следующим образом: ```python def count_words(text: str) -> Dict[str, int]: ... ``` Устарело с версии 3.9: [`builtins.dict`](https://python-all.ru/3.9/library/stdtypes.html#dict) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.List(list, MutableSequence[T])` Обобщённая версия [`list`](https://python-all.ru/3.9/library/stdtypes.html#list). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`Sequence`](https://python-all.ru/3.9/library/typing.html#typing.Sequence) или [`Iterable`](https://python-all.ru/3.9/library/typing.html#typing.Iterable). Этот тип можно использовать следующим образом: ```python T = TypeVar('T', int, float) def vec2(x: T, y: T) -> List[T]: return [x, y] def keep_positives(vector: Sequence[T]) -> List[T]: return [item for item in vector if item > 0] ``` Устарело с версии 3.9: [`builtins.list`](https://python-all.ru/3.9/library/stdtypes.html#list) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Set(set, MutableSet[T])` Обобщённая версия [`builtins.set`](https://python-all.ru/3.9/library/stdtypes.html#set). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`AbstractSet`](https://python-all.ru/3.9/library/typing.html#typing.AbstractSet). Устарело с версии 3.9: [`builtins.set`](https://python-all.ru/3.9/library/stdtypes.html#set) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Обобщённый псевдоним типа](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.FrozenSet(frozenset, AbstractSet[T_co])` Обобщённая версия [`builtins.frozenset`](https://python-all.ru/3.9/library/stdtypes.html#frozenset). Устарело с версии 3.9: [`builtins.frozenset`](https://python-all.ru/3.9/library/stdtypes.html#frozenset) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). > **Примечание** > > [`Tuple`](https://python-all.ru/3.9/library/typing.html#typing.Tuple) – это специальная форма. #### Соответствует типам в [`collections`](https://python-all.ru/3.9/library/collections.html#module-collections) #### `class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])` Обобщённая версия [`collections.defaultdict`](https://python-all.ru/3.9/library/collections.html#collections.defaultdict). Новое в версии 3.5.2. Устарело с версии 3.9: [`collections.defaultdict`](https://python-all.ru/3.9/library/collections.html#collections.defaultdict) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])` Обобщённая версия [`collections.OrderedDict`](https://python-all.ru/3.9/library/collections.html#collections.OrderedDict). Добавлено в версии 3.7.2. Устарело с версии 3.9: [`collections.OrderedDict`](https://python-all.ru/3.9/library/collections.html#collections.OrderedDict) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])` Обобщённая версия [`collections.ChainMap`](https://python-all.ru/3.9/library/collections.html#collections.ChainMap). Новое в версии 3.5.4. Новое в версии 3.6.1. Устарело с версии 3.9: [`collections.ChainMap`](https://python-all.ru/3.9/library/collections.html#collections.ChainMap) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Counter(collections.Counter, Dict[T, int])` Обобщённая версия [`collections.Counter`](https://python-all.ru/3.9/library/collections.html#collections.Counter). Новое в версии 3.5.4. Новое в версии 3.6.1. Устарело с версии 3.9: [`collections.Counter`](https://python-all.ru/3.9/library/collections.html#collections.Counter) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Deque(deque, MutableSequence[T])` Обобщённая версия [`collections.deque`](https://python-all.ru/3.9/library/collections.html#collections.deque). Новое в версии 3.5.4. Новое в версии 3.6.1. Устарело с версии 3.9: [`collections.deque`](https://python-all.ru/3.9/library/collections.html#collections.deque) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### Другие конкретные типы #### `class typing.IO` #### `class typing.TextIO` #### `class typing.BinaryIO` Обобщённый тип `IO[AnyStr]` и его подклассы `TextIO(IO[str])` и `BinaryIO(IO[bytes])` представляют типы потоков ввода-вывода, такие как возвращаемые [`open()`](https://python-all.ru/3.9/library/functions.html#open). Устарело с версии 3.8, будет удалено в версии 3.12: Эти типы также находятся в пространстве имён `typing.io`, которое никогда не поддерживалось проверщиками типов и будет удалено. #### `class typing.Pattern` #### `class typing.Match` Эти псевдонимы типов соответствуют возвращаемым типам из [`re.compile()`](https://python-all.ru/3.9/library/re.html#re.compile) и [`re.match()`](https://python-all.ru/3.9/library/re.html#re.match). Эти типы (и соответствующие функции) являются обобщёнными по `AnyStr` и могут быть конкретизированы записью `Pattern[str]`, `Pattern[bytes]`, `Match[str]` или `Match[bytes]`. Устарело с версии 3.8, будет удалено в версии 3.12: Эти типы также находятся в пространстве имён `typing.re`, которое никогда не поддерживалось проверщиками типов и будет удалено. Устарело с версии 3.9: Классы `Pattern` и `Match` из [`re`](https://python-all.ru/3.9/library/re.html#module-re) теперь поддерживают `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Text` `Text` – это псевдоним для `str`. Он предоставляется для обеспечения совместимости с кодом Python 2: в Python 2 `Text` является псевдонимом для `unicode`. Используйте `Text`, чтобы указать, что значение должно содержать строку Unicode, совместимую как с Python 2, так и с Python 3: ```python def add_unicode_checkmark(text: Text) -> Text: return text + u' \u2713' ``` Новое в версии 3.5.2. ### Абстрактные базовые классы #### Соответствуют коллекциям из [`collections.abc`](https://python-all.ru/3.9/library/collections.abc.html#module-collections.abc) #### `class typing.AbstractSet(Sized, Collection[T_co])` Обобщённая версия [`collections.abc.Set`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Set). Устарело с версии 3.9: [`collections.abc.Set`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Set) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.ByteString(Sequence[int])` Обобщённая версия [`collections.abc.ByteString`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ByteString). Этот тип представляет типы [`bytes`](https://python-all.ru/3.9/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.9/library/stdtypes.html#bytearray) и [`memoryview`](https://python-all.ru/3.9/library/stdtypes.html#memoryview) последовательностей байтов. В качестве сокращения для этого типа [`bytes`](https://python-all.ru/3.9/library/stdtypes.html#bytes) можно использовать для аннотации аргументов любого из упомянутых выше типов. Устарело с версии 3.9: [`collections.abc.ByteString`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ByteString) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Collection(Sized, Iterable[T_co], Container[T_co])` Обобщённая версия [`collections.abc.Collection`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Collection) Новое в версии 3.6.0. Устарело с версии 3.9: [`collections.abc.Collection`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Collection) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Container(Generic[T_co])` Обобщённая версия [`collections.abc.Container`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Container). Устарело с версии 3.9: [`collections.abc.Container`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Container) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.ItemsView(MappingView, Generic[KT_co, VT_co])` Обобщённая версия [`collections.abc.ItemsView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ItemsView). Устарело с версии 3.9: [`collections.abc.ItemsView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ItemsView) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.KeysView(MappingView[KT_co], AbstractSet[KT_co])` Обобщённая версия [`collections.abc.KeysView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.KeysView). Устарело с версии 3.9: [`collections.abc.KeysView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.KeysView) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Mapping(Sized, Collection[KT], Generic[VT_co])` Обобщённая версия [`collections.abc.Mapping`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Mapping). Этот тип можно использовать следующим образом: ```python def get_position_in_index(word_list: Mapping[str, int], word: str) -> int: return word_list[word] ``` Устарело с версии 3.9: [`collections.abc.Mapping`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Mapping) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.MappingView(Sized, Iterable[T_co])` Обобщённая версия [`collections.abc.MappingView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MappingView). Устарело с версии 3.9: [`collections.abc.MappingView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MappingView) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.MutableMapping(Mapping[KT, VT])` Обобщённая версия [`collections.abc.MutableMapping`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableMapping). Устарело с версии 3.9: [`collections.abc.MutableMapping`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableMapping) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.MutableSequence(Sequence[T])` Обобщённая версия [`collections.abc.MutableSequence`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableSequence). Устарело с версии 3.9: [`collections.abc.MutableSequence`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableSequence) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.MutableSet(AbstractSet[T])` Обобщённая версия [`collections.abc.MutableSet`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableSet). Устарело с версии 3.9: [`collections.abc.MutableSet`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.MutableSet) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Sequence(Reversible[T_co], Collection[T_co])` Обобщённая версия [`collections.abc.Sequence`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Sequence). Устарело с версии 3.9: [`collections.abc.Sequence`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Sequence) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.ValuesView(MappingView[VT_co])` Обобщённая версия [`collections.abc.ValuesView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ValuesView). Устарело с версии 3.9: [`collections.abc.ValuesView`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.ValuesView) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### Соответствует другим типам в [`collections.abc`](https://python-all.ru/3.9/library/collections.abc.html#module-collections.abc) #### `class typing.Iterable(Generic[T_co])` Обобщённая версия [`collections.abc.Iterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterable). Устарело с версии 3.9: [`collections.abc.Iterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterable) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Iterator(Iterable[T_co])` Обобщённая версия [`collections.abc.Iterator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterator). Устарело с версии 3.9: [`collections.abc.Iterator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Iterator) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])` Генератор можно аннотировать обобщённым типом `Generator[YieldType, SendType, ReturnType]`. Например: ```python def echo_round() -> Generator[int, float, str]: sent = yield 0 while sent >= 0: sent = yield round(sent) return 'Done' ``` Обратите внимание: в отличие от многих других обобщённых типов в модуле typing, `SendType` из [`Generator`](https://python-all.ru/3.9/library/typing.html#typing.Generator) ведёт себя контравариантно, а не ковариантно или инвариантно. Если ваш генератор будет только выдавать значения, установите `SendType` и `ReturnType` в `None`: ```python def infinite_stream(start: int) -> Generator[int, None, None]: while True: yield start start += 1 ``` В качестве альтернативы аннотируйте генератор как имеющий тип возвращаемого значения либо `Iterable[YieldType]`, либо `Iterator[YieldType]`: ```python def infinite_stream(start: int) -> Iterator[int]: while True: yield start start += 1 ``` Устарело с версии 3.9: [`collections.abc.Generator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Generator) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Hashable` Псевдоним для [`collections.abc.Hashable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Hashable). #### `class typing.Reversible(Iterable[T_co])` Обобщённая версия [`collections.abc.Reversible`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Reversible). Устарело с версии 3.9: [`collections.abc.Reversible`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Reversible) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Sized` Псевдоним для [`collections.abc.Sized`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Sized). #### Асинхронное программирование #### `class typing.Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co])` Обобщённая версия [`collections.abc.Coroutine`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Coroutine). Вариантность и порядок переменных типа соответствуют таковым у [`Generator`](https://python-all.ru/3.9/library/typing.html#typing.Generator), например: ```python from collections.abc import Coroutine c: Coroutine[list[str], str, int] # Некоторая корутина, определённая в другом месте. x = c.send('hi') # Выведенный тип 'x' – list[str]. async def bar() -> None: y = await c # Выведенный тип 'y' – int. ``` Новое в версии 3.5.3. Устарело с версии 3.9: [`collections.abc.Coroutine`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Coroutine) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])` Асинхронный генератор можно аннотировать обобщённым типом `AsyncGenerator[YieldType, SendType]`. Например: ```python async def echo_round() -> AsyncGenerator[int, float]: sent = yield 0 while sent >= 0.0: rounded = await round(sent) sent = yield rounded ``` В отличие от обычных генераторов, асинхронные генераторы не могут возвращать значение, поэтому параметр типа `ReturnType` отсутствует. Как и в случае с [`Generator`](https://python-all.ru/3.9/library/typing.html#typing.Generator), `SendType` ведёт себя контравариантно. Если генератор только выдаёт значения, установите `SendType` в `None`: ```python async def infinite_stream(start: int) -> AsyncGenerator[int, None]: while True: yield start start = await increment(start) ``` В качестве альтернативы аннотируйте генератор как имеющий тип возвращаемого значения либо `AsyncIterable[YieldType]`, либо `AsyncIterator[YieldType]`: ```python async def infinite_stream(start: int) -> AsyncIterator[int]: while True: yield start start = await increment(start) ``` Новое в версии 3.6.1. Устарело с версии 3.9: [`collections.abc.AsyncGenerator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.AsyncGenerator) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.AsyncIterable(Generic[T_co])` Обобщённая версия [`collections.abc.AsyncIterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.AsyncIterable). Новое в версии 3.5.2. Устарело с версии 3.9: [`collections.abc.AsyncIterable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.AsyncIterable) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.AsyncIterator(AsyncIterable[T_co])` Обобщённая версия [`collections.abc.AsyncIterator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.AsyncIterator). Новое в версии 3.5.2. Устарело с версии 3.9: [`collections.abc.AsyncIterator`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.AsyncIterator) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.Awaitable(Generic[T_co])` Обобщённая версия [`collections.abc.Awaitable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Awaitable). Новое в версии 3.5.2. Устарело с версии 3.9: [`collections.abc.Awaitable`](https://python-all.ru/3.9/library/collections.abc.html#collections.abc.Awaitable) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### Типы контекстных менеджеров #### `class typing.ContextManager(Generic[T_co])` Обобщённая версия [`contextlib.AbstractContextManager`](https://python-all.ru/3.9/library/contextlib.html#contextlib.AbstractContextManager). Новое в версии 3.5.4. Новое в версии 3.6.0. Устарело с версии 3.9: [`contextlib.AbstractContextManager`](https://python-all.ru/3.9/library/contextlib.html#contextlib.AbstractContextManager) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). #### `class typing.AsyncContextManager(Generic[T_co])` Обобщённая версия [`contextlib.AbstractAsyncContextManager`](https://python-all.ru/3.9/library/contextlib.html#contextlib.AbstractAsyncContextManager). Новое в версии 3.5.4. Новое в версии 3.6.2. Устарело с версии 3.9: [`contextlib.AbstractAsyncContextManager`](https://python-all.ru/3.9/library/contextlib.html#contextlib.AbstractAsyncContextManager) теперь поддерживает `[]`. См. [**PEP 585**](https://python-all.ru/3.9/library/typing.html) и [Generic Alias Type](https://python-all.ru/3.9/library/stdtypes.html#types-genericalias). ### Протоколы Эти протоколы декорированы [`runtime_checkable()`](https://python-all.ru/3.9/library/typing.html#typing.runtime_checkable). #### `class typing.SupportsAbs` ABC с одним абстрактным методом `__abs__`, ковариантным по типу возвращаемого значения. #### `class typing.SupportsBytes` ABC с одним абстрактным методом `__bytes__`. #### `class typing.SupportsComplex` ABC с одним абстрактным методом `__complex__`. #### `class typing.SupportsFloat` ABC с одним абстрактным методом `__float__`. #### `class typing.SupportsIndex` ABC с одним абстрактным методом `__index__`. Новое в версии 3.8. #### `class typing.SupportsInt` ABC с одним абстрактным методом `__int__`. #### `class typing.SupportsRound` ABC с одним абстрактным методом `__round__` ковариантным по возвращаемому типу. ### Функции и декораторы #### `typing.cast(typ, val)` Приводит значение к типу. Это возвращает значение без изменений. Для проверщика типов это сигнализирует, что возвращаемое значение имеет указанный тип, но во время выполнения мы намеренно ничего не проверяем (мы хотим, чтобы это было как можно быстрее). #### `@typing.overload` Декоратор `@overload` позволяет описывать функции и методы, поддерживающие несколько различных комбинаций типов аргументов. За серией определений, декорированных `@overload`, должно следовать ровно одно определение без `@overload` (для той же функции/метода). Определения с `@overload` предназначены только для проверки типов, так как они будут перезаписаны определением без `@overload`, которое используется во время выполнения, но должно игнорироваться проверщиком типов. Во время выполнения прямой вызов функции, декорированной `@overload`, вызовет [`NotImplementedError`](https://python-all.ru/3.9/library/exceptions.html#NotImplementedError). Пример перегрузки, дающей более точный тип, чем можно выразить с помощью объединения или переменной типа: ```python @overload def process(response: None) -> None: ... @overload def process(response: int) -> tuple[int, str]: ... @overload def process(response: bytes) -> str: ... def process(response): ``` См. [**PEP 484**](https://python-all.ru/3.9/library/typing.html) для подробностей и сравнения с другими семантиками типизации. #### `@typing.final` Декоратор, указывающий проверщикам типов, что декорированный метод нельзя переопределить, а декорированный класс нельзя наследовать. Например: ```python class Base: @final def done(self) -> None: ... class Sub(Base): def done(self) -> None: # Ошибка, выдаваемая проверщиком типов ... @final class Leaf: ... class Other(Leaf): # Ошибка, выдаваемая проверщиком типов ... ``` Проверка этих свойств во время выполнения не выполняется. Подробнее см. [**PEP 591**](https://python-all.ru/3.9/library/typing.html). Новое в версии 3.8. #### `@typing.no_type_check` Декоратор, указывающий, что аннотации не являются подсказками типов. Это работает как декоратор класса или функции [декоратор](https://python-all.ru/3.9/glossary.html#term-decorator). В случае класса он рекурсивно применяется ко всем методам, определённым в этом классе (но не к методам, определённым в его суперклассах или подклассах). Это изменяет функцию(и) на месте. #### `@typing.no_type_check_decorator` Декоратор, придающий другому декоратору эффект [`no_type_check()`](https://python-all.ru/3.9/library/typing.html#typing.no_type_check). Он оборачивает декоратор чем-то, что оборачивает декорированную функцию в [`no_type_check()`](https://python-all.ru/3.9/library/typing.html#typing.no_type_check). #### `@typing.type_check_only` Декоратор, помечающий класс или функцию как недоступные во время выполнения. Сам этот декоратор недоступен во время выполнения. Он в основном предназначен для пометки классов, определённых в файлах заглушек типов (type stub), если реализация возвращает экземпляр закрытого класса: ```python @type_check_only class Response: # приватный или недоступный во время выполнения code: int def get_header(self, name: str) -> str: ... def fetch_response() -> Response: ... ``` Обратите внимание, что возврат экземпляров закрытых классов не рекомендуется. Обычно предпочтительнее делать такие классы открытыми. ### Вспомогательные функции для интроспекции #### `typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False)` Возвращает словарь, содержащий аннотации типов для функции, метода, модуля или объекта класса. Это часто совпадает с `obj.__annotations__`. Кроме того, прямые ссылки, закодированные как строковые литералы, обрабатываются путём вычисления их в пространствах имён `globals` и `locals`. При необходимости `Optional[t]` добавляется для аннотаций функций и методов, если задано значение по умолчанию, равное `None`. Для класса `C` возвращается словарь, построенный объединением всех `__annotations__` по `C.__mro__` в обратном порядке. Функция рекурсивно заменяет все `Annotated[T, ...]` на `T`, если только `include_extras` не установлено в `True` (см. [`Annotated`](https://python-all.ru/3.9/library/typing.html#typing.Annotated) для получения дополнительной информации). Например: ```python class Student(NamedTuple): name: Annotated[str, 'some marker'] get_type_hints(Student) == {'name': str} get_type_hints(Student, include_extras=False) == {'name': str} get_type_hints(Student, include_extras=True) == { 'name': Annotated[str, 'some marker'] } ``` Изменено в версии 3.9: Добавлен параметр `include_extras` в рамках [**PEP 593**](https://python-all.ru/3.9/library/typing.html). #### `typing.get_args(tp)` #### `typing.get_origin(tp)` Предоставляют базовую интроспекцию для обобщённых типов и специальных форм typing. Для объекта типизации вида `X[Y, Z, ...]` эти функции возвращают `X` и `(Y, Z, ...)`. Если `X` является обобщенным псевдонимом для встроенного или [`collections`](https://python-all.ru/3.9/library/collections.html#module-collections) класса, он нормализуется до исходного класса. Если `X` является [`Union`](https://python-all.ru/3.9/library/typing.html#typing.Union) или [`Literal`](https://python-all.ru/3.9/library/typing.html#typing.Literal), содержащимся в другом обобщенном типе, порядок `(Y, Z, ...)` может отличаться от порядка исходных аргументов `[Y, Z, ...]` из-за кеширования типов. Для неподдерживаемых объектов возвращается `None` и `()` соответственно. Примеры: ```python assert get_origin(Dict[str, int]) is dict assert get_args(Dict[int, str]) == (int, str) assert get_origin(Union[int, str]) is Union assert get_args(Union[int, str]) == (int, str) ``` Новое в версии 3.8. #### `class typing.ForwardRef` Класс, используемый для внутреннего представления типов строковых прямых ссылок. Например, `List["SomeClass"]` неявно преобразуется в `List[ForwardRef("SomeClass")]`. Этот класс не должен создаваться пользователем, но может использоваться инструментами интроспекции. > **Примечание** > > обобщённые типы [**PEP 585**](https://python-all.ru/3.9/library/typing.html), такие как `list["SomeClass"]`, не будут неявно преобразовываться в `list[ForwardRef("SomeClass")]` и, следовательно, не будут автоматически разрешаться в `list[SomeClass]`. Новое в версии 3.7.4. ### Константа #### `typing.TYPE_CHECKING` Специальная константа, которая считается `True` сторонними статическими проверщиками типов. Во время выполнения она равна `False`. Применение: ```python if TYPE_CHECKING: import expensive_mod def fun(arg: 'expensive_mod.SomeType') -> None: local_var: expensive_mod.AnotherType = other_fun() ``` Первую аннотацию типа необходимо заключать в кавычки, превращая её в «прямую ссылку» (forward reference), чтобы скрыть ссылку `expensive_mod` от интерпретатора во время выполнения. Аннотации типов для локальных переменных не вычисляются, поэтому вторую аннотацию не нужно заключать в кавычки. > **Примечание** > > Если используется `from __future__ import annotations`, аннотации не вычисляются во время определения функции. Вместо этого они сохраняются как строки в `__annotations__`. Это избавляет от необходимости заключать аннотацию в кавычки (см. [**PEP 563**](https://python-all.ru/3.9/library/typing.html)). Новое в версии 3.5.2.