TypedDict란?

 

 

TypedDict는 Python에서 딕셔너리의 키와 값의 타입을 명확하게 정의할 수 있도록 해주는 기능입니다. typing.TypedDict를 사용하면, 특정 키가 어떤 타입의 값을 가져야 하는지 지정할 수 있습니다.

1. TypedDict 사용법

 

Python의 일반적인 딕셔너리는 어떤 키든, 어떤 값이든 저장할 수 있습니다. 하지만 TypedDict를 사용하면 정해진 키와 그에 대한 타입을 강제할 수 있습니다.

 

✅ 기본 예제

from typing import TypedDict

class User(TypedDict):
    name: str
    age: int
    email: str

user1: User = {"name": "Tom", "age": 30, "email": "tom@example.com"}  # ✅ 올바른 사용
user2: User = {"name": "Alice", "age": "25", "email": "alice@example.com"}  # ❌ age가 int가 아님

위 코드에서 User는 TypedDict로 정의된 딕셔너리입니다.

• name: str 타입이어야 함

• age: int 타입이어야 함

• email: str 타입이어야 함

 

만약 타입이 맞지 않는 값이 들어가면, 타입 체크 도구(예: mypy)가 오류를 감지합니다.

2. 선택적 키 (total=False)

 

기본적으로 TypedDict에 정의된 모든 키는 필수입니다. 하지만 total=False 옵션을 사용하면 일부 키를 선택적으로 만들 수 있습니다.

 

✅ 선택적 키 사용 예제

class User(TypedDict, total=False):
    name: str
    age: int
    email: str

user1: User = {"name": "Tom"}  # ✅ age, email이 없어도 됨
user2: User = {"name": "Alice", "age": 25}  # ✅ 일부 키만 포함 가능

위 코드에서 total=False를 사용했기 때문에, name, age, email 중 일부만 포함해도 됩니다.

3. 부분 선택적 키 (Python 3.11+)

 

Python 3.11부터는 Required[]와 NotRequired[]를 사용하여 일부 필드만 선택적으로 지정할 수 있습니다.

from typing import TypedDict, Required, NotRequired

class User(TypedDict):
    name: Required[str]  # 필수 키
    age: NotRequired[int]  # 선택적 키
    email: str  # 필수 키

user1: User = {"name": "Tom", "email": "tom@example.com"}  # ✅ age가 없어도 됨
user2: User = {"name": "Alice", "age": 25, "email": "alice@example.com"}  # ✅ 모두 포함 가능

• Required[str]: 반드시 포함해야 하는 키

• NotRequired[int]: 포함해도 되고, 생략해도 되는 키

4. 중첩 TypedDict 사용

 

TypedDict는 다른 TypedDict를 값으로 가질 수도 있습니다.

class Address(TypedDict):
    city: str
    zip_code: str

class User(TypedDict):
    name: str
    age: int
    address: Address  # 중첩 TypedDict

user: User = {
    "name": "Tom",
    "age": 30,
    "address": {
        "city": "New York",
        "zip_code": "10001"
    }
}  # ✅ 올바른 사용

User 딕셔너리의 address 필드는 Address 타입을 따라야 합니다.

5. TypedDict vs. 일반 dict

비교 항목일반 dictTypedDict

타입 검사	불가능	가능 (mypy 사용)
키 존재 여부 검사	불가능	가능 (total=False로 조정 가능)
중첩 구조	가능하지만 타입 보장 어려움	가능하고 타입 보장됨
런타임 동작	딕셔너리처럼 작동	딕셔너리처럼 작동

TypedDict는 런타임에서는 일반 딕셔너리와 동일하게 동작하지만, 정적 타입 검사기(mypy)가 타입을 체크할 수 있도록 도와줍니다.

6. 언제 TypedDict를 사용할까?

• 딕셔너리 구조를 엄격하게 관리하고 싶을 때

• JSON 데이터의 구조를 정의할 때

• API 응답 데이터를 다룰 때

• mypy와 함께 정적 타입 검사를 수행할 때

🔥 정리

• TypedDict는 딕셔너리의 키와 값의 타입을 강제하는 기능

• 기본적으로 모든 키가 필수지만, total=False나 NotRequired[]를 사용하여 선택적 키 가능

• 다른 TypedDict와 중첩 사용 가능

• 정적 타입 검사기(mypy)와 함께 사용하면 오류를 방지할 수 있음

 

TypedDict를 활용하면, 데이터 구조를 명확하게 정의하고 타입 안전성을 높일 수 있습니다! 🚀