[Python] Annotated - 타입 힌트에 메타데이터 붙이기

Annotated

1. 개념

• 타입 힌트에 추가 메타데이터를 붙이는 표준 방식
• 실제 타입은 유지하면서 특정 프레임워크나 검사기가 참고할 만한 정보를 담을 때 사용한다.

2. 문법

from typing import Annotated

x: Annotated[int, "0보다 큰 값"]
# 첫 번째가 타입
# 뒤의 값들은 메타데이터

• 실제 타입은 int형
• “0보다 큰 값”이라는 것은 부가 정보(메타데이터)
• 일반적인 파이썬 실행 자체(=런타임)에서는 메타데이터를 자동으로 검증하거나 강제하지 않는다.
• 대신, FastAPI나 Pydantic, LangGraph와 같은 프레임워크나 도구에서 이 메타데이터를 읽어 활용한다.

3. 활용

(1) 타입 힌트에 메타데이터 추가

• 변수(또는 인스턴스)의 타입, 그리고 값에 대한 설명을 추가할 때 사용한다.

from typing import Annotated

def greet(name: Annotated[str, "사용자 이름"]) -> str:
    return f"Hello, {name}"

(2) 검증 규칙

• 변수의 값에 대한 검증 규칙을 정의할 때 사용

from typing import Annotated
from pydantic import BaseModel, Field

class User(BaseModel):
    age: Annotated[int, Field(gt=0, lt=150)]

u = User(age=160)

# Error >> 
# ValidationError: 1 validation error for User
# age
#   Input should be less than 150 [type=less_than, input_value=160, input_type=int]
#     For further information visit https://errors.pydantic.dev/2.11/v/less_than

• 다만 파이썬 자체에서 검증 규칙을 검증하는 게 아니라, Pydantic이나 기타 프레임워크 차원에서 검증한다.

(3) 의존성 주입

from typing import Annotated
from fastapi import Depends

def get_db():
    ...

def read_users(db: Annotated[object, Depends(get_db)]):
    ...

4. Annotated 를 사용하는 이유

• 특정 필드에 대한 정보를 더 명확하게 해줄 수 있다.
• 메타데이터를 붙이는 표준화된 방식
• 정적 타입 검사와 런타임 프레임워크 사용을 분리해서 표현할 수 있다. 즉, 타입 검사기는 타입(Annotated의 첫 번째 인자)만 보고, 프레임워크 레벨에서는 그 뒤의 메타데이터들을 본다는 말.

Reference

https://docs.python.org/3/library/typing.html