타입 힌트(Type Hint)란 무엇인가?
파이썬은 동적 타입 언어지만, 타입 힌트(Type Hinting)를 사용하면 코드의 의도를 명확히 표현할 수 있습니다.
Python 3.5 이상부터 도입된 타입 힌트는 에디터의 자동완성, 정적 분석, 문서 생성 등에 매우 유용하게 사용됩니다.
기본 예제
def add(a: int, b: int) -> int:
return a + b
해석:
a: int,b: int: 매개변수의 예상 타입-> int: 반환값의 예상 타입
이 힌트는 컴파일러에 영향을 주지는 않지만, 에디터, IDE, linter가 이를 활용해 오류를 미리 감지해줍니다.
복잡한 타입 사용
from typing import List, Dict, Optional
def get_scores(names: List[str]) -> Dict[str, int]:
return {name: 100 for name in names}
def find_user(name: str) -> Optional[str]:
if name == "admin":
return name
return None
List[str]: 문자열 리스트Dict[str, int]: 키가 str이고 값이 int인 딕셔너리Optional[str]: str 또는 None일 수 있음
정적 분석 도구(mypy)와 함께 사용하면 타입 오류를 사전에 차단할 수 있습니다.
타입 힌트를 실무에 적용하는 패턴
1. 클래스에 타입 힌트 적용
class User:
def __init__(self, name: str, age: int):
self.name = name
self.age = age
def greeting(self) -> str:
return f"안녕하세요, {self.name}님!"
해석:
클래스 생성자와 메서드에 타입 힌트를 추가하면, IDE에서 자동완성과 인자 체크가 가능해져 개발 생산성이 향상됩니다.
2. 타입 앨리어스 사용
from typing import Tuple
Coordinate = Tuple[float, float]
def distance(p1: Coordinate, p2: Coordinate) -> float:
return ((p1[0]-p2[0])**2 + (p1[1]-p2[1])**2) ** 0.5
Coordinate처럼 복잡한 타입을 별도로 정의해두면 코드 가독성이 좋아지고 재사용도 쉬워집니다.
3. mypy를 사용한 정적 타입 검사
pip install mypy
mypy myscript.py
mypy는 타입 힌트를 기반으로 코드에 타입 오류가 있는지 사전 검사해주는 도구입니다.
런타임 오류 없이 타입 문제를 미리 확인하고 싶은 경우 매우 유용합니다.
자동 문서화 도구 Sphinx / pdoc3 사용법
타입 힌트를 제대로 활용하면, 문서화 도구를 통해 함수, 클래스, 타입 정보까지 자동으로 문서화할 수 있습니다.
1. pdoc3 - 가장 간단한 문서화 도구
pip install pdoc3
pdoc --html mymodule.py --force
- 모듈의 docstring과 타입 힌트를 이용해 HTML 기반 API 문서를 자동 생성합니다.
- 브라우저에서 파일을 열면 시각적으로 정리된 문서를 확인할 수 있습니다.
2. Sphinx - 확장성과 커스터마이징에 강한 도구
설치 및 초기화
pip install sphinx
sphinx-quickstart
자동 문서화 확장 활성화
conf.py 파일에서 다음 항목을 추가하세요:
extensions = ["sphinx.ext.autodoc"]
모듈 문서 자동 생성
sphinx-apidoc -o docs/ your_module/
cd docs
make html
docs/_build/html/index.html에서 문서를 확인할 수 있습니다.
클래스, 함수, 주석, 타입 힌트까지 자동으로 문서화되므로 팀 개발에 매우 유용합니다.
3. 타입 힌트 + 문서화를 함께 사용할 때 장점
- IDE의 자동완성 + 정적 검사 + 문서 자동화 → 생산성 3배
- 협업 시 코드 설명이 필요 없어지고, 유지보수도 쉬워짐
- 오픈소스 배포 시 신뢰도 있는 프로젝트 구조 제공