typing – Поддержка аннотаций типов¶typing – Support for type hints

Специальные типы¶Special types

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

typing.Any¶

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

• Каждый тип совместим с Any.

• Any совместим с каждым типом.

typing.NoReturn¶

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

from typing import NoReturn

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

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

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

Специальные формы¶Special forms

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

typing.Tuple¶

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

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

Чтобы задать кортеж переменной длины из однотипных элементов, используйте литеральное многоточие, например Tuple[int, ...]. Простой Tuple эквивалентен Tuple[Any, ...], а тот, в свою очередь, tuple.

Устарело с версии 3.9: builtins.tuple теперь поддерживает []. См. PEP 585 и Обобщённый псевдоним типа.

typing.Union¶

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

Чтобы определить объединение, используйте, например, Union[int, str]. Подробности:

• Аргументы должны быть типами, и их должно быть как минимум один.

• Объединения объединений разворачиваются, например:

  Union[Union[int, str], float] == Union[int, str, float]
  

• Объединения из одного аргумента исчезают, например:

  Union[int] == int  # Конструктор на самом деле возвращает int
  

• Повторяющиеся аргументы пропускаются, например:

  Union[int, str, int] == Union[int, str]
  

• При сравнении объединений порядок аргументов игнорируется, например:

  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 в своей аннотации типа только потому, что он необязателен. Например:

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

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

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

typing.Callable¶

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

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

Нет синтаксиса для указания необязательных или именованных аргументов; такие типы функций редко используются в качестве типов колбэков. Callable[..., ReturnType] (буквальное многоточие) можно использовать для аннотации вызываемого объекта, принимающего любое количество аргументов и возвращающего ReturnType. Обычное Callable эквивалентно Callable[..., Any], а в свою очередь – collections.abc.Callable.

Устарело с версии 3.9: collections.abc.Callable теперь поддерживает []. См. PEP 585 и Обобщённый псевдоним типа.

class typing.Type(Generic[CT_co])¶

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

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

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

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.

Единственными допустимыми параметрами для Type являются классы, Any, переменные типа и объединения любых из этих типов. Например:

def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]): ...

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

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

Устарело с версии 3.9: builtins.type теперь поддерживает []. См. PEP 585 и Обобщённый псевдоним типа.

typing.Literal¶

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

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 для получения дополнительных сведений о литеральных типах.

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

Изменено в версии 3.9.1: Literal теперь дедуплицирует параметры. Сравнения на равенство объектов Literal больше не зависят от порядка. Объекты Literal теперь будут вызывать исключение TypeError при сравнении на равенство, если один из их параметров не является хешируемым.

typing.ClassVar¶

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

Как представлено в PEP 526, аннотация переменной, обёрнутая в ClassVar, указывает, что данный атрибут предназначен для использования в качестве переменной класса и не должен устанавливаться на экземплярах этого класса. Использование:

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

ClassVar принимает только типы и не может быть дополнительно индексирован.

ClassVar сам по себе не является классом и не должен использоваться с isinstance() или issubclass(). ClassVar не меняет поведение Python во время выполнения, но может использоваться сторонними проверяющими типов. Например, проверяющий типов может отметить следующий код как ошибочный:

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

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

typing.Final¶

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

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

class Connection:
    TIMEOUT: Final[int] = 10

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

Проверка этих свойств во время выполнения не выполняется. Подробнее см. PEP 591.

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

typing.Annotated¶

Тип, введённый в PEP 593 (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 позволяет помещать несколько аннотаций одного (или разных) типа на любой узел, инструменты или библиотеки, потребляющие эти аннотации, отвечают за обработку возможных дубликатов. Например, если вы выполняете анализ диапазона значений, вы можете разрешить это:

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

Передача include_extras=True в get_type_hints() позволяет получить доступ к дополнительным аннотациям во время выполнения.

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

• Первый аргумент Annotated должен быть допустимым типом

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

  Annotated[int, ValueRange(3, 10), ctype("char")]
  

• Annotated должен вызываться как минимум с двумя аргументами ( Annotated[int] недействителен)

• Порядок аннотаций сохраняется и важен для проверки на равенство:

  Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
      int, ctype("char"), ValueRange(3, 10)
  ]
  

• Вложенные типы Annotated уплощаются, при этом метаданные упорядочиваются, начиная с самой внутренней аннотации:

  Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
      int, ValueRange(3, 10), ctype("char")
  ]
  

• Дублирующиеся аннотации не удаляются:

  Annotated[int, ValueRange(3, 10)] != Annotated[
      int, ValueRange(3, 10), ValueRange(3, 10)
  ]
  

• Annotated можно использовать с вложенными и обобщёнными псевдонимами:

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

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

Построение обобщённых типов¶Building generic types

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

class typing.Generic¶

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

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

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

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

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¶

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

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

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

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

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 может быть решена только как одна из заданных ограничений:

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

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

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

class StringSubclass(str):
    pass

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

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

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

Связанные переменные типа особенно полезны для аннотирования classmethods, которые служат альтернативными конструкторами. В следующем примере (© Raymond Hettinger) переменная типа C привязана к классу Circle с помощью прямой ссылки. Использование этой переменной типа для аннотирования классового метода with_circumference вместо жёстко заданного возвращаемого типа Circle означает, что проверяющий типы может корректно вывести возвращаемый тип, даже если метод вызван на подклассе:

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. В общем, isinstance() и issubclass() не должны использоваться с типами.

Переменные типа могут быть помечены как ковариантные или контравариантные путём передачи covariant=True или contravariant=True. См. PEP 484 для получения дополнительных сведений. По умолчанию переменные типа инвариантны.

typing.AnyStr¶

AnyStr – это constrained type variable, определённый как AnyStr = TypeVar('AnyStr', str, bytes).

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

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)¶

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

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

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

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

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

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

Подробности см. в PEP 544. Классы протоколов, декорированные runtime_checkable() (описаны далее), действуют как упрощённые протоколы времени выполнения, которые проверяют только наличие заданных атрибутов, игнорируя их сигнатуры типов.

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

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

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

@typing.runtime_checkable¶

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

Такой протокол может использоваться с isinstance() и issubclass(). При применении к классу, не являющемуся протоколом, возникает TypeError. Это позволяет выполнять простую структурную проверку, очень похожую на “one trick ponies” в collections.abc, таких как Iterable. Например:

@runtime_checkable
class Closable(Protocol):
    def close(self): ...

assert isinstance(open('/some/file'), Closable)

Примечание

runtime_checkable() будет проверять только наличие требуемых методов, но не их сигнатуры типов! Например, builtins.complex реализует __float__(), поэтому он проходит проверку issubclass() на соответствие SupportsFloat. Однако метод complex.__float__ существует только для того, чтобы вызвать TypeError с более информативным сообщением.

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

Другие специальные директивы¶Other special directives

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

class typing.NamedTuple¶

Типизированная версия collections.namedtuple().

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

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

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

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

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

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

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

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

Полученный класс имеет дополнительный атрибут __annotations__, который содержит словарь, отображающий имена полей на их типы. (Имена полей находятся в атрибуте _fields, а значения по умолчанию – в атрибуте _field_defaults; оба они являются частью API namedtuple().)

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

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

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

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

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

Изменено в версии 3.6: Добавлена поддержка синтаксиса аннотации переменных PEP 526.

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

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

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

typing.NewType(name, tp)¶

Вспомогательная функция для указания отдельного типа проверяющему типы, см. NewType. Во время выполнения она возвращает функцию, которая возвращает свой аргумент. Использование:

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

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

class typing.TypedDict(dict)¶

Специальная конструкция для добавления подсказок типов к словарю. Во время выполнения это обычный dict.

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

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, TypedDict поддерживает две дополнительные эквивалентные синтаксические формы:

• Использование литерала dict в качестве второго аргумента:

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

• Использование именованных аргументов:

  Point2D = TypedDict('Point2D', x=int, y=int, label=str)
  

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

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

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

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

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 с использованием синтаксиса на основе классов. Использование:

class Point3D(Point2D):
    z: int

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

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

TypedDict не может наследоваться от не-TypedDict класса, включая Generic. Например:

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__, __required_keys__ и __optional_keys__.

__total__¶

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

>>> 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, содержащие обязательные и необязательные ключи соответственно. В настоящее время единственный способ объявить как обязательные, так и необязательные ключи в одном TypedDict – это смешанное наследование: объявить TypedDict с одним значением для аргумента total, а затем унаследовать его от другого TypedDict с другим значением для total. Использование:

>>> 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 для дополнительных примеров и подробных правил использования TypedDict.

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

Соответствующие встроенным типам¶Corresponding to built-in types

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

Обобщённая версия dict. Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например Mapping.

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

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

Устарело с версии 3.9: builtins.dict теперь поддерживает []. См. PEP 585 и Обобщённый псевдоним типа.

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

Обобщённая версия list. Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например Sequence или Iterable.

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

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 теперь поддерживает []. См. PEP 585 и Обобщённый псевдоним типа.

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

Обобщённая версия builtins.set. Полезна для аннотирования возвращаемых типов. Для аннотирования аргументов предпочтительнее использовать абстрактный тип коллекции, например AbstractSet.

Устарело с версии 3.9: builtins.set теперь поддерживает []. См. PEP 585 и Обобщённый псевдоним типа.

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

Обобщённая версия builtins.frozenset.

Устарело с версии 3.9: builtins.frozenset теперь поддерживает []. См. PEP 585 и Generic Alias Type.

Соответствует типам в collections¶Corresponding to types in collections

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

Обобщённая версия collections.defaultdict.

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

Устарело с версии 3.9: collections.defaultdict теперь поддерживает []. См. PEP 585 и Generic Alias Type.

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

Обобщённая версия collections.OrderedDict.

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

Устарело с версии 3.9: collections.OrderedDict теперь поддерживает []. См. PEP 585 и Generic Alias Type.

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

Обобщённая версия collections.ChainMap.

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

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

Устарело с версии 3.9: collections.ChainMap теперь поддерживает []. См. PEP 585 и Generic Alias Type.

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

Обобщённая версия collections.Counter.

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

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

Устарело с версии 3.9: collections.Counter теперь поддерживает []. См. PEP 585 и Generic Alias Type.

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

Обобщённая версия collections.deque.

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

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

Устарело с версии 3.9: collections.deque теперь поддерживает []. См. PEP 585 и Generic Alias Type.

Другие конкретные типы¶Other concrete types

class typing.IO¶

class typing.TextIO¶

class typing.BinaryIO¶

Обобщённый тип IO[AnyStr] и его подклассы TextIO(IO[str]) и BinaryIO(IO[bytes]) представляют типы потоков ввода-вывода, такие как возвращаемые open().

Устарело с версии 3.8, будет удалено в версии 3.12: Эти типы также находятся в пространстве имён typing.io, которое никогда не поддерживалось проверщиками типов и будет удалено.

class typing.Pattern¶

class typing.Match¶

Эти псевдонимы типов соответствуют возвращаемым типам из re.compile() и re.match(). Эти типы (и соответствующие функции) являются обобщёнными по AnyStr и могут быть конкретизированы записью Pattern[str], Pattern[bytes], Match[str] или Match[bytes].

Устарело с версии 3.8, будет удалено в версии 3.12: Эти типы также находятся в пространстве имён typing.re, которое никогда не поддерживалось проверщиками типов и будет удалено.

Устарело с версии 3.9: Классы Pattern и Match из re теперь поддерживают []. См. PEP 585 и Generic Alias Type.

class typing.Text¶

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

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

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

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

Соответствуют коллекциям из collections.abc¶Corresponding to collections in collections.abc

class typing.AbstractSet(Sized, Collection[T_co])¶

Обобщённая версия collections.abc.Set.

Устарело с версии 3.9: collections.abc.Set теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.ByteString(Sequence[int])¶

Обобщённая версия collections.abc.ByteString.

Этот тип представляет типы bytes, bytearray и memoryview последовательностей байтов.

В качестве сокращения для этого типа bytes можно использовать для аннотации аргументов любого из упомянутых выше типов.

Устарело с версии 3.9: collections.abc.ByteString теперь поддерживает []. См. PEP 585 и Generic Alias Type.

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

Обобщённая версия collections.abc.Collection

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

Устарело с версии 3.9: collections.abc.Collection теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.Container(Generic[T_co])¶

Обобщённая версия collections.abc.Container.

Устарело с версии 3.9: collections.abc.Container теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.ItemsView(MappingView, Generic[KT_co, VT_co])¶

Обобщённая версия collections.abc.ItemsView.

Устарело с версии 3.9: collections.abc.ItemsView теперь поддерживает []. См. PEP 585 и Generic Alias Type.

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

Обобщённая версия collections.abc.KeysView.

Устарело с версии 3.9: collections.abc.KeysView теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.Mapping(Sized, Collection[KT], Generic[VT_co])¶

Обобщённая версия collections.abc.Mapping. Этот тип можно использовать следующим образом:

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

Устарело с версии 3.9: collections.abc.Mapping теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.MappingView(Sized, Iterable[T_co])¶

Обобщённая версия collections.abc.MappingView.

Устарело с версии 3.9: collections.abc.MappingView теперь поддерживает []. См. PEP 585 и Generic Alias Type.

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

Обобщённая версия collections.abc.MutableMapping.

Устарело с версии 3.9: collections.abc.MutableMapping теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.MutableSequence(Sequence[T])¶

Обобщённая версия collections.abc.MutableSequence.

Устарело с версии 3.9: collections.abc.MutableSequence теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.MutableSet(AbstractSet[T])¶

Обобщённая версия collections.abc.MutableSet.

Устарело с версии 3.9: collections.abc.MutableSet теперь поддерживает []. См. PEP 585 и Generic Alias Type.

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

Обобщённая версия collections.abc.Sequence.

Устарело с версии 3.9: collections.abc.Sequence теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.ValuesView(MappingView[VT_co])¶

Обобщённая версия collections.abc.ValuesView.

Устарело с версии 3.9: collections.abc.ValuesView теперь поддерживает []. См. PEP 585 и Generic Alias Type.

Соответствует другим типам в collections.abc¶Corresponding to other types in collections.abc

class typing.Iterable(Generic[T_co])¶

Обобщённая версия collections.abc.Iterable.

Устарело с версии 3.9: collections.abc.Iterable теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.Iterator(Iterable[T_co])¶

Обобщённая версия collections.abc.Iterator.

Устарело с версии 3.9: collections.abc.Iterator теперь поддерживает []. См. PEP 585 и Generic Alias Type.

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

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

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

Обратите внимание: в отличие от многих других обобщённых типов в модуле typing, SendType из Generator ведёт себя контравариантно, а не ковариантно или инвариантно.

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

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

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

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

Устарело с версии 3.9: collections.abc.Generator теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.Hashable¶

Псевдоним для collections.abc.Hashable.

class typing.Reversible(Iterable[T_co])¶

Обобщённая версия collections.abc.Reversible.

Устарело с версии 3.9: collections.abc.Reversible теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.Sized¶

Псевдоним для collections.abc.Sized.

Асинхронное программирование¶Asynchronous programming

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

Обобщённая версия collections.abc.Coroutine. Вариантность и порядок переменных типа соответствуют таковым у Generator, например:

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 теперь поддерживает []. См. PEP 585 и Generic Alias Type.

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

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

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

В отличие от обычных генераторов, асинхронные генераторы не могут возвращать значение, поэтому параметр типа ReturnType отсутствует. Как и в случае с Generator, SendType ведёт себя контравариантно.

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

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

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

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

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

Устарело с версии 3.9: collections.abc.AsyncGenerator теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.AsyncIterable(Generic[T_co])¶

Обобщённая версия collections.abc.AsyncIterable.

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

Устарело с версии 3.9: collections.abc.AsyncIterable теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.AsyncIterator(AsyncIterable[T_co])¶

Обобщённая версия collections.abc.AsyncIterator.

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

Устарело с версии 3.9: collections.abc.AsyncIterator теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.Awaitable(Generic[T_co])¶

Обобщённая версия collections.abc.Awaitable.

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

Устарело с версии 3.9: collections.abc.Awaitable теперь поддерживает []. См. PEP 585 и Generic Alias Type.

Типы контекстных менеджеров¶Context manager types

class typing.ContextManager(Generic[T_co])¶

Обобщённая версия contextlib.AbstractContextManager.

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

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

Устарело с версии 3.9: contextlib.AbstractContextManager теперь поддерживает []. См. PEP 585 и Generic Alias Type.

class typing.AsyncContextManager(Generic[T_co])¶

Обобщённая версия contextlib.AbstractAsyncContextManager.

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

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

Устарело с версии 3.9: contextlib.AbstractAsyncContextManager теперь поддерживает []. См. PEP 585 и Generic Alias Type.