Тип аннотации 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.