`typing.md`

1002 строк · 55.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.6/library/typing.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 26.1. [`typing`](https://python-all.ru/3.6/library/typing.html#module-typing) – Поддержка подсказок типов89Новое в версии 3.5.1011**Исходный код:** [Lib/typing.py](https://python-all.ru/src/3.6/Lib/typing.py)1213> **Примечание**14>15> Модуль typing был включён в стандартную библиотеку на [временной основе](https://python-all.ru/3.6/glossary.html#term-provisional-api). Новые возможности могут быть добавлены, а API может изменяться даже между минорными релизами, если основные разработчики сочтут это необходимым.1617---1819Этот модуль поддерживает аннотации типов, определённые в [**PEP 484**](https://python-all.ru/3.6/library/typing.html) и [**PEP 526**](https://python-all.ru/3.6/library/typing.html). Самая базовая поддержка состоит из типов [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any), [`Union`](https://python-all.ru/3.6/library/typing.html#typing.Union), [`Tuple`](https://python-all.ru/3.6/library/typing.html#typing.Tuple), [`Callable`](https://python-all.ru/3.6/library/typing.html#typing.Callable), [`TypeVar`](https://python-all.ru/3.6/library/typing.html#typing.TypeVar) и [`Generic`](https://python-all.ru/3.6/library/typing.html#typing.Generic). Полную спецификацию см. в [**PEP 484**](https://python-all.ru/3.6/library/typing.html). Упрощённое введение в аннотации типов – в [**PEP 483**](https://python-all.ru/3.6/library/typing.html).2021Функция ниже принимает и возвращает строку и аннотирована следующим образом:2223```python24def greeting(name: str) -> str:25    return 'Hello ' + name26```2728В функции `greeting` аргумент `name` ожидается типа [`str`](https://python-all.ru/3.6/library/stdtypes.html#str), а возвращаемый тип – [`str`](https://python-all.ru/3.6/library/stdtypes.html#str). Подтипы допускаются в качестве аргументов.2930## 26.1.1. Псевдонимы типов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, List4950ConnectionOptions = Dict[str, str]51Address = Tuple[str, int]52Server = Tuple[Address, ConnectionOptions]5354def broadcast_message(message: str, servers: List[Server]) -> None:55    ...5657# Статическая проверка типов будет считать предыдущую сигнатуру типа как58# полностью эквивалентную этой.59def broadcast_message(60        message: str,61        servers: List[Tuple[Tuple[str, int], Dict[str, str]]]) -> None:62    ...63```6465Обратите внимание, что `None` как аннотация типа является особым случаем и заменяется на `type(None)`.6667## 26.1.2. NewType6869Для создания отдельных типов используется вспомогательная функция [`NewType()`](https://python-all.ru/3.6/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.6/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.6/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## 26.1.3. 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## 26.1.4. Дженерики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.6/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## 26.1.5. Пользовательские обобщённые типы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.6/library/typing.html#typing.Generic) использует метакласс, который определяет [`__getitem__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__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.6/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.6/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.6/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Метакласс, используемый [`Generic`](https://python-all.ru/3.6/library/typing.html#typing.Generic), является подклассом [`abc.ABCMeta`](https://python-all.ru/3.6/library/abc.html#abc.ABCMeta). Обобщённый класс может быть ABC, если содержит абстрактные методы или свойства, и обобщённые классы также могут иметь ABC в качестве базовых классов без конфликта метаклассов. Обобщённые метаклассы не поддерживаются. Результат параметризации дженериков кэшируется, а большинство типов в модуле typing являются хэшируемыми и сравнимыми на равенство.292293## 26.1.6. Тип [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any)294295Особым видом типа является [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any). Статический проверяющий типов будет считать каждый тип совместимым с [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any), а [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any) – совместимым с каждым типом.296297Это означает, что над значением типа [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any) можно выполнять любые операции или вызовы методов и присваивать его любой переменной:298299```python300from typing import Any301302a = None    # type: Any303a = []      # ОК304a = 2       # ОК305306s = ''      # type: str307s = a       # ОК308309def foo(item: Any) -> int:310    # Проходит проверку типов; 'item' может быть любого типа,311    # и этот тип может иметь метод 'bar'312    item.bar()313    ...314```315316Обратите внимание, что никакая проверка типов не выполняется при присваивании значения типа [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any) более точному типу. Например, статический проверяющий типы не сообщил об ошибке при присваивании `a` переменной `s`, хотя `s` был объявлен как тип [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) и получает значение [`int`](https://python-all.ru/3.6/library/functions.html#int) во время выполнения!317318Кроме того, все функции без указания типа возврата или типов параметров по умолчанию неявно используют [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any):319320```python321def legacy_parser(text):322    ...323    return data324325# Статический проверщик типов будет рассматривать вышеприведенное326# как имеющее ту же сигнатуру, что и:327def legacy_parser(text: Any) -> Any:328    ...329    return data330```331332Такое поведение позволяет использовать [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any) в качестве *запасного выхода*, когда нужно смешивать динамически и статически типизированный код.333334Сравните поведение [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any) с поведением [`object`](https://python-all.ru/3.6/library/functions.html#object). Как и [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any), каждый тип является подтипом [`object`](https://python-all.ru/3.6/library/functions.html#object). Однако, в отличие от [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any), обратное неверно: [`object`](https://python-all.ru/3.6/library/functions.html#object) *не* является подтипом любого другого типа.335336Это означает, что когда тип значения – [`object`](https://python-all.ru/3.6/library/functions.html#object), проверяющий типы будет отклонять почти все операции над ним, а присваивание его переменной (или использование в качестве возвращаемого значения) более специализированного типа является ошибкой типа. Например:337338```python339def hash_a(item: object) -> int:340    # Завершается ошибкой; у объекта нет метода 'magic'.341    item.magic()342    ...343344def hash_b(item: Any) -> int:345    # Проходит проверку типов.346    item.magic()347    ...348349# Проходит проверку типов, так как int и str являются подклассами object.350hash_a(42)351hash_a("foo")352353# Проходит проверку типов, так как Any совместим со всеми типами.354hash_b(42)355hash_b("foo")356```357358Используйте [`object`](https://python-all.ru/3.6/library/functions.html#object), чтобы указать, что значение может быть любого типа в типобезопасной манере. Используйте [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any), чтобы указать, что значение динамически типизировано.359360## 26.1.7. Классы, функции и декораторы361362Модуль определяет следующие классы, функции и декораторы:363364#### `class typing.TypeVar`365366Переменная типа.367368Использование:369370```python371T = TypeVar('T')  # Может быть чем угодно372A = TypeVar('A', str, bytes)  # Должно быть str или bytes373```374375Переменные типа существуют в первую очередь для статических анализаторов типов. Они служат параметрами для обобщённых типов, а также для определений обобщённых функций. См. класс Generic для получения дополнительной информации об обобщённых типах. Обобщённые функции работают следующим образом:376377```python378def repeat(x: T, n: int) -> Sequence[T]:379    """Возвращает список, содержащий n ссылок на x."""380    return [x]*n381382def longest(x: A, y: A) -> A:383    """Возвращает самую длинную из двух строк."""384    return x if len(x) >= len(y) else y385```386387Сигнатура последнего примера по сути является перегрузкой `(str, str) -> str` и `(bytes, bytes) -> bytes`. Также обратите внимание, что если аргументы являются экземплярами какого-либо подкласса [`str`](https://python-all.ru/3.6/library/stdtypes.html#str), возвращаемый тип остаётся простым [`str`](https://python-all.ru/3.6/library/stdtypes.html#str).388389Во время выполнения `isinstance(x, T)` вызовет [`TypeError`](https://python-all.ru/3.6/library/exceptions.html#TypeError). В общем, [`isinstance()`](https://python-all.ru/3.6/library/functions.html#isinstance) и [`issubclass()`](https://python-all.ru/3.6/library/functions.html#issubclass) не должны использоваться с типами.390391Переменные типа могут быть помечены как ковариантные или контравариантные путём передачи `covariant=True` или `contravariant=True`. См. [**PEP 484**](https://python-all.ru/3.6/library/typing.html) для подробностей. По умолчанию переменные типа инвариантны. В качестве альтернативы, переменная типа может указывать верхнюю границу с помощью `bound=<type>`. Это означает, что фактический тип, подставленный (явно или неявно) для переменной типа, должен быть подклассом граничного типа, см. [**PEP 484**](https://python-all.ru/3.6/library/typing.html).392393#### `class typing.Generic`394395Абстрактный базовый класс для обобщённых типов.396397Обобщённый тип обычно объявляется наследованием от экземпляра этого класса с одной или несколькими переменными типа. Например, обобщённый тип отображения может быть определён так:398399```python400class Mapping(Generic[KT, VT]):401    def __getitem__(self, key: KT) -> VT:402        ...403        # И т.д.404```405406Затем этот класс можно использовать следующим образом:407408```python409X = TypeVar('X')410Y = TypeVar('Y')411412def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:413    try:414        return mapping[key]415    except KeyError:416        return default417```418419#### `class typing.Type(Generic[CT_co])`420421Переменная, аннотированная `C`, может принимать значение типа `C`. Напротив, переменная, аннотированная `Type[C]`, может принимать значения, которые сами являются классами – а именно, она принимает *объект класса* `C`. Например:422423```python424a = 3         # Имеет тип 'int'425b = int       # Имеет тип 'Type[int]'426c = type(a)   # Также имеет тип 'Type[int]'427```428429Обратите внимание, что `Type[C]` ковариантен:430431```python432class User: ...433class BasicUser(User): ...434class ProUser(User): ...435class TeamUser(User): ...436437# Принимает User, BasicUser, ProUser, TeamUser, ...438def make_new_user(user_class: Type[User]) -> User:439    # ...440    return user_class()441```442443Тот факт, что `Type[C]` ковариантен, подразумевает, что все подклассы `C` должны реализовывать те же сигнатуры конструктора и методов класса, что и `C`. Средство проверки типов должно отмечать нарушения этого, но также должно разрешать вызовы конструкторов в подклассах, которые соответствуют вызовам конструктора в указанном базовом классе. То, как средство проверки типов должно обрабатывать этот конкретный случай, может измениться в будущих версиях [**PEP 484**](https://python-all.ru/3.6/library/typing.html).444445Единственными допустимыми параметрами для [`Type`](https://python-all.ru/3.6/library/typing.html#typing.Type) являются классы, [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any), [переменные типа](https://python-all.ru/3.6/library/typing.html#generics) и объединения любых из этих типов. Например:446447```python448def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...449```450451`Type[Any]` эквивалентен `Type`, который в свою очередь эквивалентен `type`, корню метаклассовой иерархии Python.452453Новое в версии 3.5.2.454455#### `class typing.Iterable(Generic[T_co])`456457Обобщённая версия [`collections.abc.Iterable`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Iterable).458459#### `class typing.Iterator(Iterable[T_co])`460461Обобщённая версия [`collections.abc.Iterator`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Iterator).462463#### `class typing.Reversible(Iterable[T_co])`464465Обобщённая версия [`collections.abc.Reversible`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Reversible).466467#### `class typing.SupportsInt`468469ABC с одним абстрактным методом `__int__`.470471#### `class typing.SupportsFloat`472473ABC с одним абстрактным методом `__float__`.474475#### `class typing.SupportsComplex`476477ABC с одним абстрактным методом `__complex__`.478479#### `class typing.SupportsBytes`480481ABC с одним абстрактным методом `__bytes__`.482483#### `class typing.SupportsAbs`484485ABC с одним абстрактным методом `__abs__`, ковариантным по типу возвращаемого значения.486487#### `class typing.SupportsRound`488489ABC с одним абстрактным методом `__round__` ковариантным по возвращаемому типу.490491#### `class typing.Container(Generic[T_co])`492493Обобщённая версия [`collections.abc.Container`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Container).494495#### `class typing.Hashable`496497Псевдоним для [`collections.abc.Hashable`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Hashable)498499#### `class typing.Sized`500501Псевдоним для [`collections.abc.Sized`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Sized)502503#### `class typing.Collection(Sized, Iterable[T_co], Container[T_co])`504505Обобщённая версия [`collections.abc.Collection`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Collection)506507Новое в версии 3.6.508509#### `class typing.AbstractSet(Sized, Collection[T_co])`510511Обобщённая версия [`collections.abc.Set`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Set).512513#### `class typing.MutableSet(AbstractSet[T])`514515Обобщённая версия [`collections.abc.MutableSet`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.MutableSet).516517#### `class typing.Mapping(Sized, Collection[KT], Generic[VT_co])`518519Обобщённая версия [`collections.abc.Mapping`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Mapping).520521#### `class typing.MutableMapping(Mapping[KT, VT])`522523Обобщённая версия [`collections.abc.MutableMapping`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.MutableMapping).524525#### `class typing.Sequence(Reversible[T_co], Collection[T_co])`526527Обобщённая версия [`collections.abc.Sequence`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Sequence).528529#### `class typing.MutableSequence(Sequence[T])`530531Обобщённая версия [`collections.abc.MutableSequence`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.MutableSequence).532533#### `class typing.ByteString(Sequence[int])`534535Обобщённая версия [`collections.abc.ByteString`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.ByteString).536537Этот тип представляет типы [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.6/library/stdtypes.html#bytearray) и [`memoryview`](https://python-all.ru/3.6/library/stdtypes.html#memoryview).538539В качестве сокращения для этого типа [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) можно использовать для аннотации аргументов любого из упомянутых выше типов.540541#### `class typing.Deque(deque, MutableSequence[T])`542543Обобщённая версия [`collections.deque`](https://python-all.ru/3.6/library/collections.html#collections.deque).544545Новое в версии 3.6.1.546547#### `class typing.List(list, MutableSequence[T])`548549Обобщённая версия [`list`](https://python-all.ru/3.6/library/stdtypes.html#list). Полезна для аннотации возвращаемых типов. Для аннотации аргументов предпочтительнее использовать абстрактные типы коллекций, такие как [`Mapping`](https://python-all.ru/3.6/library/typing.html#typing.Mapping), [`Sequence`](https://python-all.ru/3.6/library/typing.html#typing.Sequence) или [`AbstractSet`](https://python-all.ru/3.6/library/typing.html#typing.AbstractSet).550551Этот тип можно использовать следующим образом:552553```python554T = TypeVar('T', int, float)555556def vec2(x: T, y: T) -> List[T]:557    return [x, y]558559def keep_positives(vector: Sequence[T]) -> List[T]:560    return [item for item in vector if item > 0]561```562563#### `class typing.Set(set, MutableSet[T])`564565Обобщённая версия [`builtins.set`](https://python-all.ru/3.6/library/stdtypes.html#set).566567#### `class typing.FrozenSet(frozenset, AbstractSet[T_co])`568569Обобщённая версия [`builtins.frozenset`](https://python-all.ru/3.6/library/stdtypes.html#frozenset).570571#### `class typing.MappingView(Sized, Iterable[T_co])`572573Обобщённая версия [`collections.abc.MappingView`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.MappingView).574575#### `class typing.KeysView(MappingView[KT_co], AbstractSet[KT_co])`576577Обобщённая версия [`collections.abc.KeysView`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.KeysView).578579#### `class typing.ItemsView(MappingView, Generic[KT_co, VT_co])`580581Обобщённая версия [`collections.abc.ItemsView`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.ItemsView).582583#### `class typing.ValuesView(MappingView[VT_co])`584585Обобщённая версия [`collections.abc.ValuesView`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.ValuesView).586587#### `class typing.Awaitable(Generic[T_co])`588589Обобщённая версия [`collections.abc.Awaitable`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Awaitable).590591#### `class typing.Coroutine(Awaitable[V_co], Generic[T_co T_contra, V_co])`592593Обобщённая версия [`collections.abc.Coroutine`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Coroutine). Вариантность и порядок переменных типа соответствуют таковым у [`Generator`](https://python-all.ru/3.6/library/typing.html#typing.Generator), например:594595```python596from typing import List, Coroutine597c = None # type: Coroutine[List[str], str, int]598...599x = c.send('hi') # type: List[str]600async def bar() -> None:601    x = await c # type: int602```603604#### `class typing.AsyncIterable(Generic[T_co])`605606Обобщённая версия [`collections.abc.AsyncIterable`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.AsyncIterable).607608#### `class typing.AsyncIterator(AsyncIterable[T_co])`609610Обобщённая версия [`collections.abc.AsyncIterator`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.AsyncIterator).611612#### `class typing.ContextManager(Generic[T_co])`613614Обобщённая версия [`contextlib.AbstractContextManager`](https://python-all.ru/3.6/library/contextlib.html#contextlib.AbstractContextManager).615616Новое в версии 3.6.617618#### `class typing.AsyncContextManager(Generic[T_co])`619620ABC с асинхронными абстрактными методами [`__aenter__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__aenter__) и [`__aexit__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__aexit__).621622Новое в версии 3.6.623624#### `class typing.Dict(dict, MutableMapping[KT, VT])`625626Обобщённая версия [`dict`](https://python-all.ru/3.6/library/stdtypes.html#dict). Использование этого типа выглядит следующим образом:627628```python629def get_position_in_index(word_list: Dict[str, int], word: str) -> int:630    return word_list[word]631```632633#### `class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])`634635Обобщённая версия [`collections.defaultdict`](https://python-all.ru/3.6/library/collections.html#collections.defaultdict).636637Новое в версии 3.5.2.638639#### `class typing.Counter(collections.Counter, Dict[T, int])`640641Обобщённая версия [`collections.Counter`](https://python-all.ru/3.6/library/collections.html#collections.Counter).642643Новое в версии 3.6.1.644645#### `class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])`646647Обобщённая версия [`collections.ChainMap`](https://python-all.ru/3.6/library/collections.html#collections.ChainMap).648649Новое в версии 3.6.1.650651#### `class typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])`652653Генератор можно аннотировать обобщённым типом `Generator[YieldType, SendType, ReturnType]`. Например:654655```python656def echo_round() -> Generator[int, float, str]:657    sent = yield 0658    while sent >= 0:659        sent = yield round(sent)660    return 'Done'661```662663Обратите внимание: в отличие от многих других обобщённых типов в модуле typing, `SendType` из [`Generator`](https://python-all.ru/3.6/library/typing.html#typing.Generator) ведёт себя контравариантно, а не ковариантно или инвариантно.664665Если ваш генератор будет только выдавать значения, установите `SendType` и `ReturnType` в `None`:666667```python668def infinite_stream(start: int) -> Generator[int, None, None]:669    while True:670        yield start671        start += 1672```673674В качестве альтернативы аннотируйте генератор как имеющий тип возвращаемого значения либо `Iterable[YieldType]`, либо `Iterator[YieldType]`:675676```python677def infinite_stream(start: int) -> Iterator[int]:678    while True:679        yield start680        start += 1681```682683#### `class typing.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])`684685Асинхронный генератор можно аннотировать обобщённым типом `AsyncGenerator[YieldType, SendType]`. Например:686687```python688async def echo_round() -> AsyncGenerator[int, float]:689    sent = yield 0690    while sent >= 0.0:691        rounded = await round(sent)692        sent = yield rounded693```694695В отличие от обычных генераторов, асинхронные генераторы не могут возвращать значение, поэтому параметр типа `ReturnType` отсутствует. Как и в случае с [`Generator`](https://python-all.ru/3.6/library/typing.html#typing.Generator), `SendType` ведёт себя контравариантно.696697Если генератор только выдаёт значения, установите `SendType` в `None`:698699```python700async def infinite_stream(start: int) -> AsyncGenerator[int, None]:701    while True:702        yield start703        start = await increment(start)704```705706В качестве альтернативы аннотируйте генератор как имеющий тип возвращаемого значения либо `AsyncIterable[YieldType]`, либо `AsyncIterator[YieldType]`:707708```python709async def infinite_stream(start: int) -> AsyncIterator[int]:710    while True:711        yield start712        start = await increment(start)713```714715Новое в версии 3.5.4.716717#### `class typing.Text`718719`Text` – это псевдоним для `str`. Он предоставляется для обеспечения совместимости с кодом Python 2: в Python 2 `Text` является псевдонимом для `unicode`.720721Используйте `Text`, чтобы указать, что значение должно содержать строку Unicode, совместимую как с Python 2, так и с Python 3:722723```python724def add_unicode_checkmark(text: Text) -> Text:725    return text + u' \u2713'726```727728Новое в версии 3.5.2.729730#### `class typing.IO`731732#### `class typing.TextIO`733734#### `class typing.BinaryIO`735736Обобщённый тип `IO[AnyStr]` и его подклассы `TextIO(IO[str])` и `BinaryIO(IO[bytes])` представляют типы потоков ввода-вывода, такие как возвращаемые [`open()`](https://python-all.ru/3.6/library/functions.html#open).737738#### `class typing.Pattern`739740#### `class typing.Match`741742Эти псевдонимы типов соответствуют возвращаемым типам из [`re.compile()`](https://python-all.ru/3.6/library/re.html#re.compile) и [`re.match()`](https://python-all.ru/3.6/library/re.html#re.match). Эти типы (и соответствующие функции) являются обобщёнными по `AnyStr` и могут быть конкретизированы записью `Pattern[str]`, `Pattern[bytes]`, `Match[str]` или `Match[bytes]`.743744#### `class typing.NamedTuple`745746Типизированная версия namedtuple.747748Использование:749750```python751class Employee(NamedTuple):752    name: str753    id: int754```755756Это эквивалентно:757758```python759Employee = collections.namedtuple('Employee', ['name', 'id'])760```761762Чтобы задать полю значение по умолчанию, можно присвоить его в теле класса:763764```python765class Employee(NamedTuple):766    name: str767    id: int = 3768769employee = Employee('Guido')770assert employee.id == 3771```772773Поля со значением по умолчанию должны следовать после полей без значения по умолчанию.774775Полученный класс имеет два дополнительных атрибута: `_field_types`, содержащий словарь, сопоставляющий имена полей с типами, и `_field_defaults`, словарь, сопоставляющий имена полей со значениями по умолчанию. (Имена полей находятся в атрибуте `_fields`, который является частью API именованных кортежей.)776777Подклассы `NamedTuple` также могут иметь докстринги и методы:778779```python780class Employee(NamedTuple):781    """Представляет сотрудника."""782    name: str783    id: int = 3784785    def __repr__(self) -> str:786        return f'<Employee {self.name}, id={self.id}>'787```788789Обратно совместимое использование:790791```python792Employee = NamedTuple('Employee', [('name', str), ('id', int)])793```794795Изменено в версии 3.6: Добавлена поддержка синтаксиса аннотации переменных [**PEP 526**](https://python-all.ru/3.6/library/typing.html).796797Изменено в версии 3.6.1: Добавлена поддержка значений по умолчанию, методов и строк документации.798799#### `typing.NewType(typ)`800801Вспомогательная функция для указания статическому анализатору, что тип является отдельным; см. [NewType](https://python-all.ru/3.6/library/typing.html#distinct). Во время выполнения возвращает функцию, которая возвращает свой аргумент. Использование:802803```python804UserId = NewType('UserId', int)805first_user = UserId(1)806```807808Новое в версии 3.5.2.809810#### `typing.cast(typ, val)`811812Приводит значение к типу.813814Это возвращает значение без изменений. Для проверщика типов это сигнализирует, что возвращаемое значение имеет указанный тип, но во время выполнения мы намеренно ничего не проверяем (мы хотим, чтобы это было как можно быстрее).815816#### `typing.get_type_hints(obj[, globals[, locals]])`817818Возвращает словарь, содержащий аннотации типов для функции, метода, модуля или объекта класса.819820Это часто совпадает с `obj.__annotations__`. Кроме того, прямые ссылки, закодированные как строковые литералы, обрабатываются путём вычисления их в пространствах имён `globals` и `locals`. При необходимости `Optional[t]` добавляется для аннотаций функций и методов, если задано значение по умолчанию, равное `None`. Для класса `C` возвращается словарь, построенный объединением всех `__annotations__` по `C.__mro__` в обратном порядке.821822#### `@typing.overload`823824Декоратор `@overload` позволяет описывать функции и методы, поддерживающие несколько различных комбинаций типов аргументов. За серией определений, декорированных `@overload`, должно следовать ровно одно определение без `@overload` (для той же функции/метода). Определения с `@overload` предназначены только для проверки типов, так как они будут перезаписаны определением без `@overload`, которое используется во время выполнения, но должно игнорироваться проверщиком типов. Во время выполнения прямой вызов функции, декорированной `@overload`, вызовет `NotImplementedError`. Пример перегрузки, дающей более точный тип, чем можно выразить с помощью объединения или переменной типа:825826```python827@overload828def process(response: None) -> None:829    ...830@overload831def process(response: int) -> Tuple[int, str]:832    ...833@overload834def process(response: bytes) -> str:835    ...836def process(response):837    <actual implementation>838```839840См. [**PEP 484**](https://python-all.ru/3.6/library/typing.html) для подробностей и сравнения с другими семантиками типизации.841842#### `@typing.no_type_check`843844Декоратор, указывающий, что аннотации не являются подсказками типов.845846Это работает как декоратор класса или функции [декоратор](https://python-all.ru/3.6/glossary.html#term-decorator). В случае класса он рекурсивно применяется ко всем методам, определённым в этом классе (но не к методам, определённым в его суперклассах или подклассах).847848Это изменяет функцию(и) на месте.849850#### `@typing.no_type_check_decorator`851852Декоратор, придающий другому декоратору эффект [`no_type_check()`](https://python-all.ru/3.6/library/typing.html#typing.no_type_check).853854Он оборачивает декоратор чем-то, что оборачивает декорированную функцию в [`no_type_check()`](https://python-all.ru/3.6/library/typing.html#typing.no_type_check).855856#### `typing.Any`857858Специальный тип, указывающий на неограниченный тип.859860- Каждый тип совместим с [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any).861- [`Any`](https://python-all.ru/3.6/library/typing.html#typing.Any) совместим с каждым типом.862863#### `typing.NoReturn`864865Специальный тип, указывающий, что функция никогда не возвращает значение. Например:866867```python868from typing import NoReturn869870def stop() -> NoReturn:871    raise RuntimeError('no way')872```873874Новое в версии 3.6.5.875876#### `typing.Union`877878Тип объединения; `Union[X, Y]` означает либо X, либо Y.879880Чтобы определить объединение, используйте, например, `Union[int, str]`. Подробности:881882- Аргументы должны быть типами, и их должно быть как минимум один.883- Объединения объединений разворачиваются, например:884885  ```python886  Union[Union[int, str], float] == Union[int, str, float]887  ```888- Объединения из одного аргумента исчезают, например:889890  ```python891  Union[int] == int  # Конструктор на самом деле возвращает int892  ```893- Повторяющиеся аргументы пропускаются, например:894895  ```python896  Union[int, str, int] == Union[int, str]897  ```898- При сравнении объединений порядок аргументов игнорируется, например:899900  ```python901  Union[int, str] == Union[str, int]902  ```903- Когда присутствуют класс и его подкласс, последний пропускается, например:904905  ```python906  Union[int, object] == object907  ```908- Нельзя создавать подкласс или экземпляр объединения.909- Нельзя записать `Union[X][Y]`.910- Можно использовать `Optional[X]` как сокращение для `Union[X, None]`.911912#### `typing.Optional`913914Тип Optional.915916`Optional[X]` эквивалентно `Union[X, None]`.917918Обратите внимание, что это не то же самое, что необязательный аргумент, который имеет значение по умолчанию. Необязательный аргумент с значением по умолчанию не требует квалификатора `Optional` в своей аннотации типа только потому, что он необязателен. Например:919920```python921def foo(arg: int = 0) -> None:922    ...923```924925С другой стороны, если явное значение `None` допускается, то использование `Optional` уместно, независимо от того, является ли аргумент необязательным или нет. Например:926927```python928def foo(arg: Optional[int] = None) -> None:929    ...930```931932#### `typing.Tuple`933934Тип кортежа; `Tuple[X, Y]` – это тип кортежа из двух элементов с первым элементом типа X и вторым типа Y.935936Пример: `Tuple[T1, T2]` – это кортеж из двух элементов, соответствующих переменным типа T1 и T2. `Tuple[int, float, str]` – это кортеж из int, float и строки.937938Чтобы задать кортеж переменной длины из однотипных элементов, используйте литеральное многоточие, например `Tuple[int, ...]`. Простой [`Tuple`](https://python-all.ru/3.6/library/typing.html#typing.Tuple) эквивалентен `Tuple[Any, ...]`, а тот, в свою очередь, [`tuple`](https://python-all.ru/3.6/library/stdtypes.html#tuple).939940#### `typing.Callable`941942Тип Callable; `Callable[[int], str]` – это функция вида (int) -\> str.943944Синтаксис индексирования всегда должен использоваться ровно с двумя значениями: списком аргументов и типом возвращаемого значения. Список аргументов должен быть списком типов или многоточием; тип возвращаемого значения должен быть одним типом.945946Нет синтаксиса для указания необязательных или именованных аргументов; такие типы функций редко используются в качестве типов колбэков. `Callable[..., ReturnType]` (буквальное многоточие) можно использовать для аннотации вызываемого объекта, принимающего любое количество аргументов и возвращающего `ReturnType`. Обычное [`Callable`](https://python-all.ru/3.6/library/typing.html#typing.Callable) эквивалентно `Callable[..., Any]`, а в свою очередь – [`collections.abc.Callable`](https://python-all.ru/3.6/library/collections.abc.html#collections.abc.Callable).947948#### `typing.ClassVar`949950Специальная конструкция типа для пометки переменных класса.951952Как представлено в [**PEP 526**](https://python-all.ru/3.6/library/typing.html), аннотация переменной, обёрнутая в ClassVar, указывает, что данный атрибут предназначен для использования в качестве переменной класса и не должен устанавливаться на экземплярах этого класса. Использование:953954```python955class Starship:956    stats: ClassVar[Dict[str, int]] = {} # переменная класса957    damage: int = 10                     # переменная экземпляра958```959960[`ClassVar`](https://python-all.ru/3.6/library/typing.html#typing.ClassVar) принимает только типы и не может быть дополнительно индексирован.961962[`ClassVar`](https://python-all.ru/3.6/library/typing.html#typing.ClassVar) сам по себе не является классом и не должен использоваться с [`isinstance()`](https://python-all.ru/3.6/library/functions.html#isinstance) или [`issubclass()`](https://python-all.ru/3.6/library/functions.html#issubclass). [`ClassVar`](https://python-all.ru/3.6/library/typing.html#typing.ClassVar) не меняет поведение Python во время выполнения, но может использоваться сторонними проверяющими типов. Например, проверяющий типов может отметить следующий код как ошибочный:963964```python965enterprise_d = Starship(3000)966enterprise_d.stats = {} # Ошибка: установка переменной класса на экземпляре967Starship.stats = {}     # Это корректно.968```969970Новое в версии 3.5.3.971972#### `typing.AnyStr`973974`AnyStr` – это переменная типа, определённая как `AnyStr = TypeVar('AnyStr', str, bytes)`.975976Предназначен для функций, которые могут принимать строки любого типа, не допуская смешивания разных типов строк. Например:977978```python979def concat(a: AnyStr, b: AnyStr) -> AnyStr:980    return a + b981982concat(u"foo", u"bar")  # Ок, результат имеет тип 'unicode'983concat(b"foo", b"bar")  # Ок, результат имеет тип 'bytes'984concat(u"foo", b"bar")  # Ошибка, нельзя смешивать unicode и bytes985```986987#### `typing.TYPE_CHECKING`988989Специальная константа, которая считается `True` сторонними статическими проверщиками типов. Во время выполнения она равна `False`. Применение:990991```python992if TYPE_CHECKING:993    import expensive_mod994995def fun(arg: 'expensive_mod.SomeType') -> None:996    local_var: expensive_mod.AnotherType = other_fun()997```998999Обратите внимание, что первая аннотация типа должна быть заключена в кавычки, что делает её «отложенной ссылкой» (forward reference), чтобы скрыть ссылку `expensive_mod` от интерпретатора во время выполнения. Аннотации типов для локальных переменных не вычисляются, поэтому вторую аннотацию заключать в кавычки не нужно.10001001Новое в версии 3.5.2.1002