Python 강좌 / 타입 힌트로 함수의 입력과 반환값 설명하기

타입 힌트는 변수와 함수의 입력·반환값에 기대하는 자료형을 표현합니다. 기본 Python 실행기는 힌트만으로 잘못된 입력을 차단하지 않으므로 정적 검사와 런타임 검증의 역할을 나눠야 합니다.

어노테이션과 실행 검사의 차이

amount: int는 정수를 기대한다는 정보를 제공하지만 자동 int 변환을 뜻하지 않습니다. -> str은 문자열 반환을 기대한다는 표현입니다. 편집기와 정적 검사 도구는 이 정보를 사용해 잘못된 호출을 찾을 수 있고 실제 외부 입력은 별도 검증이 필요합니다.

관련 동작과 지원 조건은 타입 힌트로 함수의 입력과 반환값 설명하기 관련 공식 문서에서 확인할 수 있습니다.

list[int]는 정수 목록, str | None은 문자열 또는 None을 나타냅니다. Python 3.12 이상을 기준으로 예제를 구성합니다. 실행 중 어노테이션의 평가 방식은 버전에 따라 달라질 수 있으므로 타입 정보 자체를 동적으로 해석하는 코드는 해당 버전 문서를 확인합니다.

전체 예제와 실행 결과

별도의 실습 폴더에서 아래 파일을 UTF-8로 저장합니다. 가상환경을 선택한 터미널에서 python hints.py 명령으로 실행합니다. macOS·Ubuntu에서 가상환경을 사용하지 않는 경우 명령 이름을 python3으로 바꿉니다.

hints.py 파일의 전체 내용입니다.

def format_amount(amount: int) -> str:
    if type(amount) is not int or amount < 0:
        raise ValueError("invalid amount")
    return f"{amount:,} KRW"

def find_name(names: dict[str, str], key: str) -> str | None:
    return names.get(key)

print(format_amount(8000))
print(find_name({"e1": "lunch"}, "missing"))
try:
    format_amount("8000")
except ValueError:
    print("rejected")

예상 결과는 다음과 같습니다.

8,000 KRW
None
rejected

정적 검사 도구 연결하기

예를 들어 가상환경에 mypy를 설치해 아래처럼 검사할 수 있습니다. 예제의 의도적인 문자열 호출은 정적 오류로 보고될 수 있습니다. 오류를 고치려면 호출 값을 정수로 바꾸거나 입력 변환을 명시하고, 단지 경고를 숨기려고 Any로 모두 바꾸지 않습니다.

python -m pip install mypy
python -m mypy hints.py

정적 검사 통과는 파일 존재·네트워크·업무 규칙이 항상 맞다는 보장이 아닙니다. 반대로 런타임 예제의 rejected 출력은 수동 검증 코드가 작동한 결과이지 어노테이션이 자동 차단한 결과가 아닙니다.

없을 수 있는 값과 입력 경계

find_name의 반환값이 None일 수 있으므로 문자열 메서드를 부르기 전에 검사해야 합니다. Optional한 값의 처리를 호출자가 놓치지 않도록 힌트와 실제 반환 규칙을 맞춥니다.

함수 반환형과 실제 반환 경로를 비교하고 모든 분기에서 계약을 지키는지 테스트합니다. 외부 JSON의 amount가 문자열일 때 허용할지 거부할지는 타입 힌트와 별도로 입력 정책으로 정합니다.