JSON 구조를 Pydantic v2 BaseModel 또는 표준 라이브러리 @dataclass 코드로 옮겨 줍니다. 필드 이름은 파이썬 관례대로 snake_case로 바뀌고, 중첩 객체는 각각의 클래스로 정의됩니다.
FastAPI 요청·응답 스키마를 잡을 때, requests나 httpx로 받은 응답에 타입 힌트를 붙이고 싶을 때, 크롤링·ETL 스크립트에서 dict 키를 문자열로 찾아다니는 코드를 정리할 때 쓰기 좋습니다.
타입 이름에 최상위 모델 이름을 적습니다(예: Forecast).스타일에서 Pydantic (v2) 또는 dataclass를 고릅니다. 검증·별칭이 필요하면 Pydantic, 의존성 없이 가볍게 쓰려면 dataclass입니다.models.py 같은 모듈에 넣습니다. 스타일과 타입 이름은 주소에 저장됩니다.{
"city": "Seoul",
"updatedAt": "2024-05-01T09:00:00+09:00",
"current": { "temp": 18.5, "humidity": 40 },
"hourly": [
{ "hour": 10, "temp": 19, "rain_mm": 0 },
{ "hour": 11, "temp": 20.5, "rain_mm": 0.4, "alert": "shower" }
]
}from __future__ import annotations
from pydantic import BaseModel, ConfigDict, Field
class Hourly(BaseModel):
hour: int
temp: float
rain_mm: float
alert: str | None = None
class Current(BaseModel):
temp: float
humidity: int
class Forecast(BaseModel):
model_config = ConfigDict(populate_by_name=True)
city: str
updated_at: str = Field(alias="updatedAt")
current: Current
hourly: list[Hourly]
updatedAt은 updated_at 필드가 되고 Field(alias="updatedAt")로 원래 키와 연결됩니다. hourly의 temp는 정수와 소수가 섞여 float가 되었고, 두 번째 항목에만 있는 alert는 str | None = None입니다. 하위 클래스가 먼저 나오도록 순서가 뒤집혀 있습니다.
Field(alias=...)를 쓰고 model_config = ConfigDict(populate_by_name=True)를 넣어 파이썬 이름으로도 값을 채울 수 있게 합니다.= None 필드를 뒤로 재배치해 TypeError: non-default argument 오류를 피합니다. 원래 키는 # JSON: "updatedAt" 주석으로 남깁니다.str, int, float, bool, list[...], 타입이 섞인 값은 Any.null이 섞인 필드는 X | None = None.class, from, type 같은 파이썬 예약어 키는 class_처럼 뒤에 _를 붙입니다.from __future__ import annotations를 넣어 클래스 정의 순서와 상관없이 타입을 참조할 수 있게 합니다.Root = list[RootItem] 같은 별칭을 만듭니다.프론트엔드와 합의한 JSON 예시로 BaseModel을 만들어 response_model=이나 엔드포인트 파라미터에 쓰면 OpenAPI 문서까지 함께 생깁니다.
Forecast.model_validate(resp.json())로 감싸 두면 API가 필드 타입을 바꿨을 때 어디서 깨졌는지 ValidationError가 필드 경로와 함께 알려 줍니다.
data["current"]["temp"]처럼 쓰던 코드를 forecast.current.temp로 바꾸면 에디터 자동완성과 mypy·pyright 검사가 동작합니다.
@dataclass는 중첩 dict를 자동으로 객체로 바꾸지 않습니다. Forecast(**data)를 하면 current는 여전히 dict이므로, 중첩 변환이 필요하면 Pydantic이나 dacite 같은 도구를 쓰세요.updatedAt)로 다시 내보내려면 model_dump(by_alias=True) 또는 model_dump_json(by_alias=True)를 호출해야 합니다.str | None 문법을 쓰므로 Pydantic 모델은 Python 3.10 이상을 기준으로 합니다.str로 나옵니다. Pydantic이라면 타입을 datetime으로 바꾸기만 해도 ISO 8601 문자열을 파싱합니다.class Config, parse_obj)은 만들지 않습니다.populate_by_name=True는 왜 들어가나요?별칭이 있는 필드는 기본적으로 별칭(updatedAt)으로만 값을 받습니다. 이 설정이 있으면 Forecast(updated_at=...)처럼 파이썬 이름으로도 생성할 수 있어 테스트 코드 작성이 편해집니다.
Optional[str]로 받고 싶어요.str | None과 Optional[str]은 같은 뜻입니다. 3.9 이하 호환이 필요하면 from typing import Optional을 추가하고 바꿔 쓰면 됩니다.
지원하는 스타일은 Pydantic v2와 dataclass 두 가지입니다. dataclass 출력의 필드 목록을 그대로 TypedDict나 @attrs.define 클래스로 옮기면 구조는 같습니다.
아니요. 변환 결과가 원래 키와 같으면 Field(alias=...)와 ConfigDict를 넣지 않고 rain_mm: float처럼 단순하게 나옵니다.