추가 데이터 타입

추가 데이터 타입 (Extra Data Types)

지금까지는 str, int, float, bool 같은 흔한 타입을 썼는데, FastAPI는 그것보다 훨씬 다양한 표준 Python 타입도 그대로 지원해요. 선언만 하면 나머지(에디터 지원, 요청 데이터 변환, 응답 데이터 변환, 데이터 검증, 자동 문서화)는 전부 FastAPI가 알아서 처리해요.

출처: 공식문서

다른 데이터 타입들 (Other data types)

FastAPI(정확히는 Pydantic)가 지원하는 추가 타입들을 살펴볼게요.

  • UUID: 표준 "범용 고유 식별자(Universally Unique Identifier)"로, 많은 데이터베이스와 시스템에서 ID로 흔히 쓰여요. 요청·응답에서는 str로 표현돼요.
  • datetime.datetime: Python의 datetime.datetime. 요청·응답에서는 ISO 8601 형식의 str로 표현돼요. 예: 2008-09-15T15:53:00+05:00.
  • datetime.date: Python의 datetime.date. 요청·응답에서는 ISO 8601 형식의 str로 표현돼요. 예: 2008-09-15.
  • datetime.time: Python의 datetime.time. 요청·응답에서는 ISO 8601 형식의 str로 표현돼요. 예: 14:23:55.003.
  • datetime.timedelta: Python의 datetime.timedelta. 요청·응답에서는 총 초 수를 나타내는 float로 표현돼요. Pydantic이 "ISO 8601 시간 차이 인코딩"으로도 표현할 수 있게 해 주는데, 자세한 내용은 Pydantic 문서에서 확인할 수 있어요.
  • frozenset: 요청·응답에서 set과 동일하게 취급돼요.
    • 요청에서는 리스트가 읽혀서 중복을 제거하고 set으로 변환돼요.
    • 응답에서는 set이 list로 변환돼요.
    • 생성되는 스키마에서는 set 값이 유일하다고(JSON Schema의 uniqueItems) 명시돼요.
  • bytes: 표준 Python bytes. 요청·응답에서는 str로 취급돼요. 생성되는 스키마에서는 binary "형식(format)"의 str로 명시돼요.
  • Decimal: 표준 Python Decimal. 요청·응답에서는 float와 동일하게 처리돼요.

유효한 Pydantic 데이터 타입 전체 목록은 Pydantic 데이터 타입 문서에서 확인할 수 있어요.

예시 (Example)

이 타입들을 실제로 어떻게 쓰는지, 한 함수에 여러 타입을 섞어 본 예시를 볼게요:

from datetime import datetime, time, timedelta
from uuid import UUID

from fastapi import Body, FastAPI

app = FastAPI()


@app.put("/items/{item_id}")
async def read_items(
    item_id: UUID,
    start_datetime: datetime = Body(),
    end_datetime: datetime = Body(),
    process_after: timedelta = Body(),
    repeat_at: time | None = Body(default=None),
):
    start_process = start_datetime + process_after
    duration = end_datetime - start_process
    return {
        "item_id": item_id,
        "start_datetime": start_datetime,
        "end_datetime": end_datetime,
        "process_after": process_after,
        "repeat_at": repeat_at,
        "start_process": start_process,
        "duration": duration,
    }

함수 안의 파라미터는 자연스러운 데이터 타입 그대로예요. 그래서 예를 들어 평범한 날짜 연산을 바로 할 수 있어요.

  • start_process = start_datetime + process_after — datetime과 timedelta를 더하면 datetime이 나와요.
  • duration = end_datetime - start_process — 두 datetime을 빼면 timedelta가 나와요.

사용자가 JSON으로 보낼 때는 이 값들이 위에서 설명한 형태(예를 들어 item_id는 UUID 문자열, 날짜는 ISO 8601 문자열)로 옵니다. FastAPI가 자동으로 변환해 주니 우리는 Python 타입 그대로 다루면 돼요.

이렇게 하면:

  • item_id는 경로 파라미터의 UUID라서, 유효한 UUID가 아니면 오류가 나요.
  • start_datetime, end_datetime은 ISO 8601 날짜 문자열로 받아 datetime으로 변환돼요.
  • process_after 같은 timedelta는 초 수(float)로 받아요.
  • repeat_at은 시간 문자열로 받되 None이 허용되는 선택값이에요.

즉 클라이언트는 item_id에 UUID 문자열, start_datetime·end_datetime에 ISO 8601 날짜 문자열, process_after에 초 수(float), repeat_at에 시간 문자열을 보내면, FastAPI가 이를 각각 UUID, datetime, timedelta, time 타입으로 변환해서 우리 코드에 넘겨줘요. 응답으로 내보낼 때도 반대로 변환해서 JSON으로 직렬화돼요.

더 알아보기 (Learn more)