typing — 타입 힌트 지원

typing 모듈은 파이썬의 런타임 타입 힌트(type hints) 시스템에 표준 지원을 제공해요. 핵심 런타임 기능으로는 TypeAlias, Generic, Union, Callable 같은 유틸리티 타입들이 있고, 여러 가지 예시가 있습니다. 타입 힌트 철학에 대해 더 자세히 배우려면 다음 PEP들을 참고하세요(원문의 참고 목록 확인): PEP 483(타입 힌트의 이론), PEP 484(type hints), PEP 585(표준 컬렉션의 제너릭), PEP 613(explicit type aliases), PEP 604(X | Y 결합), PEP 612(parameter specification variables), PEP 695(type parameter syntax) 등.

출처: Python 표준 라이브러리 — typing

본문

기본 예시 (Examples)

한 함수가 하나 또는 float·int를 처리하거나 user-defined 클래스를 반환하도록 명시하려면 Union과 Optional(또는 3.10+의 | 문법)을 사용할 수 있어요.

from collections.abc import Callable
from typing import TypeAlias, TypeVar, Union, Optional

# 3.10+에서는 | 를 쓸 수도 있다:
# def notify(prefs: str | None) -> None:

def notify(prefs: Optional[str]) -> None:
    """prefs에 전달된 문자열(하나 또는 아무것도 없음)을 알림."""
    if prefs is None:
        print("사용자 기본 설정이 없음")
    else:
        print("사용자 기본 설정: " + prefs)

# Attribute 순서/타입을 기술하는 TypeAlias
Vector: TypeAlias = list[float]

def scale(scalar: float, v: Vector) -> Vector:
    return [scalar * num for num in v]

class typing.TypeVar(name) — 제네릭(Generic) 함수·클래스에서 쓰이는 타입 변수. T = TypeVar('T')처럼 선언하고 def first(a: T, b: T) -> T로 사용합니다. bound, covariant, contravariant 파라미터를 가질 수 있어요.
class typing.Generic — 제네릭 타입 파라미터를 갖는 클래스·함수·별칭의 추상 기본 클래스. class Stack(Generic[T]): ...처럼 사용.
class typing.AnyStr — str와 bytes를 포함하는 TypeVar.
class typing.Union — 여러 타입의 결합을 나타냅니다. Union[int, str]은 int 또는 str. (3.10+에선 int | str로도 씁니다.)
typing.Optional[X] — Union[X, None]의 단축형. 값이 X이거나 None일 때.
typing.Callable — 호출 가능한 타입. Callable[[int, str], bool]처럼 인자와 반환 타입을 지정.
typing.Any — 특수 타입. 어떤 타입도 될 수 있음을 나타냄.
typing.NoReturn — 결코 반환하지 않는 함수의 반환 타입.
typing.Never — 아무 값에도 할당하지 않는 타입 (3.11+).

특수 타입들 (Special typing primitives)

특수 형태 (Special forms) — Any, Union(|), Optional, Literal, Final, ClassVar, Tuple, Callable, Self, TypeAlias, TypeGuard, Concatenate, Annotated, Required, NotRequired, ReadOnly 등.
typing.Literal[...] — 정확한 값으로 제한하는 리터럴 타입. Literal['a', 'b'].
typing.Final — 재할당/서브클래스 재정의가 되지 않음을 나타내는 타입.
typing.Annotated[T, ...] — 타입에 추가 메타데이터를 붙이는 타입.
typing.Self — 현재 클래스 자신을 참조 (3.11+).
typing.ClassVar — 클래스 변수임을 나타냄.
typing.Tuple[X, Y, Z] / tuple[X, Y] — 튜플 타입.
typing.Protocol — 구조적 서브타이핑(구조가 일치하면 만족)을 위한 프로토콜 클래스.
typing.TypedDict — 딕셔너리의 고정 키·타입을 지정하는 타입.
typing.NamedTuple — 이름 붙은 튜플 타입 (collections.namedtuple과 유사).

제네릭 함수·클래스 정의하기

TypeVar와 Generic을 조합해서 재사용 가능한 제네릭 코드를 만들 수 있어요.

from typing import TypeVar, Generic

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self.items: list[T] = []

    def push(self, item: T) -> None:
        self.items.append(item)

    def pop(self) -> T:
        return self.items.pop()

재귀 타입과 순방향 참조 (Recursive types / forward references)

타입 별칭은 매핑이나 리스트 같은 다른 타입 안에 재귀적으로 포함될 수 있어요. 순방향 참조는 from __future__ import annotations를 쓰거나 문자열로 타입을 표현해 처리할 수 있어요.

함수·메서드 데코레이터 타입

typing.cast(typ, val) — 타입을 런타임에 변경하지 않고 힌트만 바꾸는 캐스트 함수.
typing.get_type_hints(obj, ...) — 함수·모듈·클래스의 타입 힌트를 딕셔너리로 반환.
typing.get_origin / typing.get_args — 제네릭 타입의 원형과 인자 추출.
typing.overload — 같은 함수의 여러 시그니처를 선언하는 데코레이터 (3.8+에서는 함수형 접근 @typing.overload).

typing — 타입 힌트 지원