`typing.md`

1055 строк · 58.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.7/library/typing.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`typing`](https://python-all.ru/3.7/library/typing.html#module-typing) – Поддержка аннотаций типов89Новое в версии 3.5.1011**Исходный код:** [Lib/typing.py](https://python-all.ru/src/3.7/Lib/typing.py)1213> **Примечание**14>15> Среда выполнения Python не проверяет аннотации типов функций и переменных. Они могут использоваться сторонними инструментами, такими как средства проверки типов, IDE, линтеры и т. д.1617---1819Этот модуль поддерживает аннотации типов, определённые в [**PEP 484**](https://python-all.ru/3.7/library/typing.html) и [**PEP 526**](https://python-all.ru/3.7/library/typing.html). Самая базовая поддержка состоит из типов [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any), [`Union`](https://python-all.ru/3.7/library/typing.html#typing.Union), [`Tuple`](https://python-all.ru/3.7/library/typing.html#typing.Tuple), [`Callable`](https://python-all.ru/3.7/library/typing.html#typing.Callable), [`TypeVar`](https://python-all.ru/3.7/library/typing.html#typing.TypeVar) и [`Generic`](https://python-all.ru/3.7/library/typing.html#typing.Generic). Полную спецификацию см. в [**PEP 484**](https://python-all.ru/3.7/library/typing.html). Упрощённое введение в аннотации типов – в [**PEP 483**](https://python-all.ru/3.7/library/typing.html).2021Функция ниже принимает и возвращает строку и аннотирована следующим образом:2223```python24def greeting(name: str) -> str:25    return 'Hello ' + name26```2728В функции `greeting` аргумент `name` ожидается типа [`str`](https://python-all.ru/3.7/library/stdtypes.html#str), а возвращаемый тип – [`str`](https://python-all.ru/3.7/library/stdtypes.html#str). Подтипы допускаются в качестве аргументов.2930## Псевдонимы типов3132Псевдоним типа определяется присваиванием типа псевдониму. В этом примере `Vector` и `List[float]` будут рассматриваться как взаимозаменяемые синонимы:3334```python35from typing import List36Vector = List[float]3738def scale(scalar: float, vector: Vector) -> Vector:39    return [scalar * num for num in vector]4041# Проходит проверку типов; список чисел с плавающей запятой считается Vector.42new_vector = scale(2.0, [1.0, -4.2, 5.4])43```4445Псевдонимы типов полезны для упрощения сложных сигнатур типов. Например:4647```python48from typing import Dict, Tuple, Sequence4950ConnectionOptions = Dict[str, str]51Address = Tuple[str, int]52Server = Tuple[Address, ConnectionOptions]5354def broadcast_message(message: str, servers: Sequence[Server]) -> None:55    ...5657# Статическая проверка типов будет считать предыдущую сигнатуру типа как58# полностью эквивалентную этой.59def broadcast_message(60        message: str,61        servers: Sequence[Tuple[Tuple[str, int], Dict[str, str]]]) -> None:62    ...63```6465Обратите внимание, что `None` как аннотация типа является особым случаем и заменяется на `type(None)`.6667## NewType6869Для создания отдельных типов используется вспомогательная функция [`NewType()`](https://python-all.ru/3.7/library/typing.html#typing.NewType):7071```python72from typing import NewType7374UserId = NewType('UserId', int)75some_id = UserId(524313)76```7778Статический проверщик типов будет рассматривать новый тип как подкласс исходного типа. Это полезно для выявления логических ошибок:7980```python81def get_user_name(user_id: UserId) -> str:82    ...8384# Проходит проверку типов.85user_a = get_user_name(UserId(42351))8687# Не проходит проверку типов; int не является UserId.88user_b = get_user_name(-1)89```9091Можно по-прежнему выполнять все операции `int` над переменной типа `UserId`, но результат всегда будет типа `int`. Это позволяет передавать `UserId` везде, где может ожидаться `int`, но предотвращает случайное создание `UserId` недопустимым способом:9293```python94# 'output' имеет тип 'int', а не 'UserId'95output = UserId(23413) + UserId(54341)96```9798Обратите внимание, что эти проверки выполняются только статическим анализатором типов. Во время выполнения инструкция `Derived = NewType('Derived', Base)` превращает `Derived` в функцию, которая немедленно возвращает переданный ей параметр. Это означает, что выражение `Derived(some_value)` не создаёт новый класс и не вносит никаких накладных расходов, кроме обычного вызова функции.99100Точнее, выражение `some_value is Derived(some_value)` во время выполнения всегда истинно.101102Это также означает, что невозможно создать подтип `Derived`, поскольку во время выполнения это тождественная функция, а не реальный тип:103104```python105from typing import NewType106107UserId = NewType('UserId', int)108109# Завершается ошибкой во время выполнения и не проходит проверку типов.110class AdminUserId(UserId): pass111```112113Однако можно создать [`NewType()`](https://python-all.ru/3.7/library/typing.html#typing.NewType) на основе «производного» `NewType`:114115```python116from typing import NewType117118UserId = NewType('UserId', int)119120ProUserId = NewType('ProUserId', UserId)121```122123и проверка типов для `ProUserId` будет работать как ожидается.124125Подробнее см. [**PEP 484**](https://python-all.ru/3.7/library/typing.html).126127> **Примечание**128>129> Напомним, что использование псевдонима типа объявляет два типа *эквивалентными* друг другу. Использование `Alias = Original` заставит статический анализатор типов считать `Alias` *точно эквивалентным* `Original` во всех случаях. Это полезно, когда требуется упростить сложные сигнатуры типов.130>131> В отличие от этого, `NewType` объявляет один тип *подтипом* другого. Использование `Derived = NewType('Derived', Original)` заставит статический анализатор типов считать `Derived` *подклассом* `Original`, что означает, что значение типа `Original` не может использоваться там, где ожидается значение типа `Derived`. Это полезно для предотвращения логических ошибок с минимальными затратами времени выполнения.132133Новое в версии 3.5.2.134135## Callable136137Фреймворки, ожидающие функции обратного вызова с определённой сигнатурой, могут быть аннотированы с помощью `Callable[[Arg1Type, Arg2Type], ReturnType]`.138139Например:140141```python142from typing import Callable143144def feeder(get_next_item: Callable[[], str]) -> None:145    # Тело146147def async_query(on_success: Callable[[int], None],148                on_error: Callable[[int, Exception], None]) -> None:149    # Тело150```151152Можно объявить возвращаемый тип вызываемого объекта, не указывая сигнатуру вызова, заменив список аргументов многоточием в аннотации типа: `Callable[..., ReturnType]`.153154## Обобщённые типы155156Поскольку информацию о типах объектов, хранящихся в контейнерах, нельзя статически вывести обобщённым способом, абстрактные базовые классы были расширены для поддержки параметризации типами, чтобы обозначить ожидаемые типы элементов контейнера.157158```python159from typing import Mapping, Sequence160161def notify_by_email(employees: Sequence[Employee],162                    overrides: Mapping[str, str]) -> None: ...163```164165Обобщения (дженерики) можно параметризовать с помощью новой фабрики, доступной в typing, которая называется [`TypeVar`](https://python-all.ru/3.7/library/typing.html#typing.TypeVar).166167```python168from typing import Sequence, TypeVar169170T = TypeVar('T')      # Объявить переменную типа171172def first(l: Sequence[T]) -> T:   # Обобщённая функция173    return l[0]174```175176## Пользовательские обобщённые типы177178Пользовательский класс можно определить как обобщённый класс.179180```python181from typing import TypeVar, Generic182from logging import Logger183184T = TypeVar('T')185186class LoggedVar(Generic[T]):187    def __init__(self, value: T, name: str, logger: Logger) -> None:188        self.name = name189        self.logger = logger190        self.value = value191192    def set(self, new: T) -> None:193        self.log('Set ' + repr(self.value))194        self.value = new195196    def get(self) -> T:197        self.log('Get ' + repr(self.value))198        return self.value199200    def log(self, message: str) -> None:201        self.logger.info('%s: %s', self.name, message)202```203204`Generic[T]` в качестве базового класса определяет, что класс `LoggedVar` принимает один параметр типа `T`. Это также делает `T` допустимым типом внутри тела класса.205206Базовый класс [`Generic`](https://python-all.ru/3.7/library/typing.html#typing.Generic) определяет [`__class_getitem__()`](https://python-all.ru/3.7/reference/datamodel.html#object.__class_getitem__), что делает `LoggedVar[t]` допустимым в качестве типа:207208```python209from typing import Iterable210211def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:212    for var in vars:213        var.set(0)214```215216Обобщённый тип может иметь любое количество переменных типа, и эти переменные могут быть ограничены:217218```python219from typing import TypeVar, Generic220...221222T = TypeVar('T')223S = TypeVar('S', int, str)224225class StrangePair(Generic[T, S]):226    ...227```228229Каждый аргумент-переменная типа для [`Generic`](https://python-all.ru/3.7/library/typing.html#typing.Generic) должен быть уникальным. Поэтому такой код некорректен:230231```python232from typing import TypeVar, Generic233...234235T = TypeVar('T')236237class Pair(Generic[T, T]):   # НЕДОПУСТИМО238    ...239```240241Можно использовать множественное наследование с [`Generic`](https://python-all.ru/3.7/library/typing.html#typing.Generic):242243```python244from typing import TypeVar, Generic, Sized245246T = TypeVar('T')247248class LinkedList(Sized, Generic[T]):249    ...250```251252При наследовании от обобщённых классов некоторые переменные типа могут быть зафиксированы:253254```python255from typing import TypeVar, Mapping256257T = TypeVar('T')258259class MyDict(Mapping[str, T]):260    ...261```262263В этом случае `MyDict` имеет один параметр – `T`.264265Использование обобщённого класса без указания параметров типа подразумевает [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any) для каждой позиции. В следующем примере `MyIterable` не является обобщённым, но неявно наследуется от `Iterable[Any]`:266267```python268from typing import Iterable269270class MyIterable(Iterable): # То же, что и Iterable[Any].271```272273Пользовательские обобщённые псевдонимы типов также поддерживаются. Примеры:274275```python276from typing import TypeVar, Iterable, Tuple, Union277S = TypeVar('S')278Response = Union[Iterable[S], int]279280# Тип возврата здесь такой же, как Union[Iterable[str], int]281def response(query: str) -> Response[str]:282    ...283284T = TypeVar('T', int, float, complex)285Vec = Iterable[Tuple[T, T]]286287def inproduct(v: Vec[T]) -> T: # То же, что Iterable[Tuple[T, T]]288    return sum(x*y for x, y in v)289```290291Изменено в версии 3.7: [`Generic`](https://python-all.ru/3.7/library/typing.html#typing.Generic) больше не имеет собственного метакласса.292293Пользовательский обобщённый класс может иметь ABC в качестве базовых классов без конфликта метаклассов. Обобщённые метаклассы не поддерживаются. Результат параметризации обобщений кэшируется, и большинство типов в модуле typing являются хешируемыми и сравнимыми на равенство.294295## Тип [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any)296297Особым видом типа является [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any). Статический проверяющий типов будет считать каждый тип совместимым с [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any), а [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any) – совместимым с каждым типом.298299Это означает, что над значением типа [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any) можно выполнять любые операции или вызовы методов и присваивать его любой переменной:300301```python302from typing import Any303304a = None    # type: Any305a = []      # ОК306a = 2       # ОК307308s = ''      # type: str309s = a       # ОК310311def foo(item: Any) -> int:312    # Проходит проверку типов; 'item' может быть любого типа,313    # и этот тип может иметь метод 'bar'314    item.bar()315    ...316```317318Обратите внимание, что никакая проверка типов не выполняется при присваивании значения типа [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any) более точному типу. Например, статический проверяющий типы не сообщил об ошибке при присваивании `a` переменной `s`, хотя `s` был объявлен как тип [`str`](https://python-all.ru/3.7/library/stdtypes.html#str) и получает значение [`int`](https://python-all.ru/3.7/library/functions.html#int) во время выполнения!319320Кроме того, все функции без указания типа возврата или типов параметров по умолчанию неявно используют [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any):321322```python323def legacy_parser(text):324    ...325    return data326327# Статический проверщик типов будет рассматривать вышеприведенное328# как имеющее ту же сигнатуру, что и:329def legacy_parser(text: Any) -> Any:330    ...331    return data332```333334Такое поведение позволяет использовать [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any) в качестве *запасного выхода*, когда нужно смешивать динамически и статически типизированный код.335336Сравните поведение [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any) с поведением [`object`](https://python-all.ru/3.7/library/functions.html#object). Как и [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any), каждый тип является подтипом [`object`](https://python-all.ru/3.7/library/functions.html#object). Однако, в отличие от [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any), обратное неверно: [`object`](https://python-all.ru/3.7/library/functions.html#object) *не* является подтипом любого другого типа.337338Это означает, что когда тип значения – [`object`](https://python-all.ru/3.7/library/functions.html#object), проверяющий типы будет отклонять почти все операции над ним, а присваивание его переменной (или использование в качестве возвращаемого значения) более специализированного типа является ошибкой типа. Например:339340```python341def hash_a(item: object) -> int:342    # Завершается ошибкой; у объекта нет метода 'magic'.343    item.magic()344    ...345346def hash_b(item: Any) -> int:347    # Проходит проверку типов.348    item.magic()349    ...350351# Проходит проверку типов, так как int и str являются подклассами object.352hash_a(42)353hash_a("foo")354355# Проходит проверку типов, так как Any совместим со всеми типами.356hash_b(42)357hash_b("foo")358```359360Используйте [`object`](https://python-all.ru/3.7/library/functions.html#object), чтобы указать, что значение может быть любого типа в типобезопасной манере. Используйте [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any), чтобы указать, что значение динамически типизировано.361362## Классы, функции и декораторы363364Модуль определяет следующие классы, функции и декораторы:365366#### `class typing.TypeVar`367368Переменная типа.369370Использование:371372```python373T = TypeVar('T')  # Может быть чем угодно374A = TypeVar('A', str, bytes)  # Должно быть str или bytes375```376377Переменные типа существуют в первую очередь для статических анализаторов типов. Они служат параметрами для обобщённых типов, а также для определений обобщённых функций. См. класс Generic для получения дополнительной информации об обобщённых типах. Обобщённые функции работают следующим образом:378379```python380def repeat(x: T, n: int) -> Sequence[T]:381    """Возвращает список, содержащий n ссылок на x."""382    return [x]*n383384def longest(x: A, y: A) -> A:385    """Возвращает самую длинную из двух строк."""386    return x if len(x) >= len(y) else y387```388389Сигнатура последнего примера по сути является перегрузкой `(str, str) -> str` и `(bytes, bytes) -> bytes`. Также обратите внимание, что если аргументы являются экземплярами какого-либо подкласса [`str`](https://python-all.ru/3.7/library/stdtypes.html#str), возвращаемый тип остаётся простым [`str`](https://python-all.ru/3.7/library/stdtypes.html#str).390391Во время выполнения `isinstance(x, T)` вызовет [`TypeError`](https://python-all.ru/3.7/library/exceptions.html#TypeError). В общем, [`isinstance()`](https://python-all.ru/3.7/library/functions.html#isinstance) и [`issubclass()`](https://python-all.ru/3.7/library/functions.html#issubclass) не должны использоваться с типами.392393Переменные типа могут быть помечены как ковариантные или контравариантные путём передачи `covariant=True` или `contravariant=True`. См. [**PEP 484**](https://python-all.ru/3.7/library/typing.html) для подробностей. По умолчанию переменные типа инвариантны. В качестве альтернативы, переменная типа может указывать верхнюю границу с помощью `bound=<type>`. Это означает, что фактический тип, подставленный (явно или неявно) для переменной типа, должен быть подклассом граничного типа, см. [**PEP 484**](https://python-all.ru/3.7/library/typing.html).394395#### `class typing.Generic`396397Абстрактный базовый класс для обобщённых типов.398399Обобщённый тип обычно объявляется наследованием от экземпляра этого класса с одной или несколькими переменными типа. Например, обобщённый тип отображения может быть определён так:400401```python402class Mapping(Generic[KT, VT]):403    def __getitem__(self, key: KT) -> VT:404        ...405        # И т.д.406```407408Затем этот класс можно использовать следующим образом:409410```python411X = TypeVar('X')412Y = TypeVar('Y')413414def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:415    try:416        return mapping[key]417    except KeyError:418        return default419```420421#### `class typing.Type(Generic[CT_co])`422423Переменная, аннотированная `C`, может принимать значение типа `C`. Напротив, переменная, аннотированная `Type[C]`, может принимать значения, которые сами являются классами – а именно, она принимает *объект класса* `C`. Например:424425```python426a = 3         # Имеет тип 'int'427b = int       # Имеет тип 'Type[int]'428c = type(a)   # Также имеет тип 'Type[int]'429```430431Обратите внимание, что `Type[C]` ковариантен:432433```python434class User: ...435class BasicUser(User): ...436class ProUser(User): ...437class TeamUser(User): ...438439# Принимает User, BasicUser, ProUser, TeamUser, ...440def make_new_user(user_class: Type[User]) -> User:441    # ...442    return user_class()443```444445Тот факт, что `Type[C]` ковариантен, подразумевает, что все подклассы `C` должны реализовывать те же сигнатуры конструктора и методов класса, что и `C`. Средство проверки типов должно отмечать нарушения этого, но также должно разрешать вызовы конструкторов в подклассах, которые соответствуют вызовам конструктора в указанном базовом классе. То, как средство проверки типов должно обрабатывать этот конкретный случай, может измениться в будущих версиях [**PEP 484**](https://python-all.ru/3.7/library/typing.html).446447Единственными допустимыми параметрами для [`Type`](https://python-all.ru/3.7/library/typing.html#typing.Type) являются классы, [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any), [переменные типа](https://python-all.ru/3.7/library/typing.html#generics) и объединения любых из этих типов. Например:448449```python450def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...451```452453`Type[Any]` эквивалентен `Type`, который в свою очередь эквивалентен `type`, корню метаклассовой иерархии Python.454455Новое в версии 3.5.2.456457#### `class typing.Iterable(Generic[T_co])`458459Обобщённая версия [`collections.abc.Iterable`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Iterable).460461#### `class typing.Iterator(Iterable[T_co])`462463Обобщённая версия [`collections.abc.Iterator`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Iterator).464465#### `class typing.Reversible(Iterable[T_co])`466467Обобщённая версия [`collections.abc.Reversible`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Reversible).468469#### `class typing.SupportsInt`470471ABC с одним абстрактным методом `__int__`.472473#### `class typing.SupportsFloat`474475ABC с одним абстрактным методом `__float__`.476477#### `class typing.SupportsComplex`478479ABC с одним абстрактным методом `__complex__`.480481#### `class typing.SupportsBytes`482483ABC с одним абстрактным методом `__bytes__`.484485#### `class typing.SupportsAbs`486487ABC с одним абстрактным методом `__abs__`, ковариантным по типу возвращаемого значения.488489#### `class typing.SupportsRound`490491ABC с одним абстрактным методом `__round__` ковариантным по возвращаемому типу.492493#### `class typing.Container(Generic[T_co])`494495Обобщённая версия [`collections.abc.Container`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Container).496497#### `class typing.Hashable`498499Псевдоним для [`collections.abc.Hashable`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Hashable)500501#### `class typing.Sized`502503Псевдоним для [`collections.abc.Sized`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Sized)504505#### `class typing.Collection(Sized, Iterable[T_co], Container[T_co])`506507Обобщённая версия [`collections.abc.Collection`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Collection)508509Новое в версии 3.6.0.510511#### `class typing.AbstractSet(Sized, Collection[T_co])`512513Обобщённая версия [`collections.abc.Set`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Set).514515#### `class typing.MutableSet(AbstractSet[T])`516517Обобщённая версия [`collections.abc.MutableSet`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.MutableSet).518519#### `class typing.Mapping(Sized, Collection[KT], Generic[VT_co])`520521Обобщённая версия [`collections.abc.Mapping`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Mapping). Этот тип можно использовать следующим образом:522523```python524def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:525    return word_list[word]526```527528#### `class typing.MutableMapping(Mapping[KT, VT])`529530Обобщённая версия [`collections.abc.MutableMapping`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.MutableMapping).531532#### `class typing.Sequence(Reversible[T_co], Collection[T_co])`533534Обобщённая версия [`collections.abc.Sequence`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Sequence).535536#### `class typing.MutableSequence(Sequence[T])`537538Обобщённая версия [`collections.abc.MutableSequence`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.MutableSequence).539540#### `class typing.ByteString(Sequence[int])`541542Обобщённая версия [`collections.abc.ByteString`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.ByteString).543544Этот тип представляет типы [`bytes`](https://python-all.ru/3.7/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.7/library/stdtypes.html#bytearray) и [`memoryview`](https://python-all.ru/3.7/library/stdtypes.html#memoryview).545546В качестве сокращения для этого типа [`bytes`](https://python-all.ru/3.7/library/stdtypes.html#bytes) можно использовать для аннотации аргументов любого из упомянутых выше типов.547548#### `class typing.Deque(deque, MutableSequence[T])`549550Обобщённая версия [`collections.deque`](https://python-all.ru/3.7/library/collections.html#collections.deque).551552Новое в версии 3.5.4.553554Новое в версии 3.6.1.555556#### `class typing.List(list, MutableSequence[T])`557558Обобщённая версия [`list`](https://python-all.ru/3.7/library/stdtypes.html#list). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`Sequence`](https://python-all.ru/3.7/library/typing.html#typing.Sequence) или [`Iterable`](https://python-all.ru/3.7/library/typing.html#typing.Iterable).559560Этот тип можно использовать следующим образом:561562```python563T = TypeVar('T', int, float)564565def vec2(x: T, y: T) -> List[T]:566    return [x, y]567568def keep_positives(vector: Sequence[T]) -> List[T]:569    return [item for item in vector if item > 0]570```571572#### `class typing.Set(set, MutableSet[T])`573574Обобщённая версия [`builtins.set`](https://python-all.ru/3.7/library/stdtypes.html#set). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`AbstractSet`](https://python-all.ru/3.7/library/typing.html#typing.AbstractSet).575576#### `class typing.FrozenSet(frozenset, AbstractSet[T_co])`577578Обобщённая версия [`builtins.frozenset`](https://python-all.ru/3.7/library/stdtypes.html#frozenset).579580#### `class typing.MappingView(Sized, Iterable[T_co])`581582Обобщённая версия [`collections.abc.MappingView`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.MappingView).583584#### `class typing.KeysView(MappingView[KT_co], AbstractSet[KT_co])`585586Обобщённая версия [`collections.abc.KeysView`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.KeysView).587588#### `class typing.ItemsView(MappingView, Generic[KT_co, VT_co])`589590Обобщённая версия [`collections.abc.ItemsView`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.ItemsView).591592#### `class typing.ValuesView(MappingView[VT_co])`593594Обобщённая версия [`collections.abc.ValuesView`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.ValuesView).595596#### `class typing.Awaitable(Generic[T_co])`597598Обобщённая версия [`collections.abc.Awaitable`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Awaitable).599600Новое в версии 3.5.2.601602#### `class typing.Coroutine(Awaitable[V_co], Generic[T_co T_contra, V_co])`603604Обобщённая версия [`collections.abc.Coroutine`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Coroutine). Вариантность и порядок переменных типа соответствуют таковым у [`Generator`](https://python-all.ru/3.7/library/typing.html#typing.Generator), например:605606```python607from typing import List, Coroutine608c = None # type: Coroutine[List[str], str, int]609...610x = c.send('hi') # type: List[str]611async def bar() -> None:612    x = await c # type: int613```614615Новое в версии 3.5.3.616617#### `class typing.AsyncIterable(Generic[T_co])`618619Обобщённая версия [`collections.abc.AsyncIterable`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.AsyncIterable).620621Новое в версии 3.5.2.622623#### `class typing.AsyncIterator(AsyncIterable[T_co])`624625Обобщённая версия [`collections.abc.AsyncIterator`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.AsyncIterator).626627Новое в версии 3.5.2.628629#### `class typing.ContextManager(Generic[T_co])`630631Обобщённая версия [`contextlib.AbstractContextManager`](https://python-all.ru/3.7/library/contextlib.html#contextlib.AbstractContextManager).632633Новое в версии 3.5.4.634635Новое в версии 3.6.0.636637#### `class typing.AsyncContextManager(Generic[T_co])`638639Обобщённая версия [`contextlib.AbstractAsyncContextManager`](https://python-all.ru/3.7/library/contextlib.html#contextlib.AbstractAsyncContextManager).640641Новое в версии 3.5.4.642643Новое в версии 3.6.2.644645#### `class typing.Dict(dict, MutableMapping[KT, VT])`646647Обобщённая версия [`dict`](https://python-all.ru/3.7/library/stdtypes.html#dict). Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например [`Mapping`](https://python-all.ru/3.7/library/typing.html#typing.Mapping).648649Этот тип можно использовать следующим образом:650651```python652def count_words(text: str) -> Dict[str, int]:653    ...654```655656#### `class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])`657658Обобщённая версия [`collections.defaultdict`](https://python-all.ru/3.7/library/collections.html#collections.defaultdict).659660Новое в версии 3.5.2.661662#### `class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])`663664Обобщённая версия [`collections.OrderedDict`](https://python-all.ru/3.7/library/collections.html#collections.OrderedDict).665666Добавлено в версии 3.7.2.667668#### `class typing.Counter(collections.Counter, Dict[T, int])`669670Обобщённая версия [`collections.Counter`](https://python-all.ru/3.7/library/collections.html#collections.Counter).671672Новое в версии 3.5.4.673674Новое в версии 3.6.1.675676#### `class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])`677678Обобщённая версия [`collections.ChainMap`](https://python-all.ru/3.7/library/collections.html#collections.ChainMap).679680Новое в версии 3.5.4.681682Новое в версии 3.6.1.683684#### `class typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])`685686Генератор можно аннотировать обобщённым типом `Generator[YieldType, SendType, ReturnType]`. Например:687688```python689def echo_round() -> Generator[int, float, str]:690    sent = yield 0691    while sent >= 0:692        sent = yield round(sent)693    return 'Done'694```695696Обратите внимание: в отличие от многих других обобщённых типов в модуле typing, `SendType` из [`Generator`](https://python-all.ru/3.7/library/typing.html#typing.Generator) ведёт себя контравариантно, а не ковариантно или инвариантно.697698Если ваш генератор будет только выдавать значения, установите `SendType` и `ReturnType` в `None`:699700```python701def infinite_stream(start: int) -> Generator[int, None, None]:702    while True:703        yield start704        start += 1705```706707В качестве альтернативы аннотируйте генератор как имеющий тип возвращаемого значения либо `Iterable[YieldType]`, либо `Iterator[YieldType]`:708709```python710def infinite_stream(start: int) -> Iterator[int]:711    while True:712        yield start713        start += 1714```715716#### `class typing.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])`717718Асинхронный генератор можно аннотировать обобщённым типом `AsyncGenerator[YieldType, SendType]`. Например:719720```python721async def echo_round() -> AsyncGenerator[int, float]:722    sent = yield 0723    while sent >= 0.0:724        rounded = await round(sent)725        sent = yield rounded726```727728В отличие от обычных генераторов, асинхронные генераторы не могут возвращать значение, поэтому параметр типа `ReturnType` отсутствует. Как и в случае с [`Generator`](https://python-all.ru/3.7/library/typing.html#typing.Generator), `SendType` ведёт себя контравариантно.729730Если генератор только выдаёт значения, установите `SendType` в `None`:731732```python733async def infinite_stream(start: int) -> AsyncGenerator[int, None]:734    while True:735        yield start736        start = await increment(start)737```738739В качестве альтернативы аннотируйте генератор как имеющий тип возвращаемого значения либо `AsyncIterable[YieldType]`, либо `AsyncIterator[YieldType]`:740741```python742async def infinite_stream(start: int) -> AsyncIterator[int]:743    while True:744        yield start745        start = await increment(start)746```747748Новое в версии 3.6.1.749750#### `class typing.Text`751752`Text` – это псевдоним для `str`. Он предоставляется для обеспечения совместимости с кодом Python 2: в Python 2 `Text` является псевдонимом для `unicode`.753754Используйте `Text`, чтобы указать, что значение должно содержать строку Unicode, совместимую как с Python 2, так и с Python 3:755756```python757def add_unicode_checkmark(text: Text) -> Text:758    return text + u' \u2713'759```760761Новое в версии 3.5.2.762763#### `class typing.IO`764765#### `class typing.TextIO`766767#### `class typing.BinaryIO`768769Обобщённый тип `IO[AnyStr]` и его подклассы `TextIO(IO[str])` и `BinaryIO(IO[bytes])` представляют типы потоков ввода-вывода, такие как возвращаемые [`open()`](https://python-all.ru/3.7/library/functions.html#open).770771#### `class typing.Pattern`772773#### `class typing.Match`774775Эти псевдонимы типов соответствуют возвращаемым типам из [`re.compile()`](https://python-all.ru/3.7/library/re.html#re.compile) и [`re.match()`](https://python-all.ru/3.7/library/re.html#re.match). Эти типы (и соответствующие функции) являются обобщёнными по `AnyStr` и могут быть конкретизированы записью `Pattern[str]`, `Pattern[bytes]`, `Match[str]` или `Match[bytes]`.776777#### `class typing.NamedTuple`778779Типизированная версия [`collections.namedtuple()`](https://python-all.ru/3.7/library/collections.html#collections.namedtuple).780781Использование:782783```python784class Employee(NamedTuple):785    name: str786    id: int787```788789Это эквивалентно:790791```python792Employee = collections.namedtuple('Employee', ['name', 'id'])793```794795Чтобы задать полю значение по умолчанию, можно присвоить его в теле класса:796797```python798class Employee(NamedTuple):799    name: str800    id: int = 3801802employee = Employee('Guido')803assert employee.id == 3804```805806Поля со значением по умолчанию должны следовать после полей без значения по умолчанию.807808Полученный класс имеет два дополнительных атрибута: `_field_types`, содержащий словарь, сопоставляющий имена полей с типами, и `_field_defaults`, словарь, сопоставляющий имена полей со значениями по умолчанию. (Имена полей находятся в атрибуте `_fields`, который является частью API именованных кортежей.)809810Подклассы `NamedTuple` также могут иметь докстринги и методы:811812```python813class Employee(NamedTuple):814    """Представляет сотрудника."""815    name: str816    id: int = 3817818    def __repr__(self) -> str:819        return f'<Employee {self.name}, id={self.id}>'820```821822Обратно совместимое использование:823824```python825Employee = NamedTuple('Employee', [('name', str), ('id', int)])826```827828Изменено в версии 3.6: Добавлена поддержка синтаксиса аннотации переменных [**PEP 526**](https://python-all.ru/3.7/library/typing.html).829830Изменено в версии 3.6.1: Добавлена поддержка значений по умолчанию, методов и строк документации.831832#### `class typing.ForwardRef`833834Класс, используемый для внутреннего представления типов строковых прямых ссылок. Например, `List["SomeClass"]` неявно преобразуется в `List[ForwardRef("SomeClass")]`. Этот класс не должен создаваться пользователем, но может использоваться инструментами интроспекции.835836#### `typing.NewType(typ)`837838Вспомогательная функция для указания статическому анализатору, что тип является отдельным; см. [NewType](https://python-all.ru/3.7/library/typing.html#distinct). Во время выполнения возвращает функцию, которая возвращает свой аргумент. Использование:839840```python841UserId = NewType('UserId', int)842first_user = UserId(1)843```844845Новое в версии 3.5.2.846847#### `typing.cast(typ, val)`848849Приводит значение к типу.850851Это возвращает значение без изменений. Для проверщика типов это сигнализирует, что возвращаемое значение имеет указанный тип, но во время выполнения мы намеренно ничего не проверяем (мы хотим, чтобы это было как можно быстрее).852853#### `typing.get_type_hints(obj[, globals[, locals]])`854855Возвращает словарь, содержащий аннотации типов для функции, метода, модуля или объекта класса.856857Это часто совпадает с `obj.__annotations__`. Кроме того, прямые ссылки, закодированные как строковые литералы, обрабатываются путём вычисления их в пространствах имён `globals` и `locals`. При необходимости `Optional[t]` добавляется для аннотаций функций и методов, если задано значение по умолчанию, равное `None`. Для класса `C` возвращается словарь, построенный объединением всех `__annotations__` по `C.__mro__` в обратном порядке.858859#### `@typing.overload`860861Декоратор `@overload` позволяет описывать функции и методы, поддерживающие несколько различных комбинаций типов аргументов. За серией определений, декорированных `@overload`, должно следовать ровно одно определение без `@overload` (для той же функции/метода). Определения с `@overload` предназначены только для проверки типов, так как они будут перезаписаны определением без `@overload`, которое используется во время выполнения, но должно игнорироваться проверщиком типов. Во время выполнения прямой вызов функции, декорированной `@overload`, вызовет [`NotImplementedError`](https://python-all.ru/3.7/library/exceptions.html#NotImplementedError). Пример перегрузки, дающей более точный тип, чем можно выразить с помощью объединения или переменной типа:862863```python864@overload865def process(response: None) -> None:866    ...867@overload868def process(response: int) -> Tuple[int, str]:869    ...870@overload871def process(response: bytes) -> str:872    ...873def process(response):874    <actual implementation>875```876877См. [**PEP 484**](https://python-all.ru/3.7/library/typing.html) для подробностей и сравнения с другими семантиками типизации.878879#### `@typing.no_type_check`880881Декоратор, указывающий, что аннотации не являются подсказками типов.882883Это работает как декоратор класса или функции [декоратор](https://python-all.ru/3.7/glossary.html#term-decorator). В случае класса он рекурсивно применяется ко всем методам, определённым в этом классе (но не к методам, определённым в его суперклассах или подклассах).884885Это изменяет функцию(и) на месте.886887#### `@typing.no_type_check_decorator`888889Декоратор, придающий другому декоратору эффект [`no_type_check()`](https://python-all.ru/3.7/library/typing.html#typing.no_type_check).890891Он оборачивает декоратор чем-то, что оборачивает декорированную функцию в [`no_type_check()`](https://python-all.ru/3.7/library/typing.html#typing.no_type_check).892893#### `@typing.type_check_only`894895Декоратор, помечающий класс или функцию как недоступные во время выполнения.896897Сам этот декоратор недоступен во время выполнения. Он в основном предназначен для пометки классов, определённых в файлах заглушек типов (type stub), если реализация возвращает экземпляр закрытого класса:898899```python900@type_check_only901class Response:  # приватный или недоступный во время выполнения902    code: int903    def get_header(self, name: str) -> str: ...904905def fetch_response() -> Response: ...906```907908Обратите внимание, что возврат экземпляров закрытых классов не рекомендуется. Обычно предпочтительнее делать такие классы открытыми.909910#### `typing.Any`911912Специальный тип, указывающий на неограниченный тип.913914- Каждый тип совместим с [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any).915- [`Any`](https://python-all.ru/3.7/library/typing.html#typing.Any) совместим с каждым типом.916917#### `typing.NoReturn`918919Специальный тип, указывающий, что функция никогда не возвращает значение. Например:920921```python922from typing import NoReturn923924def stop() -> NoReturn:925    raise RuntimeError('no way')926```927928Новое в версии 3.5.4.929930Новое в версии 3.6.2.931932#### `typing.Union`933934Тип объединения; `Union[X, Y]` означает либо X, либо Y.935936Чтобы определить объединение, используйте, например, `Union[int, str]`. Подробности:937938- Аргументы должны быть типами, и их должно быть как минимум один.939- Объединения объединений разворачиваются, например:940941  ```python942  Union[Union[int, str], float] == Union[int, str, float]943  ```944- Объединения из одного аргумента исчезают, например:945946  ```python947  Union[int] == int  # Конструктор на самом деле возвращает int948  ```949- Повторяющиеся аргументы пропускаются, например:950951  ```python952  Union[int, str, int] == Union[int, str]953  ```954- При сравнении объединений порядок аргументов игнорируется, например:955956  ```python957  Union[int, str] == Union[str, int]958  ```959- Нельзя создавать подкласс или экземпляр объединения.960- Нельзя записать `Union[X][Y]`.961- Можно использовать `Optional[X]` как сокращение для `Union[X, None]`.962963Изменено в версии 3.7: Явные подклассы не удаляются из объединений во время выполнения.964965#### `typing.Optional`966967Тип Optional.968969`Optional[X]` эквивалентно `Union[X, None]`.970971Обратите внимание, что это не то же самое, что необязательный аргумент, который имеет значение по умолчанию. Необязательный аргумент с значением по умолчанию не требует квалификатора `Optional` в своей аннотации типа только потому, что он необязателен. Например:972973```python974def foo(arg: int = 0) -> None:975    ...976```977978С другой стороны, если явное значение `None` допускается, то использование `Optional` уместно, независимо от того, является ли аргумент необязательным или нет. Например:979980```python981def foo(arg: Optional[int] = None) -> None:982    ...983```984985#### `typing.Tuple`986987Тип кортежа; `Tuple[X, Y]` – это тип кортежа из двух элементов, где первый элемент имеет тип X, а второй – Y. Тип пустого кортежа может быть записан как `Tuple[()]`.988989Пример: `Tuple[T1, T2]` – это кортеж из двух элементов, соответствующих переменным типа T1 и T2. `Tuple[int, float, str]` – это кортеж из int, float и строки.990991Чтобы задать кортеж переменной длины из однотипных элементов, используйте литеральное многоточие, например `Tuple[int, ...]`. Простой [`Tuple`](https://python-all.ru/3.7/library/typing.html#typing.Tuple) эквивалентен `Tuple[Any, ...]`, а тот, в свою очередь, [`tuple`](https://python-all.ru/3.7/library/stdtypes.html#tuple).992993#### `typing.Callable`994995Тип Callable; `Callable[[int], str]` – это функция вида (int) -\> str.996997Синтаксис индексирования всегда должен использоваться ровно с двумя значениями: списком аргументов и типом возвращаемого значения. Список аргументов должен быть списком типов или многоточием; тип возвращаемого значения должен быть одним типом.998999Нет синтаксиса для указания необязательных или именованных аргументов; такие типы функций редко используются в качестве типов колбэков. `Callable[..., ReturnType]` (буквальное многоточие) можно использовать для аннотации вызываемого объекта, принимающего любое количество аргументов и возвращающего `ReturnType`. Обычное [`Callable`](https://python-all.ru/3.7/library/typing.html#typing.Callable) эквивалентно `Callable[..., Any]`, а в свою очередь – [`collections.abc.Callable`](https://python-all.ru/3.7/library/collections.abc.html#collections.abc.Callable).10001001#### `typing.ClassVar`10021003Специальная конструкция типа для пометки переменных класса.10041005Как представлено в [**PEP 526**](https://python-all.ru/3.7/library/typing.html), аннотация переменной, обёрнутая в ClassVar, указывает, что данный атрибут предназначен для использования в качестве переменной класса и не должен устанавливаться на экземплярах этого класса. Использование:10061007```python1008class Starship:1009    stats: ClassVar[Dict[str, int]] = {} # переменная класса1010    damage: int = 10                     # переменная экземпляра1011```10121013[`ClassVar`](https://python-all.ru/3.7/library/typing.html#typing.ClassVar) принимает только типы и не может быть дополнительно индексирован.10141015[`ClassVar`](https://python-all.ru/3.7/library/typing.html#typing.ClassVar) сам по себе не является классом и не должен использоваться с [`isinstance()`](https://python-all.ru/3.7/library/functions.html#isinstance) или [`issubclass()`](https://python-all.ru/3.7/library/functions.html#issubclass). [`ClassVar`](https://python-all.ru/3.7/library/typing.html#typing.ClassVar) не меняет поведение Python во время выполнения, но может использоваться сторонними проверяющими типов. Например, проверяющий типов может отметить следующий код как ошибочный:10161017```python1018enterprise_d = Starship(3000)1019enterprise_d.stats = {} # Ошибка: установка переменной класса на экземпляре1020Starship.stats = {}     # Это корректно.1021```10221023Новое в версии 3.5.3.10241025#### `typing.AnyStr`10261027`AnyStr` – это переменная типа, определённая как `AnyStr = TypeVar('AnyStr', str, bytes)`.10281029Предназначен для функций, которые могут принимать строки любого типа, не допуская смешивания разных типов строк. Например:10301031```python1032def concat(a: AnyStr, b: AnyStr) -> AnyStr:1033    return a + b10341035concat(u"foo", u"bar")  # Ок, результат имеет тип 'unicode'1036concat(b"foo", b"bar")  # Ок, результат имеет тип 'bytes'1037concat(u"foo", b"bar")  # Ошибка, нельзя смешивать unicode и bytes1038```10391040#### `typing.TYPE_CHECKING`10411042Специальная константа, которая считается `True` сторонними статическими проверщиками типов. Во время выполнения она равна `False`. Применение:10431044```python1045if TYPE_CHECKING:1046    import expensive_mod10471048def fun(arg: 'expensive_mod.SomeType') -> None:1049    local_var: expensive_mod.AnotherType = other_fun()1050```10511052Обратите внимание, что первая аннотация типа должна быть заключена в кавычки, что делает её «отложенной ссылкой» (forward reference), чтобы скрыть ссылку `expensive_mod` от интерпретатора во время выполнения. Аннотации типов для локальных переменных не вычисляются, поэтому вторую аннотацию заключать в кавычки не нужно.10531054Новое в версии 3.5.2.1055