[Python] TypedDict - 각 키별 타입을 명시하는 타입 힌트 도구

TypedDict

1. 정의

• typing 모듈에서 제공하는 타입 힌트 도구로, 기본적으로 딕셔너리의 형태이다.
• 딕셔너리의 각 키별 값의 타입을 정적으로 명시할 때 사용할 수 있다.
• 즉, 일반 딕셔너리처럼 동작하면서도, 각 키에 어떤 타입의 값이 들어가야 하는지 타입 체커가 이해할 수 있게 해준다.
• 예를 들어 다음과 같은 구조를 표현할 때 유용하다.

"name"은 문자열
"level"은 정수
"items"는 문자열 리스트

• 다만, 런타임에서 타입을 강제하거나 에러를 내는 게 아닌 보조적인 설명 기능만을 수행한다.
• 실제 검사는 mypy나 pyright 또는 IDE 등의 정적 타입 검사 도구가 수행한다.

2. 기본 문법

• TypedDict 를 상속받아 새로운 클래스를 정의할 수 있다.

from typing import TypedDict

class Player(TypedDict):
    name: str
    level: int
    strength: int
    intelligence: int
    gold: int

p = Player()

• 이를 통해 생성된 인스턴스는 일반 딕셔너리와 같이 사용할 수 있다.

p["level"] = 10
p["name"] = "John"

print(p["level"])
# >> 10

3. 일반 Dictionary와의 차이점

(1) 키별 타입 지정

• 일반 딕셔너리는 모든 키와 값에 대해 일괄적인 타입 지정만 가능하다.

# 일반 Dictionary: 일률적임
scores: dict[str, int] = {"math":90, "english":80}

• 반면 TypedDict는 각 key마다 value에 대한 타입을 정할 수 있다.

# TypedDict: 각 키마다 다른 타입
class Player(TypedDict):
    name: str         # name 은 str형
    level: int        # level 은 int형
    strength: float   # strength 는 float형

(2) 정적 타입 검사 가능

• mypy 또는 pyright 와 같은 타입 검사기를 통해 타입 체크가 가능하다.
• 예를 들어 다음 코드는 타입 검사기에서 문제로 잡힐 수 있다.

class Human(TypedDict):
    name: str
    age: int

h: Human = {
    "name": "John",
    "age": "50",   # 타입 오류
}

(3) IDE 자동완성

• IDE의 자동완성 기능에, 인스턴스가 어떤 key를 가지고 있는지 힌트가 노출된다.
• 따라서 일반 딕셔너리보다 코드 작성이 편하며, 오류 가능성도 줄어든다.

4. 인스턴스를 만드는 방법

• 일반 딕셔너리와 같이 value를 채워넣기

from typing import TypedDict

class Human(TypedDict):
    name: str
    age: int
    hobby: list[str]

h = Human()
h["name"] = "John Doe"
h["age"] = 50
h["hobby"] = ["Piano", "Tennis"]

• 인스턴스에 대한 타입을 지정해주면서 딕셔너리 할당

from typing import TypedDict

class Human(TypedDict):
    name: str
    age: int
    hobby: list[str]

h: Human = {
    "name" : "John Doe",
    "age" : 50,
    "hobby" : ["Piano", "Tennis"]
}

• 클래스 인스턴스를 생성하듯이 초기화(초기화 값으로는 딕셔너리 들어감)

from typing import TypedDict

class Human(TypedDict):
    name: str
    age: int
    hobby: list[str]

h = Human({"name":"John Doe", "age":50, "hobby":["Piano", "Tennis"]})

5. 필수 키와 선택 키

• 필수 키와 선택 키를 지정하는 방법 : Required , NotRequired

from typing import TypedDict, NotRequired, Required

class UserInfo(TypedDict):
    name: Required[str]
    age: NotRequired[int]
    email: NotRequired[str]

• 전체 키를 선택 키로 만드는 방법 : total=False

from typing import TypedDict

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

• total 값을 주지 않는 경우, 모든 키는 기본적으로 필수 키

Reference

https://docs.python.org/3/library/typing.html