Сообщить об ошибке.

Тип аннотации Annotated модуля typing в Python.

Типизация существующих типов контекстно-зависимыми метаданными.

Может использоваться как тип в аннотациях с помощью синтаксиса [].

Синтаксис:

from typing import Annotated

# новое в  Python 3.9.
Annotated[T, x]

Параметры:

  • T - тип данных Python,
  • x - контекстно-зависимые метаданные типа T.

Описание:

Тип аннотации Annotated() модуля typing представляет собой гибкие аннотации функций и переменных, для типизации существующих типов контекстно-зависимыми метаданными (возможно, несколькими их частями).

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

В отличие от функции typing.no_type_check(), которая полностью отключает аннотации проверки типов для функции или класса, тип Annotated позволяет как статическую проверку типов T (например, через сторонние модули mypy или Pyre, которые могут безопасно игнорировать x), так и доступ во время выполнения к x в конкретном приложении.

В конечном итоге ответственность за то, как интерпретировать аннотации, является обязанностью инструмента, проверяющего типизацию кода. Этот инструмент или библиотека, столкнувшиеся с Annotated, могут сканировать аннотации, чтобы определить, представляют ли они интерес (например, используя isinstance()).

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

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

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

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

Передача include_extras=True в get_type_hints() позволяет получить доступ к дополнительным аннотациям во время выполнения.

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

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

  • Поддерживаются аннотации нескольких типов (Annotated поддерживает переменные аргументы):

    Annotated[int, ValueRange(3, 10), ctype("char")]
    
  • Annotated должен вызываться как минимум с двумя аргументами. Запись Annotated[int] недействительна.

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

    Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
       int, ctype("char"), ValueRange(3, 10)
    ]
    
  • Вложенные аннотированные типы сглажены, а метаданные упорядочены, начиная с самой внутренней аннотации:

    Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
       int, ValueRange(3, 10), ctype("char")
    ]
    
  • Дублирующиеся аннотации не удаляются

    Annotated[int, ValueRange(3, 10)] != Annotated[
       int, ValueRange(3, 10), ValueRange(3, 10)
    ]
    
  • Annotated может использоваться с вложенными и универсальными псевдонимами:

    T = TypeVar('T')
    Vec = Annotated[list[tuple[T, T]], MaxLen(10)]
    V = Vec[int]
    
    V == Annotated[list[tuple[int, int]], MaxLen(10)]
    

Новое в Python 3.9.