typing — Поддержка подсказок типов

Специальные типы

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

typing.Any

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

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

Изменено в версии 3.11: Any теперь может использоваться в качестве базового класса. Это может быть полезно для предотвращения ошибок проверки типов с классами, которые могут иметь тип утиной типизации в любом месте или являются высокодинамичными.

typing.AnyStr

Переменная типа, ограниченная типом ограниченной переменной типа.

Определение:

AnyStr = TypeVar('AnyStr', str, bytes)

AnyStr предназначен для использования с функциями, которые могут принимать аргументы типа str или bytes, но не могут допускать их смешивание.

Например:

def concat(a: AnyStr, b: AnyStr) -> AnyStr:
    return a + b

concat("foo", "bar")    # OK, output has type 'str'
concat(b"foo", b"bar")  # OK, output has type 'bytes'
concat("foo", b"bar")   # Error, cannot mix str and bytes

Обратите внимание, что, несмотря на своё название, AnyStr не имеет ничего общего с типом Any и не означает «любой строковый тип». В частности, AnyStr и str | bytes отличаются друг от друга и имеют различные области применения:

# Invalid use of AnyStr:
# The type variable is used only once in the function signature,
# so cannot be "solved" by the type checker
def greet_bad(cond: bool) -> AnyStr:
    return "hi there!" if cond else b"greetings!"

# The better way of annotating this function:
def greet_proper(cond: bool) -> str | bytes:
    return "hi there!" if cond else b"greetings!"

typing.LiteralString

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

Любой строковый литерал совместим с LiteralString, как и другой LiteralString. Однако объект, типизированный как просто str не совместим. Строка, созданная путём составления объектов типа LiteralString также допустима как LiteralString.

Пример:

def run_query(sql: LiteralString) -> None:
    ...

def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
    run_query("SELECT * FROM students")  # OK
    run_query(literal_string)  # OK
    run_query("SELECT * FROM " + literal_string)  # OK
    run_query(arbitrary_string)  # type checker error
    run_query(  # type checker error
        f"SELECT * FROM students WHERE name = {arbitrary_string}"
    )

LiteralString полезен для чувствительных API, где произвольные строки, сгенерированные пользователем, могут привести к проблемам. Например, два вышеуказанных случая, которые генерируют ошибки проверки типа, могут быть уязвимы для атаки SQL-инъекции.

См. PEP 675 для получения дополнительных сведений.

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

typing.Never

typing.NoReturn

Never и NoReturn представляют собой тип-дно, тип, не имеющий членов.

Они могут использоваться для обозначения того, что функция никогда не возвращает значение, например, sys.exit():

from typing import Never  # or NoReturn

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

Или для определения функции, которая никогда не должна вызываться, так как нет допустимых аргументов, таких как assert_never():

from typing import Never  # or NoReturn

def never_call_me(arg: Never) -> None:
    pass

def int_or_str(arg: int | str) -> None:
    never_call_me(arg)  # type checker error
    match arg:
        case int():
            print("It's an int")
        case str():
            print("It's a str")
        case _:
            never_call_me(arg)  # OK, arg is of type Never (or NoReturn)

Never и NoReturn имеют одинаковый смысл в системе типов, и статические проверки типов обрабатывают их одинаково.

Добавлен в версии 3.6.2: Добавлен NoReturn.

Добавлен в версии 3.11: Добавлен Never.

typing.Self

Специальный тип для представления текущего вложенного класса.

Например:

from typing import Self, reveal_type

class Foo:
    def return_self(self) -> Self:
        ...
        return self

class SubclassOfFoo(Foo): pass

reveal_type(Foo().return_self())  # Revealed type is "Foo"
reveal_type(SubclassOfFoo().return_self())  # Revealed type is "SubclassOfFoo"

Эта аннотация семантически эквивалентна следующему, хотя и более лаконично:

from typing import TypeVar

Self = TypeVar("Self", bound="Foo")

class Foo:
    def return_self(self: Self) -> Self:
        ...
        return self

В общем случае, если что-то возвращает self, как в вышеприведённых примерах, следует использовать Self в качестве аннотации возвращаемого значения. Если Foo.return_self была аннотирована как возвращающая "Foo", тогда система проверки типов предположит, что объект, возвращённый из SubclassOfFoo.return_self, является типом Foo, а не SubclassOfFoo.

Другие распространённые случаи использования:

• classmethod методы, используемые в качестве альтернативных конструкторов и возвращающие экземпляры параметра cls.
• Аннотация метода __enter__(), который возвращает self.

Не следует использовать Self в качестве аннотации возвращаемого значения, если метод не гарантированно возвращает экземпляр подкласса при наследовании:

class Eggs:
    # Self would be an incorrect return annotation here,
    # as the object returned is always an instance of Eggs,
    # even in subclasses
    def returns_eggs(self) -> "Eggs":
        return Eggs()

См. PEP 673 для получения дополнительных сведений.

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

typing.TypeAlias

Специальная аннотация для явного объявления псевдонима типа.

Например:

from typing import TypeAlias

Factors: TypeAlias = list[int]

TypeAlias особенно полезна в старых версиях Python для аннотирования псевдонимов, использующих вперёд объявления, так как проверка типов может с трудом отличить их от обычных присваиваний переменных:

from typing import Generic, TypeAlias, TypeVar

T = TypeVar("T")

# "Box" does not exist yet,
# so we have to use quotes for the forward reference on Python <3.12.
# Using ``TypeAlias`` tells the type checker that this is a type alias declaration,
# not a variable assignment to a string.
BoxOfStrings: TypeAlias = "Box[str]"

class Box(Generic[T]):
    @classmethod
    def make_box_of_strings(cls) -> BoxOfStrings: ...

См. PEP 613 для получения дополнительных сведений.

Устарело начиная с версии 3.12: TypeAlias устарело в пользу оператора type, который создаёт экземпляры TypeAliasType и который нативно поддерживает вперёд объявления. Обратите внимание, что, хотя TypeAlias и TypeAliasType служат похожим целям и имеют аналогичные имена, они различны, и последний не является типом первого. Удаление TypeAlias в настоящее время не планируется, но пользователям рекомендуется перейти к операторам type.

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

Эти формы могут быть использованы в качестве типов в аннотациях. Все они поддерживают подписку с использованием [], но каждая имеет уникальный синтаксис.

typing.Union

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

Для определения объединения используйте, например, Union[int, str] или сокращенную запись int | str. Использование сокращенной записи рекомендуется. Подробности:

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

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

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

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

  Union[int] == int  # The constructor actually returns int
  

• Избыточные аргументы пропускаются, например:

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

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

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

• Вы не можете наследоваться от или создавать экземпляры Union.
• Вы не можете записать Union[X][Y].

Изменено в версии 3.7: Явных подклассов из объединений не удаляется во время выполнения.

Изменено в версии 3.10: Теперь объединения могут быть записаны как X | Y. См. выражения типа объединения.

typing.Optional

Optional[X] эквивалентно X | None (или Union[X, None]).

Обратите внимание, что это не то же самое, что необязательный аргумент, который имеет значение по умолчанию. Для необязательного аргумента с значением по умолчанию не требуется квалификатор Optional в аннотации типа, просто потому что он необязателен. Например:

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

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

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

Изменено в версии 3.10: Теперь Optional может быть записан как X | None. См. выражения типа объединения.

typing.Concatenate

Специальная форма для аннотирования функций высшего порядка.

Concatenate может использоваться вместе с Callable и ParamSpec для аннотирования вызова высшего порядка, который добавляет, удаляет или преобразует параметры другого вызова. Использование в форме Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]. Concatenate в настоящее время допустимо только при использовании в качестве первого аргумента Callable. Последний параметр Concatenate должен быть ParamSpec или многоточие (...).

Например, чтобы аннотировать декоратор with_lock , который предоставляет threading.Lock декорированной функции, Concatenate можно использовать для указания, что with_lock ожидает вызов, который принимает Lock в качестве первого аргумента и возвращает вызов с другим типом сигнатуры. В этом случае ParamSpec указывает, что типы параметров возвращаемого вызова зависят от типов параметров передаваемого вызова:

from collections.abc import Callable
from threading import Lock
from typing import Concatenate

# Use this lock to ensure that only one thread is executing a function
# at any time.
my_lock = Lock()

def with_lock[**P, R](f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
    '''A type-safe decorator which provides a lock.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        # Provide the lock as the first argument.
        return f(my_lock, *args, **kwargs)
    return inner

@with_lock
def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:
    '''Add a list of numbers together in a thread-safe manner.'''
    with lock:
        return sum(numbers)

# We don't need to pass in the lock ourselves thanks to the decorator.
sum_threadsafe([1.1, 2.2, 3.3])

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

См. также

• PEP 612 — Переменные для спецификации параметров (PEP, который представил ParamSpec и Concatenate)
• ParamSpec
• Аннотирование вызываемых объектов

typing.Literal

Специальная форма типизации для определения «литеральных типов».

Literal может использоваться для указания проверкам типов, что аннотированный объект имеет значение, эквивалентное одному из предоставленных литералов.

Например:

def validate_simple(data: Any) -> Literal[True]:  # always returns True
    ...

type Mode = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: Mode) -> str:
    ...

open_helper('/some/path', 'r')      # Passes type check
open_helper('/other/path', 'typo')  # Error in type checker

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]] = {} # class variable
    damage: int = 10                     # instance variable

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

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

enterprise_d = Starship(3000)
enterprise_d.stats = {} # Error, setting class variable on instance
Starship.stats = {}     # This is OK

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

typing.Final

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

Конечные имена не могут быть переопределены ни в одном из областей видимости. Конечные имена, объявленные в областях видимости класса, не могут быть переопределены в подклассах.

Например:

MAX_SIZE: Final = 9000
MAX_SIZE += 1  # Error reported by type checker

class Connection:
    TIMEOUT: Final[int] = 10

class FastConnector(Connection):
    TIMEOUT = 1  # Error reported by type checker

Проверки этих свойств во время выполнения нет. См. PEP 591 для получения дополнительной информации.

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

typing.Required

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

Это в основном полезно для total=False TypedDicts. См. TypedDict и PEP 655 для получения дополнительной информации.

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

typing.NotRequired

Специальный конструктор типа для маркировки ключа TypedDict как потенциально отсутствующего.

См. TypedDict и PEP 655 для получения дополнительной информации.

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

typing.Annotated

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

Добавьте метаданные x к заданному типу T с помощью аннотации Annotated[T, x]. Метаданные, добавленные с помощью Annotated, могут использоваться инструментами статического анализа или во время выполнения. Во время выполнения метаданные хранятся в атрибуте __metadata__.

Если библиотека или инструмент сталкивается с аннотацией Annotated[T, x] и не имеет специальной логики для метаданных, она должна игнорировать метаданные и просто обрабатывать аннотацию как T. Таким образом, Annotated может быть полезным для кода, который хочет использовать аннотации для целей, выходящих за рамки системы статической типизации Python.

Использование Annotated[T, x] в качестве аннотации все еще позволяет выполнять статическую проверку типов T, так как инструменты проверки типов просто проигнорируют метаданные x. Таким образом, Annotated отличается от декоратора @no_type_check, который также может использоваться для добавления аннотаций за пределами системы типизации, но полностью отключает проверку типов для функции или класса.

Ответственность за интерпретацию метаданных лежит на инструменте или библиотеке, столкнувшейся с аннотацией Annotated . Инструмент или библиотека, столкнувшись с типом Annotated, может просматривать элементы метаданных, чтобы определить, представляют ли они интерес (например, используя isinstance()).

Annotated[<type>, <metadata>]

Вот пример того, как можно использовать Annotated для добавления метаданных к аннотациям типов, если вы выполняете анализ диапазонов:

@dataclass
class ValueRange:
    lo: int
    hi: int

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

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

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

• Можно предоставить несколько элементов метаданных (Annotated поддерживает аргументы переменной длины):

  @dataclass
  class ctype:
      kind: str
  
  Annotated[int, ValueRange(3, 10), ctype("char")]
  

  Инструменту, потребляющему аннотации, решать, разрешено ли клиенту добавлять несколько элементов метаданных к одной аннотации и как объединять эти аннотации.

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

• Порядок элементов метаданных сохраняется и имеет значение для проверок на равенство:

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

• Вложенные типы Annotated сглаживаются. Порядок элементов метаданных начинается с самой внутренней аннотации:

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

• Дублированные элементы метаданных не удаляются:

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

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

  @dataclass
  class MaxLen:
      value: int
  
  type Vec[T] = Annotated[list[tuple[T, T]], MaxLen(10)]
  
  # When used in a type annotation, a type checker will treat "V" the same as
  # ``Annotated[list[tuple[int, int]], MaxLen(10)]``:
  type V = Vec[int]
  

• Annotated нельзя использовать с распакованным TypeVarTuple:

  type Variadic[*Ts] = Annotated[*Ts, Ann1]  # NOT valid
  

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

  Annotated[T1, T2, T3, ..., Ann1]
  

  где T1, T2, и т. д. являются TypeVars. Это будет недопустимо: в Annotated должен быть передан только один тип.

• По умолчанию get_type_hints() удаляет метаданные из аннотаций. Передайте include_extras=True для сохранения метаданных:

  >>> from typing import Annotated, get_type_hints
  >>> def func(x: Annotated[int, "metadata"]) -> None: pass
  ...
  >>> get_type_hints(func)
  {'x': <class 'int'>, 'return': <class 'NoneType'>}
  >>> get_type_hints(func, include_extras=True)
  {'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}
  

• Во время выполнения метаданные, связанные с типом Annotated, могут быть получены через атрибут __metadata__:

  >>> from typing import Annotated
  >>> X = Annotated[int, "very", "important", "metadata"]
  >>> X
  typing.Annotated[int, 'very', 'important', 'metadata']
  >>> X.__metadata__
  ('very', 'important', 'metadata')
  

См. также

PEP 593 - Гибкие аннотации функций и переменных

PEP, который вводит Annotated в стандартную библиотеку.

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

typing.TypeGuard

Специальная конструкция типизации для маркировки пользовательских функций-предикатов типа.

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

TypeGuard призван принести пользу сужению типов — технике, используемой инструментами статической типизации для определения более точного типа выражения в потоке кода программы. Обычно сужение типов выполняется путем анализа условного потока кода и применения сужения к блоку кода. Условное выражение в этом случае иногда называется «предикатом типа»:

def is_str(val: str | float):
    # "isinstance" type guard
    if isinstance(val, str):
        # Type of ``val`` is narrowed to ``str``
        ...
    else:
        # Else, type of ``val`` is narrowed to ``float``.
        ...

Иногда бывает удобно использовать пользовательскую булеву функцию в качестве предиката типа. Такая функция должна использовать TypeGuard[...] в качестве типа возвращаемого значения, чтобы сообщить инструментам статической типизации об этом намерении.

Использование -> TypeGuard сообщает инструменту статической типизации, что для данной функции:

1. Возвращаемое значение — булево.
2. Если возвращаемое значение — True, тип его аргумента — тип внутри TypeGuard.

Например:

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    '''Determines whether all objects in the list are strings'''
    return all(isinstance(x, str) for x in val)

def func1(val: list[object]):
    if is_str_list(val):
        # Type of ``val`` is narrowed to ``list[str]``.
        print(" ".join(val))
    else:
        # Type of ``val`` remains as ``list[object]``.
        print("Not a list of strings!")

Если is_str_list — метод класса или экземпляра, то тип в TypeGuard соответствует типу второго параметра (после cls или self).

Короче говоря, форма def foo(arg: TypeA) -> TypeGuard[TypeB]: ..., означает, что если foo(arg) возвращает True, то arg сужается от TypeA до TypeB.

Примечание

TypeB не обязательно должен быть более узкой формой TypeA — он может быть даже более широкой. Основная причина заключается в том, чтобы разрешить такие вещи, как сужение list[object] до list[str] даже если последнее не является подтипом первого, так как list инвариантен. Ответственность за написание безопасных с точки зрения типов предикатов типа возлагается на пользователя.

TypeGuard также работает с переменными типов. См. PEP 647 для получения дополнительных сведений.

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

typing.Unpack

Оператор типизации для концептуальной маркировки объекта как распакованного.

Например, использование оператора распаковки * на кортеже переменной типа эквивалентно использованию Unpack для обозначения кортежа переменной типа как распакованного:

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]
# Effectively does:
tup: tuple[Unpack[Ts]]

На самом деле, Unpack может использоваться взаимозаменяемо с * в контексте typing.TypeVarTuple и builtins.tuple типов. Вы можете увидеть Unpack в явном виде в более ранних версиях Python, где * нельзя было использовать в определенных местах:

# In older versions of Python, TypeVarTuple and Unpack
# are located in the `typing_extensions` backports package.
from typing_extensions import TypeVarTuple, Unpack

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]         # Syntax error on Python <= 3.10!
tup: tuple[Unpack[Ts]]  # Semantically equivalent, and backwards-compatible

Unpack также можно использовать вместе с typing.TypedDict для типизации **kwargs в сигнатуре функции:

from typing import TypedDict, Unpack

class Movie(TypedDict):
    name: str
    year: int

# This function expects two keyword arguments - `name` of type `str`
# and `year` of type `int`.
def foo(**kwargs: Unpack[Movie]): ...

См. PEP 692 для получения более подробной информации об использовании Unpack для типизации **kwargs.

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

Создание обобщенных типов и псевдонимов типов

Следующие классы не должны использоваться напрямую в качестве аннотаций. Их предназначение — служить строительными блоками для создания обобщенных типов и псевдонимов типов.

Эти объекты могут быть созданы с помощью специальной синтаксической конструкции (списки параметров типа и оператора type). Для совместимости с Python 3.11 и более ранними версиями их также можно создавать без специального синтаксиса, как описано ниже.

class typing.Generic

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

Обобщенный тип обычно объявляется путем добавления списка параметров типа после имени класса:

class Mapping[KT, VT]:
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.

Такой класс неявно наследуется от Generic. Семантика выполнения этого синтаксиса обсуждается в Справочнике по языку.

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

def lookup_name[X, Y](mapping: Mapping[X, Y], key: X, default: Y) -> Y:
    try:
        return mapping[key]
    except KeyError:
        return default

Здесь скобки после имени функции указывают на обобщенную функцию.

Для обратной совместимости обобщенные классы также можно объявить, явно унаследовавшись от Generic. В этом случае параметры типа должны быть объявлены отдельно:

KT = TypeVar('KT')
VT = TypeVar('VT')

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

class typing.TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False)

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

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

class Sequence[T]:  # T is a TypeVar
    ...

Этот синтаксис также можно использовать для создания ограниченных и связанных переменных типа:

class StrSequence[S: str]:  # S is a TypeVar bound to str
    ...


class StrOrBytesSequence[A: (str, bytes)]:  # A is a TypeVar constrained to str or bytes
    ...

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

T = TypeVar('T')  # Can be anything
S = TypeVar('S', bound=str)  # Can be any subtype of str
A = TypeVar('A', str, bytes)  # Must be exactly str or bytes

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

def repeat[T](x: T, n: int) -> Sequence[T]:
    """Return a list containing n references to x."""
    return [x]*n


def print_capitalized[S: str](x: S) -> S:
    """Print x capitalized, and return x."""
    print(x.capitalize())
    return x


def concatenate[A: (str, bytes)](x: A, y: A) -> A:
    """Add two strings or bytes objects together."""
    return x + y

Обратите внимание, что переменные типа могут быть связанными, ограниченными или ни тем, ни другим, но не могут быть одновременно связанными и ограниченными.

Изменчивость переменных типа определяется проверяющими типами при их создании с помощью синтаксиса параметров типа или при передаче infer_variance=True. Вручную созданные переменные типа могут быть явно отмечены как ковариантные или контравариантные путем передачи covariant=True или contravariant=True. По умолчанию вручную созданные переменные типа являются инвариантными. См. PEP 484 и PEP 695 для получения более подробной информации.

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

x = print_capitalized('a string')
reveal_type(x)  # revealed type is str

class StringSubclass(str):
    pass

y = print_capitalized(StringSubclass('another string'))
reveal_type(y)  # revealed type is StringSubclass

z = print_capitalized(45)  # error: int is not a subtype of str

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

# Can be anything with an __abs__ method
def print_abs[T: SupportsAbs](arg: T) -> None:
    print("Absolute value:", abs(arg))

U = TypeVar('U', bound=str|bytes)  # Can be any subtype of the union str|bytes
V = TypeVar('V', bound=SupportsAbs)  # Can be anything with an __abs__ method

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

a = concatenate('one', 'two')
reveal_type(a)  # revealed type is str

b = concatenate(StringSubclass('one'), StringSubclass('two'))
reveal_type(b)  # revealed type is str, despite StringSubclass being passed in

c = concatenate('one', b'two')  # error: type variable 'A' can be either str or bytes in a function call, but not both

Во время выполнения isinstance(x, T) будет вызывать TypeError.

__name__

Имя переменной типа.

__covariant__

Указывает, была ли переменная типа явно помечена как ковариантная.

__contravariant__

Указывает, была ли переменная типа явно помечена как контравариантная.

__infer_variance__

Указывает, следует ли проверяющим типов выводить изменчивость переменной типа.

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

__bound__

Ограничение переменной типа, если таковое имеется.

Изменено в версии 3.12: Для переменных типа, созданных с помощью синтаксиса параметров типа, ограничение вычисляется только при обращении к атрибуту, а не при создании переменной типа (см. Ленивые вычисления).

__constraints__

Кортеж, содержащий ограничения переменной типа, если таковые имеются.

Изменено в версии 3.12: Для переменных типа, созданных с помощью синтаксиса параметров типа, ограничения вычисляются только при обращении к атрибуту, а не при создании переменной типа (см. Ленивые вычисления).

Изменено в версии 3.12: Теперь переменные типа можно объявлять с помощью синтаксиса параметра типа, введенного в PEP 695. Добавлено параметр infer_variance.

class typing.TypeVarTuple(name)

Кортеж переменных типа. Специализированная форма переменной типа, которая позволяет создавать переменные обобщения.

Кортежи переменных типа могут быть объявлены в списках параметров типа с использованием одиночного символа звездочки (*) перед именем:

def move_first_element_to_last[T, *Ts](tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

Или путем явного вызова конструктора TypeVarTuple.

T = TypeVar("T")
Ts = TypeVarTuple("Ts")

def move_first_element_to_last(tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

Обычная переменная типа позволяет параметризацию с одним типом. В отличие от этого, кортеж переменных типа позволяет параметризацию с любым количеством типов, действуя как любое количество переменных типа, заключенных в кортеж. Например:

# T is bound to int, Ts is bound to ()
# Return value is (1,), which has type tuple[int]
move_first_element_to_last(tup=(1,))

# T is bound to int, Ts is bound to (str,)
# Return value is ('spam', 1), which has type tuple[str, int]
move_first_element_to_last(tup=(1, 'spam'))

# T is bound to int, Ts is bound to (str, float)
# Return value is ('spam', 3.0, 1), which has type tuple[str, float, int]
move_first_element_to_last(tup=(1, 'spam', 3.0))

# This fails to type check (and fails at runtime)
# because tuple[()] is not compatible with tuple[T, *Ts]
# (at least one element is required)
move_first_element_to_last(tup=())

Обратите внимание на использование оператора распаковки * в tuple[T, *Ts]. По сути, Ts можно представить как кортеж из переменных типа (T1, T2, ...). tuple[T, *Ts] тогда станет tuple[T, *(T1, T2, ...)], что эквивалентно tuple[T, T1, T2, ...]. (Обратите внимание, что в более старых версиях Python это может быть записано с использованием Unpack вместо Unpack[Ts].)

Кортежи переменных типа всегда должны быть распакованы. Это помогает различать кортежи переменных типа от обычных переменных типа:

x: Ts          # Not valid
x: tuple[Ts]   # Not valid
x: tuple[*Ts]  # The correct way to do it

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

class Array[*Shape]:
    def __getitem__(self, key: tuple[*Shape]) -> float: ...
    def __abs__(self) -> "Array[*Shape]": ...
    def get_shape(self) -> tuple[*Shape]: ...

Кортежи переменных типа могут быть объединены с обычными переменными типа:

class Array[DType, *Shape]:  # This is fine
    pass

class Array2[*Shape, DType]:  # This would also be fine
    pass

class Height: ...
class Width: ...

float_array_1d: Array[float, Height] = Array()     # Totally fine
int_array_2d: Array[int, Height, Width] = Array()  # Yup, fine too

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

x: tuple[*Ts, *Ts]            # Not valid
class Array[*Shape, *Shape]:  # Not valid
    pass

Наконец, распакованный кортеж переменных типа может быть использован как аннотация типа для *args:

def call_soon[*Ts](
    callback: Callable[[*Ts], None],
    *args: *Ts
) -> None:
    ...
    callback(*args)

В отличие от нераспакованных аннотаций *args - например, *args: int, которые указывали бы, что все аргументы являются int, *args: *Ts позволяет ссылаться на типы отдельных аргументов в *args. Здесь это позволяет нам гарантировать, что типы *args передаваемые в call_soon соответствуют типам (позиционных) аргументов callback.

См. PEP 646 для получения более подробной информации о кортежах переменных типа.

__name__

Имя кортежа переменной типа.

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

Изменено в версии 3.12: Кортежи переменных типа теперь можно объявлять с использованием синтаксиса параметра типа, введенного в PEP 695.

class typing.ParamSpec(name, *, bound=None, covariant=False, contravariant=False)

Переменная спецификации параметра. Специализированная версия переменных типов.

В списках параметров типа спецификации параметров могут быть объявлены с двумя звёздочками (**):

type IntFunc[**P] = Callable[P, int]

Для совместимости с Python 3.11 и более ранними версиями, ParamSpec объекты также могут быть созданы следующим образом:

P = ParamSpec('P')

Переменные спецификации параметров существуют в первую очередь для удобства статических проверочных инструментов типов. Они используются для передачи типов параметров одного вызываемого объекта другому вызываемому объекту — шаблон, часто встречающийся в высших-порядковых функциях и декораторах. Они допустимы только при использовании в Concatenate, или в качестве первого аргумента для Callable, или в качестве параметров для пользовательских обобщений. См. Generic для получения дополнительной информации о обобщённых типах.

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

from collections.abc import Callable
import logging

def add_logging[T, **P](f: Callable[P, T]) -> Callable[P, T]:
    '''A type-safe decorator to add logging to a function.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> T:
        logging.info(f'{f.__name__} was called')
        return f(*args, **kwargs)
    return inner

@add_logging
def add_two(x: float, y: float) -> float:
    '''Add two numbers together.'''
    return x + y

Без ParamSpec, самый простой способ аннотировать это ранее заключался в использовании TypeVar с ограничением Callable[..., Any]. Однако это вызывает две проблемы:

1. Инструмент проверки типов не может проверить функцию inner, потому что *args и **kwargs должны быть типизированы как Any.
2. cast() может потребоваться в теле декоратора add_logging при возвращении функции inner, или инструменту статической проверки типов нужно сказать игнорировать return inner.

args

kwargs

Поскольку ParamSpec захватывает как позиционные, так и ключевые параметры, P.args и P.kwargs могут быть использованы для разделения ParamSpec на компоненты. P.args представляет собой кортеж позиционных параметров в данном вызове и должен использоваться только для аннотации *args. P.kwargs представляет собой отображение ключевых параметров и их значений в данном вызове и должно использоваться только для аннотации **kwargs. Оба атрибута требуют, чтобы аннотируемый параметр был в области видимости. Во время выполнения, P.args и P.kwargs являются соответственно экземплярами ParamSpecArgs и ParamSpecKwargs.

__name__

Имя спецификации параметра.

Переменные спецификации параметров, созданные с помощью covariant=True или contravariant=True могут быть использованы для объявления ковариативных или контравариативных обобщенных типов. Также принимается аргумент bound, аналогично TypeVar. Однако фактическая семантика этих ключевых слов ещё не определена.

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

Изменено в версии 3.12: Спецификации параметров теперь можно объявлять с использованием синтаксиса параметра типа, введённого в PEP 695.

Примечание

Только переменные спецификации параметров, определённые в глобальной области, могут быть сериализованы.

См. также

• PEP 612 — Переменные спецификации параметров (PEP, введший ParamSpec и Concatenate)
• Concatenate
• Аннотирование вызываемых объектов

typing.ParamSpecArgs

typing.ParamSpecKwargs

Атрибуты аргументов и ключевых аргументов ParamSpec. Атрибут P.args ParamSpec является экземпляром ParamSpecArgs, а P.kwargs — экземпляром ParamSpecKwargs. Они предназначены для интроспекции во время выполнения и не имеют особого значения для статических инструментов проверки типов.

Вызов get_origin() для любого из этих объектов вернёт исходный ParamSpec:

>>> from typing import ParamSpec, get_origin
>>> P = ParamSpec("P")
>>> get_origin(P.args) is P
True
>>> get_origin(P.kwargs) is P
True

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

class typing.TypeAliasType(name, value, *, type_params=())

Тип псевдонимов типов, созданных с помощью инструкции type.

Пример:

>>> type Alias = int
>>> type(Alias)
<class 'typing.TypeAliasType'>

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

__name__

Имя псевдонима типа:

>>> type Alias = int
>>> Alias.__name__
'Alias'

__module__

Модуль, в котором был определён псевдоним типа:

>>> type Alias = int
>>> Alias.__module__
'__main__'

__type_params__

Параметры типа псевдонима, или пустой кортеж, если псевдоним не обобщённый:

>>> type ListOrSet[T] = list[T] | set[T]
>>> ListOrSet.__type_params__
(T,)
>>> type NotGeneric = int
>>> NotGeneric.__type_params__
()

__value__

Значение псевдонима типа. Оно лениво вычисляется, поэтому имена, используемые в определении псевдонима, не разрешаются до тех пор, пока не будет обращение к атрибуту __value__:

>>> type Mutually = Recursive
>>> type Recursive = Mutually
>>> Mutually
Mutually
>>> Recursive
Recursive
>>> Mutually.__value__
Recursive
>>> Recursive.__value__
Mutually

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

Эти функции и классы не должны использоваться напрямую как аннотации. Их предназначение — быть строительными блоками для создания и объявления типов.

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):
    """Represents an employee."""
    name: str
    id: int = 3

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

NamedTuple подклассы могут быть обобщёнными:

class Group[T](NamedTuple):
    key: T
    group: list[T]

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

# For creating a generic NamedTuple on Python 3.11 or lower
class Group(NamedTuple, Generic[T]):
    key: T
    group: list[T]

# A functional syntax is also supported
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__ , содержащего ту же информацию.

Изменено в версии 3.11: Добавлена поддержка обобщённых кортежей с именованными полями.

class typing.NewType(name, tp)

Вспомогательный класс для создания типов отдельных типов с низкими накладными расходами.

Тип NewType считается типом отдельного типа в проверяющем типе. Однако при выполнении вызов NewType возвращает свой аргумент без изменений.

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

UserId = NewType('UserId', int)  # Declare the NewType "UserId"
first_user = UserId(1)  # "UserId" returns the argument unchanged at runtime

__module__

Модуль, в котором определён новый тип.

__name__

Имя нового типа.

__supertype__

Тип, на котором основан новый тип.

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

Изменено в версии 3.10: NewType теперь является классом, а не функцией.

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())  # Passes static type check

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

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

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

В коде, который должен быть совместимым с Python 3.11 или более ранними версиями, обобщённые протоколы могут быть записаны следующим образом:

T = TypeVar("T")

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

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

@typing.runtime_checkable

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

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

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

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

@runtime_checkable
class Named(Protocol):
    name: str

import threading
assert isinstance(threading.Thread(name='Bob'), Named)

Примечание

runtime_checkable() будет проверять только наличие необходимых методов или атрибутов, а не их сигнатуры типов или типы. Например, ssl.SSLObject является классом, поэтому он проходит проверку issubclass() по отношению к Callable. Однако метод ssl.SSLObject.__init__ существует только для повышения TypeError с более информативным сообщением, поэтому его нельзя вызвать (инициализировать) ssl.SSLObject.

Примечание

Проверка isinstance() на протоколе времени выполнения может быть неожиданно медленной по сравнению с проверкой isinstance() на классе, не являющимся протоколом. В производительно чувствительном коде рассмотрите использование альтернативных выражений, таких как вызовы hasattr() для структурных проверок.

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

Изменено в версии 3.12: Внутренняя реализация isinstance() проверок на протоколах времени выполнения теперь использует inspect.getattr_static() для поиска атрибутов (ранее использовалась hasattr()). В результате некоторые объекты, которые ранее считались экземплярами протокола времени выполнения, могут больше не считаться таковыми в Python 3.12+, и наоборот. Большинство пользователей, скорее всего, не пострадают от этого изменения.

Изменено в версии 3.12: Члены протокола времени выполнения теперь считаются «замороженными» во время выполнения сразу после создания класса. Модификация атрибутов протокола времени выполнения по-прежнему работает, но не повлияет на проверки isinstance(), сравнивающие объекты с протоколом. См. “Что нового в Python 3.12” для получения дополнительной информации.

class typing.TypedDict(dict)

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

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

class Point2D(TypedDict):
    x: int
    y: int
    label: str

a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # OK
b: Point2D = {'z': 3, 'label': 'bad'}           # Fails type check

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)
  

  Устарело начиная с версии 3.11, будет удалено в версии 3.13: Синтаксис именованных аргументов устарел в версии 3.11 и будет удален в версии 3.13. Он также может не поддерживаться статическими средствами проверки типов.

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

# raises SyntaxError
class Point2D(TypedDict):
    in: int  # 'in' is a keyword
    x-y: int  # name with hyphens

# OK, functional syntax
Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})

По умолчанию все ключи должны быть присутствовать в TypedDict. Можно отметить отдельные ключи как необязательные, используя NotRequired:

class Point2D(TypedDict):
    x: int
    y: int
    label: NotRequired[str]

# Alternative syntax
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': NotRequired[str]})

Это означает, что у Point2D TypedDict может быть опущен ключ label.

Также можно помечать все ключи как необязательные по умолчанию, указав полную совокупность False:

class Point2D(TypedDict, total=False):
    x: int
    y: int

# Alternative syntax
Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False)

Это означает, что у Point2D TypedDict может быть опущен любой из ключей. Средство проверки типов должно поддерживать только литеральный False или True в качестве значения аргумента total. True — значение по умолчанию, делающее все элементы, определённые в теле класса, обязательными.

Отдельные ключи total=False TypedDict можно помечать как обязательные, используя Required:

class Point2D(TypedDict, total=False):
    x: Required[int]
    y: Required[int]
    label: str

# Alternative syntax
Point2D = TypedDict('Point2D', {
    'x': Required[int],
    'y': Required[int],
    'label': str
}, total=False)

Тип 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  # A non-TypedDict class

class XY(X, Y): pass  # OK

class XZ(X, Z): pass  # raises TypeError

TypedDict может быть дженериком:

class Group[T](TypedDict):
    key: T
    group: list[T]

Для создания дженеричного TypedDict совместимого с Python 3.11 или более ранними версиями, явно наследуйте от Generic:

T = TypeVar("T")

class Group(TypedDict, Generic[T]):
    key: T
    group: list[T]

TypedDict можно проинспектировать через словари аннотаций (см. Рекомендации по лучшим практикам аннотаций для получения дополнительной информации об аннотациях лучших практик), __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

Это атрибут отражает только значение аргумента total текущего класса TypedDict, а не является ли класс семантически полным. Например, TypedDict с __total__ установленным в True может иметь ключи, помеченные NotRequired, или может наследоваться от другого TypedDict с total=False . Поэтому, для интроспекции лучше использовать __required_keys__ и __optional_keys__.

__required_keys__

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

__optional_keys__

Point2D.__required_keys__ и Point2D.__optional_keys__ возвращают объекты frozenset, содержащие требуемые и необязательные ключи соответственно.

Ключи, помеченные Required, всегда будут появляться в __required_keys__, а ключи, помеченные NotRequired, всегда будут появляться в __optional_keys__.

Для обратной совместимости с Python 3.10 и ниже также можно использовать наследование для объявления как обязательных, так и необязательных ключей в одном 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

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

Примечание

Если используется from __future__ import annotations или если аннотации заданы как строки, аннотации не оцениваются при определении TypedDict . Поэтому, динамическая интроспекция, на которой полагаются __required_keys__ и __optional_keys__ , может не работать должным образом, и значения атрибутов могут быть неверными.

См. PEP 589 для получения дополнительных примеров и подробных правил использования TypedDict.

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

Изменено в версии 3.11: Добавлена поддержка пометки отдельных ключей как Required или NotRequired. См. PEP 655.

Изменено в версии 3.11: Добавлена поддержка дженеричных TypedDict.

Псевдонимы встроенных типов

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

Устаревший псевдоним для dict.

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

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

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

Устарел начиная с версии 3.9: builtins.dict теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

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

Устаревший псевдоним для list.

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

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

def vec2[T: (int, float)](x: T, y: T) -> List[T]:
    return [x, y]

def keep_positives[T: (int, float)](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, а не set или typing.Set.

Устарел начиная с версии 3.9: builtins.set теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

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

Устаревший псевдоним для builtins.frozenset.

Устарел начиная с версии 3.9: builtins.frozenset теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

typing.Tuple

Устаревший псевдоним для tuple.

tuple и Tuple имеют специальное обращение в системе типов; см. Аннотация кортежей для получения более подробной информации.

Устарел начиная с версии 3.9: builtins.tuple теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

class typing.Type(Generic[CT_co])

Устаревший псевдоним для type.

См. Тип объектов классов для получения подробной информации об использовании type или typing.Type в аннотациях типов.

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

Устарел начиная с версии 3.9: builtins.type теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

Псевдонимы типов в collections

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

Устаревший псевдоним для collections.defaultdict.

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

Устарел начиная с версии 3.9: collections.defaultdict теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима обобщённого типа.

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

Устаревший псевдоним для collections.OrderedDict.

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

Устарел начиная с версии 3.9: collections.OrderedDict теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима обобщённого типа.

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

Устаревший псевдоним для collections.ChainMap.

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

Устарел начиная с версии 3.9: collections.ChainMap теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима обобщённого типа.

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

Устаревший псевдоним для collections.Counter.

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

Устарел начиная с версии 3.9: collections.Counter теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима обобщённого типа.

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

Устаревший псевдоним для collections.deque.

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

Устарел начиная с версии 3.9: collections.deque теперь поддерживает индексацию ([]). См. PEP 585 и Тип псевдонима обобщённого типа.

Псевдонимы других конкретных типов

class typing.Pattern

class typing.Match

Устаревшие псевдонимы, соответствующие типам возвращаемых значений из re.compile() и re.match().

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

Устарел начиная с версии 3.8, будет удален в версии 3.13: Пространство имён typing.re устарело и будет удалено. Эти типы следует импортировать напрямую из typing.

Устарел начиная с версии 3.9: Классы Pattern и Match из re теперь поддерживают []. См. PEP 585 и Тип псевдонима обобщённого типа.

class typing.Text

Устаревший псевдоним для str.

Text предоставлен для обеспечения совместимости с кодом 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.

Устарел начиная с версии 3.11: Python 2 больше не поддерживается, и большинство проверяющих типов больше не поддерживают проверку типов кода Python 2. Удаление псевдонима в настоящее время не планируется, но пользователям рекомендуется использовать str вместо Text.

Псевдонимы для ABC контейнеров в collections.abc

class typing.AbstractSet(Collection[T_co])

Устаревший псевдоним для collections.abc.Set.

Устарело начиная с версии 3.9: collections.abc.Set теперь поддерживает индексацию ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.ByteString(Sequence[int])

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

Устарело начиная с версии 3.9, будет удалено в версии 3.14: Предпочитайте collections.abc.Buffer или объединение, например, bytes | bytearray | memoryview.

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

Устаревший псевдоним для collections.abc.Collection.

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

Устарело начиная с версии 3.9: collections.abc.Collection теперь поддерживает индексацию ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.Container(Generic[T_co])

Устаревший псевдоним для collections.abc.Container.

Устарело начиная с версии 3.9: collections.abc.Container теперь поддерживает индексацию ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.ItemsView(MappingView, AbstractSet[tuple[KT_co, VT_co]])

Устаревший псевдоним для collections.abc.ItemsView.

Устарело начиная с версии 3.9: collections.abc.ItemsView теперь поддерживает индексацию ([]). См. PEP 585 и Тип обобщенного псевдонима.

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

Устаревший псевдоним для collections.abc.KeysView.

Устарело начиная с версии 3.9: collections.abc.KeysView теперь поддерживает индексацию ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.Mapping(Collection[KT], Generic[KT, 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 и Тип обобщенного псевдонима.

class typing.MappingView(Sized)

Устаревший псевдоним для collections.abc.MappingView.

Устарело начиная с версии 3.9: collections.abc.MappingView теперь поддерживает индексацию ([]). См. PEP 585 и Тип обобщенного псевдонима.

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

Устаревший псевдоним для collections.abc.MutableMapping.

Устарело начиная с версии 3.9: collections.abc.MutableMapping теперь поддерживает индексацию ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.MutableSequence(Sequence[T])

Устаревший псевдоним для collections.abc.MutableSequence.

Устарело начиная с версии 3.9: collections.abc.MutableSequence теперь поддерживает индексацию ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.MutableSet(AbstractSet[T])

Устаревший псевдоним для collections.abc.MutableSet.

Устарело начиная с версии 3.9: collections.abc.MutableSet теперь поддерживает индексацию ([]). См. PEP 585 и Тип обобщенного псевдонима.

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

Устаревший псевдоним для collections.abc.Sequence.

Устарело начиная с версии 3.9: collections.abc.Sequence теперь поддерживает индексацию ([]). См. PEP 585 и Тип обобщенного псевдонима.

class typing.ValuesView(MappingView, Collection[_VT_co])

Устаревшее псевдоним для collections.abc.ValuesView.

Устарело начиная с версии 3.9: collections.abc.ValuesView теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

Псевдонимы асинхронных ABC в collections.abc

class typing.Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])

Устаревшее псевдоним для collections.abc.Coroutine.

Изменение вариативности и порядка типов соответствуют тем, что у Generator, например:

from collections.abc import Coroutine
c: Coroutine[list[str], str, int]  # Some coroutine defined elsewhere
x = c.send('hi')                   # Inferred type of 'x' is list[str]
async def bar() -> None:
    y = await c                    # Inferred type of 'y' is int

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

Устарело начиная с версии 3.9: collections.abc.Coroutine теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

class typing.AsyncGenerator(AsyncIterator[YieldType], Generic[YieldType, SendType])

Устаревшее псевдоним для collections.abc.AsyncGenerator.

Асинхронный генератор можно аннотировать обобщённым типом 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 и Тип обобщённого псевдонима.

class typing.AsyncIterable(Generic[T_co])

Устаревшее псевдоним для collections.abc.AsyncIterable.

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

Устарело начиная с версии 3.9: collections.abc.AsyncIterable теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

class typing.AsyncIterator(AsyncIterable[T_co])

Устаревшее псевдоним для collections.abc.AsyncIterator.

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

Устарело начиная с версии 3.9: collections.abc.AsyncIterator теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

class typing.Awaitable(Generic[T_co])

Устаревшее псевдоним для collections.abc.Awaitable.

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

Устарело начиная с версии 3.9: collections.abc.Awaitable теперь поддерживает индексирование ([]). См. PEP 585 и Тип обобщённого псевдонима.

Псевдонимы других ABC в collections.abc

class typing.Iterable(Generic[T_co])

Устаревший псевдоним для collections.abc.Iterable.

Устарело начиная с версии 3.9: collections.abc.Iterable теперь поддерживает индексирование ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.Iterator(Iterable[T_co])

Устаревший псевдоним для collections.abc.Iterator.

Устарело начиная с версии 3.9: collections.abc.Iterator теперь поддерживает индексирование ([]). См. PEP 585 и Тип псевдонима дженерика.

typing.Callable

Устаревший псевдоним для collections.abc.Callable.

См. Аннотирование вызываемых объектов для получения подробной информации о том, как использовать collections.abc.Callable и typing.Callable в аннотациях типов.

Устарело начиная с версии 3.9: collections.abc.Callable теперь поддерживает индексирование ([]). См. PEP 585 и Тип псевдонима дженерика.

Изменено в версии 3.10: Callable теперь поддерживает ParamSpec и Concatenate. См. PEP 612 для получения дополнительной информации.

class typing.Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])

Устаревший псевдоним для collections.abc.Generator.

Генератор можно аннотировать с помощью дженерического типа 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 и Тип псевдонима дженерика.

class typing.Hashable

Устаревший псевдоним для collections.abc.Hashable.

Устарело начиная с версии 3.12: Используйте collections.abc.Hashable напрямую вместо этого.

class typing.Reversible(Iterable[T_co])

Устаревший псевдоним для collections.abc.Reversible.

Устарело начиная с версии 3.9: collections.abc.Reversible теперь поддерживает индексирование ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.Sized

Устаревший псевдоним для collections.abc.Sized.

Устарело начиная с версии 3.12: Используйте collections.abc.Sized напрямую вместо этого.

Псевдонимы ABC contextlib

class typing.ContextManager(Generic[T_co])

Устаревший псевдоним для contextlib.AbstractContextManager.

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

Устарело начиная с версии 3.9: contextlib.AbstractContextManager теперь поддерживает индексирование ([]). См. PEP 585 и Тип псевдонима дженерика.

class typing.AsyncContextManager(Generic[T_co])

Устаревший псевдоним для contextlib.AbstractAsyncContextManager.

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

Устарело начиная с версии 3.9: contextlib.AbstractAsyncContextManager теперь поддерживает индексирование ([]). См. PEP 585 и Тип псевдонима дженерика.