[python] Pydantic 정리

🛣️ Pydantic 선택 이유

요즘 같은 AI 시대에는 스크립트 언어도 정적 타입을 이용하여 보다 명시적으로 코딩하려는 흐름이 있는 것 같다.

명세를 보다 명확히 작성하거나 테스트를 작성하는 일이 예전이면 병목인 작업이였다면,

요새는 AI의 도움으로 보다 안정적이며 더 빠르게 개발할 수 있는 수단이 되었다.

이런 흐름에 맞춰서 Javascript 진영에는 Typescript,Python 진영에는 Pydantic 인기가 부상한게 아닐까 싶다.

그러면 어떤 기능이 있는지 한 번 정리해보도록 하자.

 

✅ 1. 자동 데이터 파싱

단순한 타입 체크를 넘어, 입력된 값을 선언된 타입으로 강제 변환.

from pydantic import BaseModel

class Item(BaseModel):
    id: int
    name: str
    price: float
    is_available: bool

# 문자열 "100"과 "4500.50", "true"가 들어와도 자동으로 파싱됩니다.
external_data = {
    "id": "100", 
    "name": "모니터", 
    "price": "4500.50", 
    "is_available": "true"
}

# Pylance 경고가 발생!
# item = Item(**external_data)
# model_validate를 이용해 검증 및 변환 수행
item = Item.model_validate(external_data)

print(item.id)           # 100 (int)
print(item.price)        # 4500.5 (float)
print(item.is_available) # True (bool)

• BaseModel 상속을 통해서 Pydantic 기능 사용.
  • Pydantic의 기본 클래스이므로 필수적으로 상속
• item = Item(**external_data) Dictinary Unpacking을 사용하여도 되지만 Pylance를 통해 즉시 검증이 Validation 에러 발생
  • model_validate를 통해서 명시적으로 변환만 진행하도록 한다.

VSCode Pylance 확장, Pydantic 사용시 검증을 위한 필수 확장 프로그램

👓 model_validate 사용 시기

• 앞선 예제로 model_validate를 사용하면 검증 대신 변환만 명시적으로 진행한다
• 요청, 응답과 같이 인터페이스를 통한 데이터 입, 출력은 Pydantic Class 그대로 사용한다.
• 코드단에서 직접 데이터 가공하여 검증이 완료된 데이터인 경우에는 model_validate 를 사용하여 변환만 수행한다

➕ Camel 변환

서버단에서 흔히 사용하는 snake ↔ camel 변환이다.

python convention에 따라 내부에서는 snake case를 사용하고,

인터페이스 상에서는 camelCase 데이터를 송수신 하는 경우 유용하다.

def to_camel(value: str) -> str:
    head, *tail = value.split("_")
    return head + "".join(part.capitalize() for part in tail)

# CamelModel 정의
## alias_generator에 camel 변환 함수 연결
class CamelModel(BaseModel):
    model_config = ConfigDict(
        alias_generator=to_camel,
        populate_by_name=True,
    )

# CasemModel 상속
class ImgProcessingForm(CamelModel):
    prc_type: PrcType
    kernel_size: int | None = None\\

 

✅ 2. 중첩된 모델

복잡한 계층 구조를 가진 데이터를 객체 지향적으로 정의 가능.

from typing import List

class QuoteItem(BaseModel):
    product_name: str
    quantity: int

class Quote(BaseModel):
    quote_id: str
    vendor_name: str
    items: List[QuoteItem]  # 다른 Pydantic 모델을 리스트로 포함

data = {
    "quote_id": "Q-2026-001",
    "vendor_name": "삼성전자",
    "items": [
        {"product_name": "노트북", "quantity": 5},
        {"product_name": "마우스", "quantity": 10}
    ]
}

quote = Quote(**data)
print(quote.items[0].product_name)  # '노트북'

• 속성에 기존 모델을 활용해 데이터 구조 정의 (Quote.items)

 

✅ 3. 커스텀 유효성 검사

기본 타입 외에 비즈니스 로직(예: 수량은 0보다 커야 함)을 강제할 때 사용.

from pydantic import BaseModel, field_validator

class Inventory(BaseModel):
    stock: int

    @field_validator('stock')
    @classmethod
    def check_positive_stock(cls, v: int):
        if v < 0:
            raise ValueError('재고는 음수일 수 없습니다.')
        return v

# 에러 발생 예시
try:
    Inventory(stock=-5)
except ValueError as e:
    print(e)  # 재고는 음수일 수 없습니다.

 

✅ 4. 직렬화 (Serialization)

모델 객체를 다시 JSON이나 Dictionary로 변환하여 DB에 저장하거나 API 응답으로 보낼 때 사용.

# Pydantic V2 기준
quote_dict = quote.model_dump()      # Python dict로 변환
quote_json = quote.model_dump_json() # JSON 문자열로 변환

print(type(quote_dict)) # <class 'dict'>
print(quote_json)       # '{"quote_id":"Q-2026-001", ...}'

FastAPI에서는 라우터에서 BaseModel 객체를 반환하면 JSON 스키마로 자동 변환 됨.

class FileListResponse(BaseModel):
    has_more: bool = Field(..., description="다음 페이지 존재 여부")
    next_cursor_uploaded_at: datetime | None = Field(None, description="다음 커서 기준 업로드 시각")
    next_cursor_id: str | None = Field(None, description="다음 커서 파일 ID")

@router.get("/image-processing")
async def get_saved_images() {
	...
	
	return FileListResponse(...)
}

 

✅ 5. 환경 설정 관리

.env 파일이나 시스템 환경 변수를 읽어올 때 유용.

BsseSettings 클래스를 이용하여 설정 구성을 하면 된다.

pydantic-settings 패키지가 필요하며 FastAPI 설치 시 기본적으로 포함되어 있다.

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    app_name: str = "FastAPI Server"
    env: str = "local"
    debug: bool = True
    api_prefix: str = "/api"
    database_url: str = "postgresql://postgres:test1!@localhost:5434/postgres"

    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
    )
    
    # .env 파일을 통해서 설정도 가능
    # class Config:
	  #   env_file = ".env"

settings = Settings()

 

부록

OpenAPI

FastAPI에서는 기본적으로

Pydantic 기반으로 OpenAPI 스펙을 작성해주고 Swagger를 통해 확인할 수 있다.

<host>/docs 경로를 통해 swagger 화면을 확인할 수 있다.

Pydantic 설정에 따른 Swagger 화면

 

마무리

• python을 컴파일 타임에 검증 하기 위해서는 Pydantic이 필수
• FastAPI에서는 Pydantic 기반 OpenAPI 명세 자동화가 되어 있어 매우 편리
• 안정적이고 AI기반 빠른 개발을 위해서는 Pydantic은 선택이 아닌 필수.