타입 힌트는 어떻게 동작하며 그 이점은 무엇인가요?

Question

Accepted Answer

**타입 힌트(type hint)**(PEP 484+)는 변수, 함수 매개변수, 반환 값의 예상 타입을 주석으로 달 수 있게 합니다. 이들은 **선택적**이며 **런타임에 강제되지 않습니다** — Python은 실행 시 이들을 무시합니다 — 하지만 정적 분석, 더 나은 도구, 명확한 코드를 가능하게 합니다.

## 기본 문법

```python
def greet(name: str, times: int = 1) -> str:
    return name * times

age: int = 30
names: list[str] = ["Ann", "Bob"]
scores: dict[str, int] = {"math": 90}
```

`: type`은 매개변수/변수를, `-> type`은 반환을 주석으로 답니다. 이들은 의도를 문서화하고 도구에 의해 검사되지만, Python은 런타임에 이들을 **강제하지 않습니다**(잘못된 타입을 전달해도 그 자체로 오류가 발생하지 않음).

## 흔한 typing 구문

```python
from typing import Optional, Union, Callable, Any

def find(id: int) -> Optional[str]:    # str 또는 None (= 3.10+에서 str | None)
    ...

x: int | str                           # Union (3.10+ 문법)
handler: Callable[[int], bool]         # int를 받아 bool을 반환하는 함수
items: list[dict[str, int]]            # 중첩 제네릭
```

## 정적 타입 검사는 런타임 전에 버그를 잡음

```python
def add(a: int, b: int) -> int:
    return a + b

add("hello", 3)   # ✅ Python은 실행함 (그리고 충돌); ❌ mypy/pyright는 실행 전에 표시
```

**mypy**나 **pyright** 같은 타입 검사기는 힌트를 분석하여 코드를 실행하기 *전에* 타입 오류를 보고합니다 — 컴파일러처럼 일련의 버그(잘못된 인수 타입, None 오용)를 조기에 잡습니다.

## 이점

```text
✓ 정적 검사기(mypy, pyright)로 타입 버그를 조기에 잡음 — 런타임 전에
✓ IDE 지원 — 더 나은 자동완성, 리팩터링, 인라인 오류 감지
✓ 자체 문서화 코드 — 시그니처가 예상/반환을 정확히 보여줌
✓ 프레임워크 구동 — FastAPI/Pydantic이 검증 및 문서에 힌트를 사용함
✓ 대규모 코드베이스의 유지보수가 쉬워짐 (변경으로 인한 파손 감지)
```

## 선택적이고 점진적임

```text
힌트를 점진적으로 추가할 수 있음 — 몇몇 함수에만, 또는 엄격하게 모든 곳에.
주석 없는 코드도 여전히 동작함. "점진적 타이핑"은 시간을 두고 채택하기에 적합함.
```

## 프레임워크는 런타임에 이들을 활용함

```python
from pydantic import BaseModel
class User(BaseModel):
    name: str
    age: int            # Pydantic은 힌트를 사용하여 런타임에 데이터를 검증함
User(name="Ann", age="x")   # 검증 오류를 발생시킴
```

일부 라이브러리(Pydantic, FastAPI)는 타입 힌트를 읽어 데이터를 검증하고 문서를 생성합니다 — 런타임에 기능적으로 의미 있게 만듭니다.

## 왜 중요한가

타입 힌트는 Python의 동적 유연성을 희생하지 않고 정적 타이핑의 많은 이점을 가져옵니다: 타입 관련 버그를 조기에 잡고(mypy/pyright를 통해), IDE 도구와 리팩터링을 극적으로 개선하고, 살아 있는 문서 역할을 하며, 검증과 자동 생성 문서에 이들을 사용하는 현대적인 프레임워크(FastAPI, Pydantic)를 구동합니다.

선택적이고 Python 자체로는 런타임에 강제되지 않지만, 코드를 더 신뢰할 수 있고, 유지보수하기 쉽고, 자체 문서화되게 만들기 때문에 전문적이고 대규모인 Python 코드베이스에서 표준이 되었습니다 — 특히 프로젝트가 성장함에 따라 점점 더 기대되는 관행입니다.