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

typing.Never¶

Нижний тип – тип, не имеющий членов.

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

from typing import Never

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

Новое в версии 3.11: В более старых версиях Python для выражения той же концепции может использоваться NoReturn. Never был добавлен, чтобы сделать предполагаемый смысл более явным.

typing.NoReturn¶

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

Например:

from typing import NoReturn

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

NoReturn также может использоваться как нижний тип, тип, не имеющий значений. Начиная с Python 3.11, для этой концепции следует использовать тип Never. Инструменты проверки типов должны считать их эквивалентными.

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

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

typing.TypeAlias¶

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

Например:

from typing import TypeAlias

Factors: TypeAlias = list[int]

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

from typing import Generic, TypeAlias, TypeVar

T = TypeVar("T")

# "Box" ещё не существует,
# поэтому для прямой ссылки приходится использовать кавычки.
# Использование ``TypeAlias`` сообщает тайпчекеру, что это объявление псевдонима типа,
# а не присваивание переменной строкового значения.
BoxOfStrings: TypeAlias = "Box[str]"

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

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

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

Специальные формы¶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, ParamSpec, TypeVar

P = ParamSpec('P')
R = TypeVar('R')

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

def with_lock(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
    ...

Mode: TypeAlias = 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.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
  
  T = TypeVar("T")
  Vec: TypeAlias = Annotated[list[tuple[T, T]], MaxLen(10)]
  
  assert Vec[int] == Annotated[list[tuple[int, int]], MaxLen(10)]
  

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

  Variadic: TypeAlias = 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')
  

См. также

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]]  # Семантически эквивалентно и обратно совместимо

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

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

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

class typing.Generic¶

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

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

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

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

X = TypeVar('X')
Y = TypeVar('Y')

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

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

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

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

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

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

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


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


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

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

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

Связанные переменные типа и ограниченные переменные типа имеют разную семантику в нескольких важных аспектах. Использование связанной переменной типа означает, что 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 или протоколами) и даже объединениями типов:

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

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

__bound__¶

Граница переменной типа, если она есть.

__constraints__¶

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

class typing.TypeVarTuple(name)¶

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

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

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]  # Правильный способ сделать это

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

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

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

DType = TypeVar('DType')
Shape = TypeVarTuple('Shape')

class Array(Generic[DType, *Shape]):  # Это нормально
    pass

class Array2(Generic[*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(Generic[*Shape, *Shape]):  # Недействительно
    pass

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

def call_soon(
         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.

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

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

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

P = ParamSpec('P')

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

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

from collections.abc import Callable
from typing import TypeVar, ParamSpec
import logging

T = TypeVar('T')
P = ParamSpec('P')

def add_logging(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.

Примечание

Только переменные спецификации параметров, определённые в глобальной области видимости, могут быть 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.

Другие специальные директивы¶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(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() (описано далее), действуют как простые протоколы времени выполнения, которые проверяют только наличие заданных атрибутов, игнорируя их сигнатуры типов.

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

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.

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  # имя с дефисами

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

По умолчанию все ключи должны присутствовать в 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 может быть обобщённым:

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.