[모던 Python 2편] 타입 힌트와 Mypy로 코드 명확성 강화하기

과거 파이썬 코드에서는 타입 정보를 명시적으로 표기하지 않아도 자유롭게 코드를 작성할 수 있었습니다. 이는 유연하지만 대규모 프로젝트나 협업 상황에서 타입 불명확성으로 디버깅, 유지보수에 어려움을 줄 수 있었습니다. Python 3.5+에서 도입된 타입 힌트(Type Hints)를 사용하면 변수, 함수 인자, 반환값의 타입을 명시할 수 있고, 정적 분석 도구인 Mypy 등을 활용하면 런타임 전 코드 상의 타입 불일치를 감지할 수 있습니다.

이번 글에서는 전통적인 무타입 파이썬 코드와 타입 힌트를 적용한 코드의 차이를 비교하고, 타입 힌트를 통해 얻을 수 있는 장점과 단점을 정리한 뒤 Mypy 사용 예제를 살펴봅니다.

이전에는 어떻게 했을까?

무타입 코드 스타일

기본 파이썬 코드는 타입 선언이 없어도 자유롭게 동작합니다.

def greet(name):
    return "Hello " + name

• 장점: 타입 선언 부담 없음, 코드 작성 속도 빠름
• 단점: name이 문자열일 것으로 가정했지만, 실수로 정수나 리스트를 넘겨도 런타임 전에는 알 수 없음. 대규모 코드베이스에서 어느 함수가 어떤 타입을 기대하는지 문서나 주석에 의존해야 함.

주석 기반 타입 정보

과거에는 주석으로 타입 정보를 명시하거나 Sphinx 등 도구로 문서화하는 방식이 있었다.

def greet(name):
    # type: (str) -> str
    return "Hello " + name

하지만 주석 기반 방식은 정적 분석 도구 지원이 제한적이었고, 별도의 문법적 보장이 없어 유지보수성이 떨어졌다.

새로운 방식: 타입 힌트

Python 3.5부터 함수 인자와 반환 타입, 변수 타입을 정식 문법으로 표기할 수 있습니다.

def greet(name: str) -> str:
    return f"Hello {name}"

장점:

• 명확성 증가: 함수 시그니처만 봐도 어떤 타입을 기대하는지 즉시 파악 가능
• IDE 지원 강화: 타입 힌트 덕분에 IDE가 자동완성, 경고, 리팩토링에 도움
• 정적 분석 가능: Mypy 등 도구로 타입 불일치 문제를 사전에 발견해 런타임 오류 감소

단점:

• 추가 문법 부담: 개발 초기에는 타입 표기 습관화 필요
• 동적 특성을 살리는 Python 관점에서 다소 제약적으로 느껴질 수도 있음
• 런타임 오버헤드 없음: 타입 힌트는 정적 분석용이므로 런타임 퍼포먼스는 별도 영향 없음. 다만 정적 분석 도구 실행 시간이 필요.

Mypy로 정적 타입 체크하기

Mypy는 타입 힌트 기반으로 코드를 정적 분석하여 타입 불일치를 경고해주는 도구입니다.

설치:

pip install mypy

사용 예:

# my_module.py
def add(x: int, y: int) -> int:
    return x + y

def greet(name: str) -> str:
    return "Hello " + name

result = add(3, "4") # 의도치 않은 타입 불일치

이 코드를 mypy로 검사:

mypy my_module.py

결과:

my_module.py:8: error: Argument 2 to "add" has incompatible type "str"; expected "int"
Found 1 error in 1 file (checked 1 source file)

Mypy가 문자열 "4" 대신 정수 4를 기대한다고 알려주므로 코드 수정 전 오류를 감지할 수 있다.

타입 힌트 장단점 정리

장점:

• 유지보수성↑: 대규모 코드나 협업 시 함수 계약(Contract) 명시적
• IDE, LSP 지원 강화: 타입 기반 자동완성, 오류 감지 쉬움
• 사전 오류 감지로 QA 단계에서 버그 감소

단점:

• 추가 문법 부담: 타입 선언 습관화 필요
• 다이내믹한 Python 특성 일부 제한적 활용
• 기존 레거시 코드에 타입 추가 시 초기 작업량 증가

결론

타입 힌트는 모던 Python 코드베이스에서 점점 더 중요한 역할을 차지하고 있습니다. Mypy 같은 정적 분석 도구와 결합하면 대규모 프로젝트에서도 타입 안정성을 확보하고, 유지보수 난이도를 크게 낮출 수 있습니다. 만약 Python 3.6+ 이상을 사용 중이고 코드 품질 개선을 원한다면, 타입 힌트를 도입하고 Mypy 정적 분석을 정기적으로 실행하는 워크플로우를 고려해보세요.

다음 글에서는 dataclass를 이용해 데이터 구조 정의를 자동화하는 방법을 살펴보며, 보일러플레이트 코드를 줄이고 명확한 데이터 모델링을 하는 현대적 Python 스타일을 소개하겠습니다.