typing.Annotated

Annotated из модуля typing в Python предназначен для добавления метаданных к аннотации. Метаданные, добавленные с помощью Annotated, могут быть использованы инструментами статического анализа или во время выполнения. Во время выполнения метаданные хранятся в атрибуте __metadata__.

from typing import Annotated 

# Синтаксис: Annotated[тип_данных, метаданные]
def say_hello(name: Annotated[str, "this is just metadata"]) -> str:
    return f"Hello {name}"

Логика обработка метаданных зависит от фреймворка или библиотек, в которых используется Annotated. Если логики для обработки метаданных нет, то метаданные игнорируются.

Например, Annotated используется в Pydantic:

from typing import Annotated
from pydantic import Field, TypeAdapter

# Функция Field используется для настройки и добавления метаданных 
# к полям моделей. Field(gt=0) - значит greater than т.е. больше чем 0
PositiveInt = Annotated[int, Field(gt=0)]

# TypeAdapter предоставляет часть функциональности методов экземпляра
# BaseModel в т.ч. валидацию с использованием метаданных из Annotated
ta = TypeAdapter(PositiveInt)


print(ta.validate_python(1))
#> 1
print(ta.validate_python(-1))
#> pydantic_core._pydantic_core.ValidationError:

В первом случае вернёт 1, во втором ошибку валидации т.к. значение должно быть > 0.

Также Annotated используется в FastAPI.