Meaning
Attaches metadata (such as units or description) to a type hint without altering the underlying type, allowing static tools to interpret the annotation for documentation, validation, or code generation.
Primary Function
Type annotation metadata
Communicative Purpose
Adds contextual information to type hints for documentation, validation, or tooling.
Pattern
Annotated[; ;]
Core Structure
Annotated[; ;]
Função primária
Type annotation metadata
Propósito comunicativo
Adds contextual information to type hints for documentation, validation, or tooling.
Situações de gatilho
When you need to specify units for numeric values, when you want to tag variables with semantic meaning for linting, when you design APIs that rely on metadata for serialization or validation.
Contextos
Python libraries using pydantic, dataclasses, FastAPI, or any codebase leveraging typing extensions for runtime metadata.
Padrão
Annotated[; ;]
Estrutura central
Annotated[; ;]
Slots de substituição
first slot: type annotation (e.g., float, int, List[str]); second slot: metadata object (commonly a string literal describing units or semantics).
Colocados típicos
- function parameters
- variable annotations
- return type annotations
- used with pydantic.Field
- dataclasses.field.
Substituições comuns
- plain type hint
- NewType
- custom wrapper class
- or using a comment.
Erros comuns
forgetting to import Annotated from typing or typing_extensions; treating the annotated type as a distinct type at runtime; assuming the metadata affects type checking.
Similar / contraste
NewType (creates a distinct simple type) vs Annotated (adds metadata without changing type); typing.Union (combines types) vs Annotated (adds metadata).
Interferências
Coming from languages without type annotations (e.g., JavaScript, Ruby): may overlook the annotation or treat it as a comment; from languages with nominal typing (e.g., Java): may mistakenly believe Annotated creates a new subtype.
Família do chunk
- type hints
- NewType
- TypedDict
- Protocol
Nuance
Annotations are erased at runtime unless accessed via typing.get_type_hints; they do not influence isinstance or issubclass checks; they are purely static metadata for tools.
Efeito pragmático
Makes developer intent explicit (e.g., units) and enables libraries to validate or display metadata, reducing bugs related to unit mismatches.
Dica de memória
Think of labeling a value with its unit, like writing '5 meters' in code.
Nota
The metadata in Annotated is accessible via typing.get_type_hints() and is used by libraries like Pydantic for validation and serialization.
Upgrade path
Using pydantic.Field to add validation and metadata alongside Annotated.
Log in to save chunks.