Python Annotated vs Field

Annotated랑 Field 둘 다 메타데이터를 추가할 수 있음.

근데 목적과 사용처가 다름. 핵심만 보고 넘어가자.

---

1. Annotated: 타입에 메타데이터 추가

• 소속: typing.Annotated

• 목적: 타입 힌팅에 메타데이터 추가

• 사용처: 함수, 변수, 클래스 등 범용적

• 검증: 없음 (외부 라이브러리가 해석해야 함)

• 주로 FastAPI나 커스텀 검증 로직에서 메타데이터를 읽어 씀.

 

from typing import Annotated

def process_data(value: Annotated[int, "양수만 허용"]) -> None:
    print(value)

---

2. Field: Pydantic 필드 전용

• 소속: pydantic.Field

• 목적: 유효성 검사 + 메타데이터 추가 + 기본값 설정

• 사용처: Pydantic 모델 필드에만 사용 가능

• 검증: Pydantic이 직접 처리함

 

from pydantic import BaseModel, Field

class User(BaseModel):
    age: int = Field(..., ge=18, le=99, description="18세 이상만 허용")

---

 

언제 어떤 걸 쓸까?

• Pydantic 모델이면 → Field

• 타입 힌팅에 설명만 추가하려면 → Annotated

• 확장성과 검증 둘 다 필요하면 → Annotated + Field