Python Literal과 Optional 완벽 가이드: 타입 안전성과 실전 활용

Python에서 타입 힌트는 점점 더 중요한 역할을 하고 있습니다. 특히 Pydantic이나 FastAPI처럼 타입 정보를 적극적으로 활용하는 프레임워크에서는, 올바른 타입 선언이 곧 서비스의 신뢰성과 직결됩니다.
이번 글에서는 그중에서도 Literal과 Optional 두 가지 키워드를 실제 예제와 함께 쉽게 풀어봅니다.

Literal이란?

특정 값 집합만 허용하고 싶을 때 사용하는 타입 힌트입니다.

예를 들어, 파라미터로 "queued", "processing", "done" 세 가지 값만 들어오길 원한다면 아래처럼 작성합니다.

from typing import Literal

def handle_status(status: Literal["queued", "processing", "done"]):
    print(f"현재 상태: {status}")

사용 예시

handle_status("queued")        # 정상
handle_status("invalid")       # 타입 검사 도구에서 에러 발생

• 장점:
  • 오타 방지 및 IDE 자동완성 지원
  • API에서 잘못된 값이 들어오는 실수를 미리 차단

FastAPI, Pydantic에서의 활용

from pydantic import BaseModel
from typing import Literal

class TaskEvent(BaseModel):
    event_type: Literal["start", "stop", "restart"]

• "start", "stop", "restart"만 허용
• 잘못된 값 입력 시 자동으로 검증 에러 반환

Optional이란?

**값이 없을 수도 있음(None 가능)**을 명시하는 타입 힌트입니다.
사실상 Union[타입, None]의 줄임말로, 예를 들어 아래처럼 사용합니다.

from typing import Optional

def greet(name: Optional[str]):
    if name:
        print(f"Hello, {name}")
    else:
        print("Hello, stranger!")

사용 예시

greet("Alice")   # Hello, Alice
greet(None)      # Hello, stranger!

Pydantic에서의 활용

from pydantic import BaseModel
from typing import Optional

class UserInput(BaseModel):
    name: str
    age: Optional[int] = None  # 입력 생략 가능

• age 필드가 없어도 에러가 아님
• 타입은 int 혹은 None

요약 표: Literal vs Optional

함께 쓰는 예시

둘을 조합하여 더욱 견고한 타입 제한도 가능합니다.

from pydantic import BaseModel
from typing import Literal, Optional, Dict, Any

class TaskEventRequest(BaseModel):
    event_type: Literal["restart", "set_script", "new_task"]
    payload: Optional[Dict[str, Any]] = None

• event_type은 지정된 값만 허용
• payload는 있을 수도, 없을 수도 있음 (None)

마치며

이처럼 Literal과 Optional은 Python 타입 힌트에서 타입 안정성과 코드 명확성을 크게 높여줍니다.
특히 API 개발, 데이터 모델링에서 적극적으로 활용하면, 코드의 신뢰성과 유지보수성이 확실히 올라갑니다.

추가로 궁금하다면 Union, Annotated, TypedDict 등 다른 typing 도구까지 확장해서 적용해보는 것도 추천합니다.
코드의 목적에 맞는 타입 힌트 활용이, 더 건강한 Python 프로젝트의 첫걸음이 될 것입니다.