Python 타입 힌트: 타입 어노테이션 실전 가이드

# 타입 힌트 없음 - 이 함수는 무엇을 기대하는가?
def process_data(data, threshold, output):
    ...
 
# 타입 힌트 있음 - 즉시 명확함
def process_data(data: list[float], threshold: float, output: str) -> dict[str, float]:
    ...

# 기본 변수 어노테이션
name: str = "Alice"
age: int = 30
height: float = 5.9
is_active: bool = True
raw_data: bytes = b"hello"
 
# 할당 없는 어노테이션 (선언만)
username: str
count: int

def greet(name: str) -> str:
    return f"Hello, {name}!"
 
def calculate_average(numbers: list[float]) -> float:
    return sum(numbers) / len(numbers)
 
def save_record(record: dict[str, str], overwrite: bool = False) -> None:
    """의미 있는 값을 반환하지 않는 함수는 -> None을 사용합니다."""
    ...

def parse_config(path: str, encoding: str = "utf-8") -> dict[str, str]:
    config: dict[str, str] = {}
    with open(path, encoding=encoding) as f:
        for line in f:
            key, _, value = line.partition("=")
            config[key.strip()] = value.strip()
    return config

# 리스트
scores: list[int] = [95, 87, 92]
names: list[str] = ["Alice", "Bob"]
 
# 딕셔너리
user_ages: dict[str, int] = {"Alice": 30, "Bob": 25}
config: dict[str, list[str]] = {"servers": ["a.com", "b.com"]}
 
# 튜플 - 고정 길이와 특정 타입
point: tuple[float, float] = (3.14, 2.72)
record: tuple[str, int, bool] = ("Alice", 30, True)
 
# 가변 길이 튜플 (모두 같은 타입)
values: tuple[int, ...] = (1, 2, 3, 4, 5)
 
# 집합과 불변집합
tags: set[str] = {"python", "typing"}
constants: frozenset[int] = frozenset({1, 2, 3})

from typing import List, Dict, Tuple, Set, FrozenSet
 
scores: List[int] = [95, 87, 92]
user_ages: Dict[str, int] = {"Alice": 30}
point: Tuple[float, float] = (3.14, 2.72)
tags: Set[str] = {"python", "typing"}

# 행렬: float 리스트의 리스트
matrix: list[list[float]] = [[1.0, 2.0], [3.0, 4.0]]
 
# 사용자를 점수 리스트에 매핑
gradebook: dict[str, list[int]] = {
    "Alice": [95, 87, 92],
    "Bob": [78, 85, 90],
}
 
# 설정: 중첩된 딕셔너리
app_config: dict[str, dict[str, str | int]] = {
    "database": {"host": "localhost", "port": 5432},
    "cache": {"host": "redis.local", "port": 6379},
}

from typing import Optional
 
# 3.10 이전 문법
def find_user(user_id: int) -> Optional[str]:
    """사용자명을 반환하거나 찾지 못하면 None을 반환합니다."""
    users = {1: "Alice", 2: "Bob"}
    return users.get(user_id)
 
# Python 3.10+ 문법 (선호)
def find_user(user_id: int) -> str | None:
    """사용자명을 반환하거나 찾지 못하면 None을 반환합니다."""
    users = {1: "Alice", 2: "Bob"}
    return users.get(user_id)

from typing import Union
 
# 3.10 이전 문법
def format_value(value: Union[int, float, str]) -> str:
    return str(value)
 
# Python 3.10+ 문법 (선호)
def format_value(value: int | float | str) -> str:
    return str(value)
 
# 일반적인 패턴: 여러 입력 형식 허용
def load_data(source: str | Path) -> list[dict[str, str]]:
    path = Path(source) if isinstance(source, str) else source
    with open(path) as f:
        return json.load(f)

from typing import Any
 
def log_event(event: str, payload: Any) -> None:
    """모든 페이로드 타입을 허용 - 일반적인 로깅에 유용합니다."""
    print(f"[{event}] {payload}")
 
# Any는 모든 타입과 호환됩니다
log_event("click", {"x": 100, "y": 200})
log_event("error", 404)
log_event("message", "hello")

from typing import TypeVar
 
T = TypeVar("T")
 
def first_element(items: list[T]) -> T:
    """첫 번째 요소를 반환하며 타입을 보존합니다."""
    return items[0]
 
# 타입 체커가 올바른 반환 타입을 추론합니다
name = first_element(["Alice", "Bob"])     # type: str
score = first_element([95, 87, 92])        # type: int
 
# 바운드 TypeVar - 특정 타입으로 제한
Numeric = TypeVar("Numeric", int, float)
 
def add(a: Numeric, b: Numeric) -> Numeric:
    return a + b

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()
 
    def peek(self) -> T:
        return self._items[-1]
 
    def is_empty(self) -> bool:
        return len(self._items) == 0
 
# 특정 타입으로 사용
int_stack: Stack[int] = Stack()
int_stack.push(42)
value: int = int_stack.pop()
 
str_stack: Stack[str] = Stack()
str_stack.push("hello")

from typing import Callable
 
# 콜백을 받는 함수
def apply_operation(
    values: list[float],
    operation: Callable[[float], float]
) -> list[float]:
    return [operation(v) for v in values]
 
# 사용법
import math
results = apply_operation([1.0, 4.0, 9.0], math.sqrt)
# results: [1.0, 2.0, 3.0]
 
# 더 복잡한 콜러블 시그니처
Comparator = Callable[[str, str], int]
EventHandler = Callable[[str, dict[str, str]], None]
 
def sort_with_comparator(
    items: list[str],
    compare: Comparator
) -> list[str]:
    import functools
    return sorted(items, key=functools.cmp_to_key(compare))

from typing import Literal
 
def set_log_level(level: Literal["DEBUG", "INFO", "WARNING", "ERROR"]) -> None:
    print(f"Log level set to {level}")
 
set_log_level("INFO")      # OK
set_log_level("VERBOSE")   # 타입 오류: 유효한 리터럴이 아님
 
# 모드 매개변수에 유용
def read_file(
    path: str,
    mode: Literal["text", "binary"] = "text"
) -> str | bytes:
    if mode == "text":
        return open(path).read()
    return open(path, "rb").read()

from typing import TypedDict, NotRequired
 
class UserProfile(TypedDict):
    name: str
    email: str
    age: int
    bio: NotRequired[str]  # 선택적 키 (Python 3.11+)
 
def display_user(user: UserProfile) -> str:
    return f"{user['name']} ({user['email']}), age {user['age']}"
 
# 타입 체커가 구조를 검증합니다
user: UserProfile = {
    "name": "Alice",
    "email": "alice@example.com",
    "age": 30,
}
 
display_user(user)  # OK

from typing import Protocol, runtime_checkable
 
@runtime_checkable
class Drawable(Protocol):
    def draw(self, x: int, y: int) -> None: ...
 
class Circle:
    def draw(self, x: int, y: int) -> None:
        print(f"Drawing circle at ({x}, {y})")
 
class Square:
    def draw(self, x: int, y: int) -> None:
        print(f"Drawing square at ({x}, {y})")
 
def render(shape: Drawable, x: int, y: int) -> None:
    shape.draw(x, y)
 
# Drawable을 상속하지 않고도 둘 다 작동합니다
render(Circle(), 10, 20)
render(Square(), 30, 40)
 
# runtime_checkable은 isinstance 체크를 활성화합니다
print(isinstance(Circle(), Drawable))  # True

from typing import TypeAlias
 
# 간단한 별칭
UserId: TypeAlias = int
JsonDict: TypeAlias = dict[str, "JsonValue"]
JsonValue: TypeAlias = str | int | float | bool | None | list["JsonValue"] | JsonDict
 
# 복잡한 별칭은 시그니처를 단순화합니다
Matrix: TypeAlias = list[list[float]]
Callback: TypeAlias = Callable[[str, int], bool]
Config: TypeAlias = dict[str, str | int | list[str]]
 
def transform_matrix(m: Matrix, factor: float) -> Matrix:
    return [[cell * factor for cell in row] for row in m]
 
# Python 3.12+는 type 문을 사용합니다
# type Vector = list[float]

# mypy 설치
# pip install mypy
 
# 단일 파일 체크
# mypy script.py
 
# 전체 프로젝트 체크
# mypy src/
 
# 특정 Python 버전으로 체크
# mypy --python-version 3.10 src/

# pyproject.toml 설정
# [tool.mypy]
# python_version = "3.10"
# warn_return_any = true
# warn_unused_configs = true
# disallow_untyped_defs = true
# check_untyped_defs = true
# no_implicit_optional = true
# strict_equality = true
 
# 모듈별 오버라이드
# [[tool.mypy.overrides]]
# module = "third_party_lib.*"
# ignore_missing_imports = true

# 오류: 반환값 타입 불일치 (got "Optional[str]", expected "str")
# 수정: None 케이스 처리
def get_name(user_id: int) -> str:
    result = lookup(user_id)  # str | None 반환
    if result is None:
        raise ValueError(f"User {user_id} not found")
    return result  # mypy는 result가 str임을 알고 있습니다
 
# 오류: "Optional[str]"의 아이템 "None"은 "upper" 속성이 없습니다
# 수정: 먼저 타입을 좁히기
def format_name(name: str | None) -> str:
    if name is not None:
        return name.upper()
    return "UNKNOWN"
 
# 오류: 변수에 타입 어노테이션 필요
# 수정: 명시적 어노테이션 추가
items: list[str] = []  # 단순히 items = []가 아님
 
# 오류: 할당에서 타입 불일치
# 수정: Union 사용 또는 타입 수정
value: int | str = 42
value = "hello"  # 유니온 타입으로 OK
 
# 필요할 때 특정 오류 억제
x = some_untyped_function()  # type: ignore[no-untyped-call]

from fastapi import FastAPI
from pydantic import BaseModel
 
app = FastAPI()
 
class UserCreate(BaseModel):
    name: str
    email: str
    age: int
    tags: list[str] = []
 
class UserResponse(BaseModel):
    id: int
    name: str
    email: str
 
@app.post("/users", response_model=UserResponse)
async def create_user(user: UserCreate) -> UserResponse:
    # FastAPI는 UserCreate에 대해 요청 본문을 검증하고
    # UserResponse에 맞게 응답을 직렬화합니다
    return UserResponse(id=1, name=user.name, email=user.email)

import pandas as pd
from typing import Any
 
# 기본 DataFrame 타이핑
def clean_dataframe(df: pd.DataFrame) -> pd.DataFrame:
    return df.dropna().reset_index(drop=True)
 
# 스키마 검증을 위해 pandera 사용
# pip install pandera
import pandera as pa
from pandera.typing import DataFrame, Series
 
class SalesSchema(pa.DataFrameModel):
    product: Series[str]
    quantity: Series[int] = pa.Field(ge=0)
    price: Series[float] = pa.Field(gt=0)
    date: Series[pd.Timestamp]
 
@pa.check_types
def process_sales(df: DataFrame[SalesSchema]) -> DataFrame[SalesSchema]:
    """타입이 체크된 DataFrame 처리."""
    return df[df["quantity"] > 0]

# 실수: 타입 힌트가 있는 가변 기본값
def bad_append(item: str, items: list[str] = []) -> list[str]:
    items.append(item)  # 공유되는 가변 기본값!
    return items
 
# 수정: None을 기본값으로 사용
def good_append(item: str, items: list[str] | None = None) -> list[str]:
    if items is None:
        items = []
    items.append(item)
    return items

from typing import TypedDict, Callable, TypeAlias
from pathlib import Path
import csv
 
# TypedDict로 데이터 형태 정의
class RawRecord(TypedDict):
    name: str
    value: str
    category: str
 
class ProcessedRecord(TypedDict):
    name: str
    value: float
    category: str
    normalized: float
 
# 변환 함수를 위한 타입 별칭
Transform: TypeAlias = Callable[[list[ProcessedRecord]], list[ProcessedRecord]]
 
def load_csv(path: Path) -> list[RawRecord]:
    """타입이 지정된 출력으로 CSV 데이터 로드."""
    records: list[RawRecord] = []
    with open(path) as f:
        reader = csv.DictReader(f)
        for row in reader:
            records.append(RawRecord(
                name=row["name"],
                value=row["value"],
                category=row["category"],
            ))
    return records
 
def parse_records(raw: list[RawRecord]) -> list[ProcessedRecord]:
    """원시 문자열 레코드를 타입이 지정된 레코드로 변환."""
    max_value = max(float(r["value"]) for r in raw) or 1.0
    return [
        ProcessedRecord(
            name=r["name"],
            value=float(r["value"]),
            category=r["category"],
            normalized=float(r["value"]) / max_value,
        )
        for r in raw
    ]
 
def filter_by_category(
    records: list[ProcessedRecord],
    category: str
) -> list[ProcessedRecord]:
    """레코드 필터링, 완전히 타입이 지정된 입력과 출력."""
    return [r for r in records if r["category"] == category]
 
def apply_transforms(
    records: list[ProcessedRecord],
    transforms: list[Transform]
) -> list[ProcessedRecord]:
    """타입이 지정된 변환 함수 체인 적용."""
    result = records
    for transform in transforms:
        result = transform(result)
    return result
 
# 사용법
raw = load_csv(Path("data.csv"))
processed = parse_records(raw)
filtered = filter_by_category(processed, "electronics")

import pandas as pd
import pygwalker as pyg
 
# 타입이 지정된 파이프라인이 깔끔하고 구조화된 데이터를 생성
data: list[ProcessedRecord] = parse_records(raw)
df = pd.DataFrame(data)
 
# PyGWalker가 이를 대화형 시각화로 렌더링
walker = pyg.walk(df)