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

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

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

typing.Any¶

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

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

• Any совместим со всеми типами устройств.

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

typing.AnyStr¶

A constrained type variable.

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

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

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

Например:

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

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

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

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

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

typing.LiteralString¶

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

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

Пример:

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

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

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

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

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

typing.Never¶

bottom type - тип, у которого нет членов.

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

from typing import Never

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

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

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

typing.NoReturn¶

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

Например:

from typing import NoReturn

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

NoReturn также может использоваться как bottom type, тип, который не имеет значений. Начиная с версии 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())  # Revealed type is "Foo"
reveal_type(SubclassOfFoo().return_self())  # Revealed type is "SubclassOfFoo"

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

from typing import TypeVar

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

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

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

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

• classmethod, которые используются в качестве альтернативных конструкторов и возвращают экземпляры параметра cls.

• Аннотирование метода __enter__(), который возвращает self.

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

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

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

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

typing.TypeAlias¶

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

Например:

from typing import TypeAlias

Factors: TypeAlias = list[int]

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

from typing import Generic, TypeAlias, TypeVar

T = TypeVar("T")

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

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

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

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

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

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

typing.Union¶

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

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

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

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

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

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

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

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

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

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

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

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

• Вы не можете написать Union[X][Y].

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

Изменено в версии 3.10: Союзы теперь можно записывать как X | Y. Смотрите union type expressions.

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: Необязательный теперь может быть записан как X | None. Смотрите union type expressions.

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

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

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

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

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

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

См.также

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

• ParamSpec

• Аннотирование вызываемых объектов

typing.Literal¶

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

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

Например:

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

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

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

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

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

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

typing.ClassVar¶

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

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

class Starship:
    stats: ClassVar[dict[str, int]] = {} # class variable
    damage: int = 10                     # instance variable

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

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

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

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

typing.Final¶

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

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

Например:

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

class Connection:
    TIMEOUT: Final[int] = 10

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

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

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

typing.Required¶

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

В основном это полезно для ввода total=False. Более подробную информацию смотрите в TypedDict и 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]  # NOT valid
  

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

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

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

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

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

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

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

См.также

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

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

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

typing.TypeGuard¶

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

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

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

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

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

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

1. Возвращаемое значение является логическим.

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

Например:

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

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

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

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

Примечание

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

TypeGuard также работает с переменными типа. Более подробную информацию смотрите в PEP 647.

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

typing.Unpack¶

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

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

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

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

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

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

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

Создание универсальных типов¶

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

class typing.Generic¶

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

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

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

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

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')  # Can be anything
S = TypeVar('S', bound=str)  # Can be any subtype of str
A = TypeVar('A', str, bytes)  # Must be exactly str or bytes

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

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


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


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

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

Переменные типа могут быть помечены как ковариантные или контравариантные, передавая covariant=True или contravariant=True. Более подробную информацию смотрите в разделе PEP 484. По умолчанию переменные типа являются инвариантными.

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

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

class StringSubclass(str):
    pass

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

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

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

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

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

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

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

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

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

__name__¶

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

__covariant__¶

Был ли тип var помечен как ковариантный.

__contravariant__¶

Был ли тип var помечен как контравариантный.

__bound__¶

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

__constraints__¶

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

class typing.TypeVarTuple(name)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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]):  # This is fine
    pass

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

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

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

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

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

Наконец, распакованный кортеж переменной типа type можно использовать в качестве аннотации типа *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__¶

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

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

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

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

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

P = ParamSpec('P')

Переменные спецификации параметров существуют в основном для проверки статических типов. Они используются для пересылки типов параметров одного вызываемого объекта другому вызываемому объекту - шаблон, обычно встречающийся в функциях и декораторах более высокого порядка. Они допустимы только при использовании в Concatenate, или в качестве первого аргумента Callable, или в качестве параметров для пользовательских обобщенных типов. Дополнительную информацию о обобщенных типах смотрите в 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]:
    '''A type-safe decorator to add logging to a function.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> T:
        logging.info(f'{f.__name__} was called')
        return f(*args, **kwargs)
    return inner

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

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

1. Средство проверки типов не может проверить ввод с помощью функции inner, потому что *args и **kwargs должны быть введены Any.

2. cast() может потребоваться в теле add_logging декоратора при возврате функции inner, или необходимо указать средству проверки статического типа игнорировать return inner.

args¶

kwargs¶

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

__name__¶

Название спецификации параметра.

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

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

Примечание

Можно выбрать только переменные спецификации параметров, определенные в глобальной области видимости.

См.также

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

• Concatenate

• Аннотирование вызываемых объектов

typing.ParamSpecArgs¶

typing.ParamSpecKwargs¶

Аргументы и атрибуты аргументов ключевого слова a 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.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__, задающий dict, который сопоставляет имена полей с типами полей. (Имена полей указаны в атрибуте _fields, а значения по умолчанию - в атрибуте _field_defaults, оба из которых являются частью API namedtuple().)

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

class Employee(NamedTuple):
    """Represents an employee."""
    name: str
    id: int = 3

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

NamedTuple подклассы могут быть универсальными:

class Group(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: Добавлена поддержка универсальных именованных наборов.

class typing.NewType(name, tp)¶

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

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

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

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

__module__¶

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

__name__¶

Название нового типа.

__supertype__¶

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

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

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

class typing.Protocol(Generic)¶

Базовый класс для классов протоколов.

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

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

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

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

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

func(C())  # Passes static type check

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

Классы протоколов могут быть универсальными, например:

T = TypeVar("T")

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

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

@typing.runtime_checkable¶

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

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

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

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

@runtime_checkable
class Named(Protocol):
    name: str

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

Примечание

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

Примечание

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

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

class typing.TypedDict(dict)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Отдельные клавиши a total=False TypedDict могут быть помечены как необходимые с помощью Required:

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

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

Тип TypedDict может наследоваться от одного или нескольких других типов TypedDict, используя синтаксис, основанный на классах. Использование:

class Point3D(Point2D):
    z: int

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

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

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

class X(TypedDict):
    x: int

class Y(TypedDict):
    y: int

class Z(object): pass  # A non-TypedDict class

class XY(X, Y): pass  # OK

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

Значение TypedDict может быть общим:

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: Добавлена поддержка общих TypedDicts.