Python 타입힌트: Type Alias와 TypedDict 활용하기

Python의 타입힌트(Type Hint)는 단순히 함수 인자나 반환 타입을 지정하는 것을 넘어, 타입 자체에 별칭(Alias)을 붙이거나
Dictionary 구조를 명확하게 정의할 수 있는 기능도 제공합니다. 이번 글에서는 Type Alias와 TypedDict를 중심으로 살펴보겠습니다.

 

Type Alias (타입 별칭)

Type Alias는 말 그대로 기존 타입에 별칭을 붙여서 새로운 타입처럼 사용하는 것입니다.
코드의 가독성을 높이고, 복잡한 타입 구조를 단순화하는 데 유용합니다.

# 간단한 타입 별칭 정의
UserId = int
Username = str

def get_user_info(user_id: UserId, name: Username) -> str:
    return f"{user_id}: {name}"

print(get_user_info(20, "준수"))  # "20: 준수

이 예제에서 UserId와 Username은 사실상 int, str과 동일하지만, 코드의 의도를 더 명확하게 표현할 수 있습니다.

 

Dict Alias (복잡한 타입 단순화)

Type Alias는 dict 구조에도 자주 쓰입니다.

from typing import Dict

# dict의 키와 값 타입을 명확히 정의
UserDict = Dict[str, str]

def show_user(user: UserDict) -> None:
    for key, value in user.items():
        print(f"{key}: {value}")

user = {"name": "민수", "email": "minsu@example.com"}
show_user(user)

 

TypedDict (딕셔너리 구조 정의)

TypedDict는 딕셔너리의 키와 값 타입을 더욱 엄격하게 정의할 수 있습니다.
특히 JSON 같은 구조화된 데이터를 다룰 때 유용합니다.

from typing import TypedDict

class Point(TypedDict):
    x: int
    y: float
    z: str

이제 Point 타입은 {"x": int, "y": float, "z": str} 구조를 반드시 따라야 합니다.

 

사용 예시

p1: Point = {"x": 10, "y": 3.5, "z": "A"}
print(p1)  # {'x': 10, 'y': 3.5, 'z': 'A'}

# 잘못된 경우 (타입 체크 에러 발생)
p2: Point = {"x": "wrong", "y": 3.5, "z": "B"}  # x가 int가 아니라서 오류

 

TypedDict와 선택적 키

TypedDict는 total=False 옵션을 통해 선택적 키(optional key)를 정의할 수도 있습니다.

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

# 모든 키를 안 넣어도 됨
user1: UserInfo = {"id": 2}
user2: UserInfo = {"name": "지수", "email": "test@example.com"}

정리

• Type Alias: 기존 타입에 별칭을 붙여 가독성과 의도를 명확히 함
• Dict Alias: Dict[str, str] 같은 복잡한 타입을 별칭으로 단순화
• TypedDict: 딕셔너리 구조를 엄격히 정의 (특히 JSON, 설정 값, API 응답 등에서 유용)
• total=False를 활용하면 선택적 키도 지정 가능

Type Alias와 TypedDict를 잘 활용하면, 협업 시 데이터 구조를 더 명확히 문서화할 수 있고 IDE 자동완성 기능까지 강화됩니다.