파이썬은 변수의 자료형을 미리 선언하지 않아도 실행할 수 있어 배우기 쉽고 개발 속도도 빠릅니다. 하지만 프로젝트가 커지면 함수에 어떤 값을 넣어야 하는지, 반환값이 없을 수도 있는지, 딕셔너리에 어떤 키가 들어 있는지 코드를 읽는 것만으로 파악하기 어려워집니다. 타입 힌트는 실행 시 자료형을 강제로 제한하는 기능이 아니라 코드의 입력과 출력 계약을 문서화하고 도구가 오류 가능성을 미리 찾도록 돕는 표기입니다.
함수의 경계를 먼저 표시하기
타입 힌트는 모든 지역 변수에 붙이기보다 여러 모듈이 만나는 함수와 클래스의 공개 인터페이스부터 적용하는 것이 효과적입니다. 예를 들어 def find_user(user_id: int) -> User | None처럼 작성하면 호출자는 정수 ID를 전달하고 결과가 없을 가능성을 처리해야 한다는 사실을 알 수 있습니다. 반환값이 없는 함수에는 -> None을 명시해 값을 기대하면 안 된다는 의도를 남깁니다.
파이썬은 기본 설정에서 타입 힌트와 다른 값도 실행할 수 있습니다. 따라서 외부 API, 환경 변수, JSON, 사용자 입력은 별도의 런타임 검증이 필요합니다. 타입 검사기는 코드 내부의 계약을 확인하고, 검증기는 신뢰할 수 없는 실제 데이터가 계약에 맞는지 확인한다고 구분하면 이해하기 쉽습니다.
컬렉션의 원소형까지 표현하기
list라고만 적으면 무엇이 들어 있는지 알기 어렵습니다. list[str], dict[str, int], tuple[int, int]처럼 원소와 키·값의 자료형을 함께 표현합니다. 함수가 읽기만 하는 연속 자료를 받는다면 구체적인 list보다 Sequence를 사용하면 튜플도 전달할 수 있습니다. 반대로 append가 필요한 함수라면 MutableSequence처럼 실제 요구 능력을 명확히 표현합니다.
타입 선택 체크포인트
- 값이 없을 수 있다면
T | None을 사용합니다. - 고정된 선택지는 Literal 또는 Enum을 고려합니다.
- 키 구조가 고정된 딕셔너리는 TypedDict로 표현합니다.
- 서로 다른 구현이 같은 동작을 제공하면 Protocol을 활용합니다.
- 모든 것을 허용하는 Any는 외부 경계에 제한적으로 둡니다.
Any가 오류를 숨기는 방식
Any는 어떤 연산도 허용하므로 타입 검사기의 보호가 그 지점에서 끊깁니다. 자료형 정보가 없는 라이브러리나 동적 JSON 때문에 Any가 필요할 수 있지만, 가능한 빨리 검증해 구체적인 자료형으로 바꿔야 합니다. 타입을 모른다는 의미라면 unknown에 가까운 object를 사용하고, isinstance 검사 후 처리하면 안전합니다.
실무 원칙: 타입 오류를 없애려고 Any를 늘리는 것은 경보기를 끄는 것과 같으므로, 불확실한 데이터의 범위를 좁히는 데 집중해야 합니다.
dataclass와 TypedDict의 역할 구분
dataclass는 애플리케이션 내부에서 행동과 데이터를 함께 다루는 객체에 적합합니다. 기본값, 비교, 불변 설정을 명확히 정의할 수 있습니다. TypedDict는 실행 시 일반 딕셔너리이며 JSON 응답처럼 키 기반 데이터의 정적 구조를 설명할 때 유용합니다. 외부 응답을 TypedDict로 표시했다고 실제 키가 보장되는 것은 아니므로 파싱 단계에서는 필수 키와 값 범위를 검사해야 합니다.
Protocol로 구현보다 기능에 의존하기
서비스가 특정 데이터베이스 클래스에 직접 의존하면 테스트 대체물을 만들기 어렵습니다. Protocol에 get이나 save처럼 필요한 메서드만 정의하면 상속 관계가 없어도 같은 형태를 가진 구현을 사용할 수 있습니다. 이 방식은 파일 저장소와 데이터베이스 저장소를 교체하거나 테스트용 가짜 객체를 주입할 때 도움이 됩니다. 인터페이스를 지나치게 크게 만들지 말고 사용하는 기능만 포함해야 합니다.
제네릭으로 자료형 관계 보존하기
입력과 출력 자료형이 서로 연결되는 함수는 TypeVar와 제네릭을 사용할 수 있습니다. 단순히 값을 그대로 반환하는 함수가 object를 반환한다고 쓰면 호출 결과의 구체적인 자료형을 잃지만, 제네릭 T를 사용하면 문자열을 넣었을 때 문자열로 추론됩니다. 다만 어려운 제네릭 표현이 실제 오류를 줄이지 못하고 가독성만 낮춘다면 작은 함수로 분리하는 편이 낫습니다.
다른 언어 및 API 연동 시 주의점
파이썬의 int는 매우 큰 정수를 다룰 수 있지만 JavaScript Number는 안전한 정수 범위가 제한됩니다. 큰 데이터베이스 ID는 JSON에서 문자열로 전달하는 정책을 고려합니다. datetime은 시간대 정보가 포함된 ISO 8601 문자열로 교환하고, Decimal은 부동소수점 오차를 피하도록 문자열 또는 명시된 최소 화폐 단위로 직렬화합니다. Python의 None은 JSON null과 연결되지만 필드 누락과 null을 구분해야 하는 API에서는 별도 모델링이 필요합니다.
도입 순서와 자동 검사
- 새로 작성하는 공개 함수의 인자와 반환값부터 표시합니다.
- None 가능성과 컬렉션 원소형을 구체화합니다.
- API 경계에 런타임 스키마 검증을 추가합니다.
- 타입 검사기를 느슨한 설정으로 실행해 기존 오류를 정리합니다.
- 모듈별로 엄격한 설정을 점진적으로 확대합니다.
- CI에서 타입 검사와 단위 테스트를 함께 실행합니다.
- 무분별한 ignore 주석은 이유와 제거 조건을 기록합니다.
mypy나 pyright 같은 검사기는 서로 설정과 추론 방식이 다를 수 있으므로 팀에서 하나를 정하고 버전을 고정합니다. 타입 검사 성공은 테스트를 대체하지 않습니다. 타입은 가능한 값의 모양을 확인하고 테스트는 실제 업무 결과와 예외 동작을 검증합니다. 둘을 함께 사용하면 리팩터링할 때 함수 계약이 깨진 위치와 행동이 달라진 위치를 각각 발견할 수 있습니다.
타입 힌트의 목적은 코드를 장황하게 만드는 것이 아닙니다. 사람이 기억해야 할 암묵적인 규칙을 코드에 옮겨 IDE와 검사기, 동료 개발자가 함께 확인하게 하는 것입니다. 외부 데이터는 검증하고 내부 계약은 구체적으로 표현하는 원칙을 지키면 파이썬의 유연함을 유지하면서도 실무 오류를 줄일 수 있습니다.
한 줄 요약: 파이썬 타입 힌트는 공개 함수와 외부 데이터 경계부터 적용하고 런타임 검증 및 테스트와 함께 사용할 때 가장 효과적입니다.