TypedDict 사용하기

1. 기본 개념

TypedDict는 Python 표준 라이브러리 typing 모듈에 포함된 클래스입니다. 딕셔너리의 키와 값 타입을 명시적으로 정의할 수 있게 해주는 타입 힌트 도구입니다.

from typing import TypedDict

2. 기본 사용법

from typing import TypedDict

class Person(TypedDict):
    name: str
    age: int
    is_active: bool

person: Person = {
    "name": "Alice",
    "age": 30,
    "is_active": True,
}

런타임에는 일반 dict처럼 동작하고, 타입 체커(mypy, pyright)가 구조를 검증해줍니다.

3. TypedDict를 쓰지 않으면

일반 딕셔너리는 구조가 강제되지 않습니다.

# 어떤 키든 넣을 수 있어서 오탈자나 타입 오류를 잡기 어려움
person = {
    "nmae": "Alice",   # 오탈자 — 타입 체커가 잡지 못함
    "age": "30",       # 타입 오류 — 런타임 전까지 모름
}

TypedDict를 쓰면 이런 오류를 코드 작성 시점에 잡아줍니다.

4. 자주 쓰는 옵션

from typing import TypedDict

# total=False — 모든 키를 선택적으로 만들기
class Config(TypedDict, total=False):
    timeout: int    # 없어도 OK
    retries: int    # 없어도 OK

# Required / NotRequired — 키별로 선택적 지정 (Python 3.11+)
from typing import Required, NotRequired

class Item(TypedDict):
    id: Required[int]       # 필수
    description: NotRequired[str]  # 선택

5. 핵심 요약

한 줄 요약: TypedDict는 딕셔너리의 구조(키·타입)를 클래스처럼 선언해 정적 타입 검사를 가능하게 하는 도구로, LangGraph 상태 스키마 등 구조화된 데이터 정의에 자주 사용됩니다.