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를 활용하면, 데이터 구조를 명확하게 정의하고 타입 안전성을 높일 수 있습니다! 🚀
