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

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

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

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, результат имеет тип 'str'
concat(b"foo", b"bar")  # OK, результат имеет тип 'bytes'
concat("foo", b"bar")   # Ошибка, нельзя смешивать str и bytes

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

# Неверное использование AnyStr:
# Переменная типа используется только один раз в сигнатуре функции,
# поэтому не может быть «решена» проверщиком типов
def greet_bad(cond: bool) -> AnyStr:
    return "hi there!" if cond else b"greetings!"

# Лучший способ аннотировать эту функцию:
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")  # ОК
    run_query(literal_string)  # ОК
    run_query("SELECT * FROM " + literal_string)  # ОК
    run_query(arbitrary_string)  # ошибка проверки типов
    run_query(  # ошибка проверки типов
        f"SELECT * FROM students WHERE name = {arbitrary_string}"
    )

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

Подробнее см. PEP 675.

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

typing.Never¶

typing.NoReturn¶

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

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

from typing import Never  # или NoReturn

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

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

from typing import Never  # или NoReturn

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

def int_or_str(arg: int | str) -> None:
    never_call_me(arg)  # ошибка проверки типов
    match arg:
        case int():
            print("It's an int")
        case str():
            print("It's a str")
        case _:
            never_call_me(arg)  # OK, аргумент имеет тип Never (или 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())  # Раскрытый тип – "Foo"
reveal_type(SubclassOfFoo().return_self())  # Раскрытый тип – "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 здесь была бы некорректной аннотацией возврата,
    # так как возвращаемый объект всегда является экземпляром Eggs,
    # даже в подклассах.
    def returns_eggs(self) -> "Eggs":
        return Eggs()

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

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

typing.TypeAlias¶

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

Например:

from typing import TypeAlias

Factors: TypeAlias = list[int]

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

from typing import Generic, TypeAlias, TypeVar

T = TypeVar("T")

# "Box" ещё не существует,
# поэтому для прямой ссылки на Python <3.12 приходится использовать кавычки.
# Использование ``TypeAlias`` сообщает тайпчекеру, что это объявление псевдонима типа,
# а не присваивание переменной строкового значения.
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.

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

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

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  # Конструктор на самом деле возвращает 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

# Используйте эту блокировку, чтобы гарантировать, что только один поток выполняет функцию
# в любой момент времени.
my_lock = Lock()

def with_lock[**P, R](f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
    '''Типобезопасный декоратор, предоставляющий блокировку.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        # Передайте блокировку в качестве первого аргумента.
        return f(my_lock, *args, **kwargs)
    return inner

@with_lock
def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:
    '''Складывайте список чисел потокобезопасным способом.'''
    with lock:
        return sum(numbers)

# Нам не нужно передавать блокировку вручную благодаря декоратору.
sum_threadsafe([1.1, 2.2, 3.3])

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

См. также

• PEP 612 – Переменные спецификации параметров (PEP, в котором были введены ParamSpec и Concatenate)

• ParamSpec

• Аннотация вызываемых объектовAnnotating callable objects

typing.Literal¶

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

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

Например:

def validate_simple(data: Any) -> Literal[True]:  # всегда возвращает True
    ...

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

open_helper('/some/path', 'r')      # Проходит проверку типов
open_helper('/other/path', 'typo')  # Ошибка в тайпчекере

Literal[...] нельзя наследовать. Во время выполнения произвольное значение допускается в качестве аргумента типа для Literal[...], но проверяющие типа могут накладывать ограничения. См. PEP 586 для получения дополнительных сведений о литеральных типах.

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

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

typing.ClassVar¶

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

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

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

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

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

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

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

typing.Final¶

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

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

Например:

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

class Connection:
    TIMEOUT: Final[int] = 10

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

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

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

typing.Required¶

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

В основном это полезно для total=False TypedDict. Подробнее см. TypedDict и PEP 655.

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

typing.NotRequired¶

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

Подробнее см. TypedDict и PEP 655.

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

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

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

assert a1 != a2  # Порядок важен

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

Вложенные типы 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)]

# При использовании в аннотации типа тайпчекер будет обрабатывать "V" так же, как
# ``Annotated[list[tuple[int, int]], MaxLen(10)]``:
type V = Vec[int]

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

type Variadic[*Ts] = Annotated[*Ts, Ann1] = 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"
    if isinstance(val, str):
        # Тип ``val`` сужается до ``str``
        ...
    else:
        # Иначе тип ``val`` сужается до ``float``.
        ...

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

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

1. Возвращаемое значение – boolean.

2. Если возвращаемое значение – True, то тип аргумента – это тип внутри TypeGuard.

Например:

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    '''Определяет, все ли объекты в списке являются строками'''
    return all(isinstance(x, str) for x in val)

def func1(val: list[object]):
    if is_str_list(val):
        # Тип ``val`` сужается до ``list[str]``.
        print(" ".join(val))
    else:
        # Тип ``val`` остаётся как ``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¶

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

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

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]
# Фактически делает:
tup: tuple[Unpack[Ts]]

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

# В старых версиях Python TypeVarTuple и Unpack
# находятся в пакете обратной совместимости `typing_extensions`.
from typing_extensions import TypeVarTuple, Unpack

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]         # Синтаксическая ошибка на Python <= 3.10!
tup: tuple[Unpack[Ts]]  # Семантически эквивалентно и обратно совместимо

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

from typing import TypedDict, Unpack

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

# Эта функция ожидает два именованных аргумента: `name` типа `str`
# и `year` типа `int`.
def foo(**kwargs: Unpack[Movie]): ...

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

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

Построение обобщённых типов и псевдонимов типов¶Building generic types and type aliases

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

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

class typing.Generic¶

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

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

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

Такой класс неявно наследуется от 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:
        ...
        # И т.д.

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

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

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

class Sequence[T]:  # T – это TypeVar
    ...

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

class StrSequence[S: str]:  # S – это TypeVar с верхней границей `str`;
    ...                     # можно сказать, что S "ограничен `str`"


class StrOrBytesSequence[A: (str, bytes)]:  # A – это TypeVar, ограниченный str или bytes
    ...

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

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

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

def repeat[T](x: T, n: int) -> Sequence[T]:
    """Возвращает список, содержащий n ссылок на x."""
    return [x]*n


def print_capitalized[S: str](x: S) -> S:
    """Печатает x с заглавной буквы и возвращает x."""
    print(x.capitalize())
    return x


def concatenate[A: (str, bytes)](x: A, y: A) -> A:
    """Складывает две строки или два объекта bytes."""
    return x + y

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

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

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

x = print_capitalized('a string')
reveal_type(x)  # выявленный тип – str

class StringSubclass(str):
    pass

y = print_capitalized(StringSubclass('another string'))
reveal_type(y)  # раскрытый тип – StringSubclass

z = print_capitalized(45)  # ошибка: int не является подтипом str

Верхней границей переменной типа может быть конкретный тип, абстрактный тип (ABC или протокол) или даже объединение типов:

# Может быть чем угодно с методом __abs__
def print_abs[T: SupportsAbs](arg: T) -> None:
    print("Absolute value:", abs(arg))

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

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

a = concatenate('one', 'two')
reveal_type(a)  # выявленный тип – str

b = concatenate(StringSubclass('one'), StringSubclass('two'))
reveal_type(b)  # выявленный тип – str, несмотря на то что передан StringSubclass

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

Во время выполнения 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 привязан к int, Ts привязан к ()
# Возвращаемое значение – (1,), тип которого tuple[int]
move_first_element_to_last(tup=(1,))

# T привязан к int, Ts привязан к (str,)
# Возвращаемое значение – ('spam', 1), тип которого tuple[str, int]
move_first_element_to_last(tup=(1, 'spam'))

# T привязан к int, Ts привязан к (str, float)
# Возвращаемое значение – ('spam', 3.0, 1), тип которого tuple[str, float, int]
move_first_element_to_last(tup=(1, 'spam', 3.0))

# Это не проходит проверку типов (и завершается ошибкой во время выполнения)
# потому что tuple[()] несовместим с tuple[T, *Ts]
# (требуется хотя бы один элемент)
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          # Недействительно
x: tuple[Ts]   # Недействительно
x: tuple[*Ts]  # Правильный способ сделать это

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

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]:  # Это нормально
    pass

class Array2[*Shape, DType]:  # Это тоже нормально
    pass

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

float_array_1d: Array[float, Height] = Array()     # Совершенно нормально
int_array_2d: Array[int, Height, Width] = Array()  # Да, тоже нормально

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

x: tuple[*Ts, *Ts]            # Недействительно
class Array[*Shape, *Shape]:  # Недействительно
    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.12.

Changed in version 3.12: Type variable tuples can now be declared using the type parameter syntax introduced by 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, или как параметры пользовательских обобщённых типов (Generics). См. Generic для получения дополнительной информации об обобщённых типах.

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

from collections.abc import Callable
import logging

def add_logging[T, **P](f: Callable[P, T]) -> Callable[P, T]:
    '''Типобезопасный декоратор для добавления логирования в функцию.'''
    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:
    '''Складывает два числа.'''
    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: Спецификации параметров теперь можно объявлять с помощью синтаксиса type parameter, введённого в PEP 695.

Примечание

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

См. также

• PEP 612 – Переменные спецификации параметров (PEP, в котором были введены ParamSpec и Concatenate)

• Concatenate

• Аннотация вызываемых объектовAnnotating callable objects

typing.ParamSpecArgs¶

typing.ParamSpecKwargs¶

Атрибуты аргументов и именованных аргументов (keyword arguments) объекта 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__¶

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

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

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

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

class typing.NamedTuple¶

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

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

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

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

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

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

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

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

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

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

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

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

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

Подклассы NamedTuple могут быть обобщёнными (generic):

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

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

# Для создания обобщённого NamedTuple в Python 3.11
T = TypeVar("T")

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

# Также поддерживается функциональный синтаксис
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: Добавлена поддержка обобщённых именованных кортежей (generic namedtuples).

class typing.NewType(name, tp)¶

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

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

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

UserId = NewType('UserId', int)  # Объявить NewType "UserId"
first_user = UserId(1)  # "UserId" возвращает аргумент без изменений во время выполнения

__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())  # Проходит статическую проверку типов

См. 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. Это позволяет выполнять простую структурную проверку, очень похожую на “one trick ponies” в 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'}  # ОК
b: Point2D = {'z': 3, 'label': 'bad'}           # Не проходит проверку типов

assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')

Чтобы разрешить использование этой возможности в старых версиях Python, которые не поддерживают PEP 526, TypedDict поддерживает две дополнительные эквивалентные синтаксические формы:

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

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

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

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

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

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

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

class Definition(TypedDict):
    __schema: str  # искажено до `_Definition__schema`

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

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

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

# Альтернативный синтаксис
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': NotRequired[str]})

Это означает, что Point2D TypedDict может не содержать ключ label.

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

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

# Альтернативный синтаксис
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

# Альтернативный синтаксис
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  # Класс, не являющийся TypedDict

class XY(X, Y): pass  # ОК

class XZ(X, Z): pass  # вызывает 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.