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.10.

Устарело с версии 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 TypedDict. Подробнее см. 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')
  

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

  >>> from typing import Annotated, get_origin
  >>> Password = Annotated[str, "secret"]
  >>> Password.__origin__
  <class 'str'>
  

  Обратите внимание, что вызов get_origin() вернёт сам Annotated:

  >>> get_origin(Password)
  <class 'typing.Annotated'>
  

См. также

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]]

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

# 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]): ...

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

Добавлено в версии 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 with a `str` upper bound;
    ...                     # we can say that S is "bounded by `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 или Protocol) или даже объединение типов:

# 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. В теле декоратора add_logging при возврате функции inner может потребоваться cast(); иначе статическому анализатору типов нужно указать игнорировать 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.

Примечание

Сериализовать с помощью pickle можно только переменные спецификации параметров, определённые в глобальной области видимости.

См. также

• 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
T = TypeVar("T")

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: Сразу после создания класса члены протокола с проверкой во время выполнения теперь считаются «замороженными». Добавление атрибутов в такой протокол с помощью monkey patching по-прежнему будет работать, но не повлияет на проверки 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

class Definition(TypedDict):
    __schema: str  # mangled to `_Definition__schema`

# OK, functional syntax
Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})
Definition = TypedDict('Definition', {'__schema': str})  # not mangled

По умолчанию в 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__, может работать неправильно, а значения атрибутов могут быть некорректными.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Псевдонимы абстрактных базовых классов контейнеров из 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.

Устарело с версии 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.

Подробные сведения об использовании collections.abc.Coroutine и typing.Coroutine в аннотациях типов см. в разделе Аннотирование генераторов и сопрограмм.

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

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

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

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

Подробные сведения об использовании collections.abc.AsyncGenerator и typing.AsyncGenerator в аннотациях типов см. в разделе Аннотирование генераторов и сопрограмм.

Добавлено в версии 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.

Подробные сведения об использовании collections.abc.Generator и typing.Generator в аннотациях типов см. в разделе Аннотирование генераторов и сопрограмм.

Устарело с версии 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 и Обобщённый тип псевдонима.