파이썬 타입 힌트(Type Hint) 완벽 정리 - 초보자가 꼭 알아야 할 핵심 개념부터 실전 사용 기준까지

1 타입 힌트란 무엇인가?

- 이 변수나 함수에 어떤 종류의 값이 오기를 기대하는지 미리 적어두는 표시

- 실행 규칙, 타입 강제, 오류 자동 발생이 없음

- 실행 결과는 타입 힌트와 무관함

- 사람과 IDE, 타입 검사 도구를 위한 설명서

---

2 타입 힌트는 '설명'이다

- '타입 힌트를 달면 자동으로 검사해 주겠지?'라고 많이 착각함

- 파이썬 인터프리터는 타입 힌트를 완전히 무시하고, 타입 힌트는 실행 흐름을 바꾸지 않음

- 타입 힌트의 진짜 역할은 코드의 의도를 설명하고, 자동 완성 정확도를 향상시키고, 실수를 사전에 경고함

---

3 여러 타입을 허용해야 할 때

1) Union

1-1 코드

value: int | str

- 여러 타입 중 하나일 수 있음

- 자동 변환과 자동 검사를 하지 않음

---

2) Optional (= None을 포함한 Union)

1-2 코드

user_id: int | None

- 값이 없을 수도 있음

- '선택'이 아니라 '없음 가능성'

---

4 컬렉션 타입 힌트 (list / tuple / set / dict)

2 코드

numbers: list[int]

- list와 set은 1개의 요소 타입을 가짐

- dict는 키 타입과 값 타입을 함께 가짐

- tuple은 위치별 타입 또는 반복 타입을 가짐

---

5 추상 컬렉션 (Iterable / Sequence / Mapping)

3 코드

from collections.abc import Iterable

def total(nums: Iterable[int]) -> int:

- '어떤 자료구조인가?'가 아니라 '무엇을 할 수 있어야 하는가?'로 사고를 전환행야 함

- Iterable은 순회만 가능함

- Sequence는 순서, 길이, 인덱싱이 가능함

- Mapping은 키로 값 조회가 가능함

- 즉, 구현이 아니라 요구 기능을 설명함

---

6 중첩 타입 힌트 읽는 법

- 항상 가장 바깥 타입부터 읽음

list[dict[str, list[int]]]

- 전체는 list, list의 요소는 dict, dict의 key는 str, dict의 value는 list[int]

- []는 구조 설명이지 실행 문법이 아님

---

728x90

7 타입 별칭 (Type Alias)

- 타입은 같은데 의미를 드러내고 싶을 때 사용함

4 코드

Email = str

- 새로운 타입이 아니며, 실행 변화가 없음

- 이 값의 역할 이름이며, 의도를 설명함

---

8 Literal 타입 (값 제한)

5 코드

from typing import Literal

Direction = Literal['left', 'right']

- 문자열이 아니라 정해진 값만 허용함

- 실행 중 강제하지 않으며, IDE / 타입 검사기용 힌트

---

9 함수 타입 힌트 확장 (Callable)

6 코드

from collections.abc import Callable

Handler = Callable[[int], int]

- 정수 하나를 받아서 정수를 반환하는 호출 가능한 대상을 의미함

- 고차 함수 / 콜백 / 전략 패턴에서 필수임

---

10 타입 흐름 이해 (Type Narrowing)

- 타입은 코드 위치에 따라 좁혀짐

7 코드

if x is not None:
    x + 1  # 여기서 x는 None 아님

- 타입이 바뀌는 게 아니라 가능한 후보가 제거되는 것이 핵심

- is None, isinstance, return / raise 등이 있음

---

11 TypedDict (dict 구조 설명)

8 코드

from typing import TypedDict

class User(TypedDict):
    name: str
    age: int

- 이 dict는 반드시 name, age를 가진 구조

- 실행 검사가 아니라 구조 설명이 맞음

- JSON / API 데이터 설명에 최적화되어 있음

---

12 dataclass + 타입 힌트

10 코드

from dataclasses import dataclass

@dataclass
class User:
    name: str
    age: int

- 반복되는 코드를 자동으로 생성함

- 타입 힌트는 필드 선언과 같음

- dataclass는 타입 검사를 하지 않고, 구조를 자동으로 생성함

---

13 제네릭 (TypeVar)

11 코드

from typing import TypeVar

T = TypeVar('T')

def identity(x: T) -> T:
    return x

- 아무 타입이 아니라 들어온 타입을 유지함

- Union은 범위랑 같고, Generic은 관계랑 같음

---

14 Protocol (덕 타이핑 공식화)

12 코드

from typing import Protocol

class Runnable(Protocol):
    def run(self) -> None:
        ...

- run() 메서드를 가진 객체라면 OK

- 상속이 아니라 구조가 기준

- '무엇을 할 수 있는가?'를 설명함

---

15 클래스 보조 타입

- ClassVar는 클래스 공유 값

- Final은 변경을 금지하는 것을 의도함

- NewType은 의미를 구분함

- Annotated는 타입과 설명이 합쳐짐

- 실행에는 영향이 없고, 설계 의도를 표현함

---

16 타입 힌트 vs 런타임 검사

구분	타입 힌트	런타임 검사
시점	실행 전	실행 중
역할	설명	보호
강제	X	O

- 타입 힌트는 검사가 아님

- 런타임 검사는 반드시 코드로 작성함

---

17 자주 하는 실수 고치기

- 타입 힌트가 강제라고 착각하지 않기

- Optional을 사용하면 None 처리를 하기

- Any를 남용하지 않기

- 타입 힌트와 실제 코드를 일치시키기

- 타입 때문에 읽기가 쉬워지며, 읽기 쉬워지지 않으면 실패한 타입 힌트

---

18 언제 타입 힌트를 쓰는가? (최종 기준)

- 함수의 경계나 다른 사람이 읽을 코드나 반환값이 명확하지 않거나 데이터 구조가 있거나 값의 선택지가 제한되거나 나중에 고칠 가능성이 있으면 타입 힌트를 사용함

- 즉석 실험 코드나 아주 짧고 명확한 코드나 의미가 뻔한 지역 변수에는 타입 힌트를 쓰지 않음

---

Python 타입 힌트에 대해 더 상세한 설명을 원하는 분들은 아래 사이트에 접속하기

☞ Python 타입 힌트 -1

☞ Python 타입 힌트 -2

☞ Python 타입 힌트 -3

☞ Python 타입 힌트 -4

---

Python 타입 힌트 뿐만 아니라 다른 프로그래밍 언어에 대해 알고 싶은 분들은 아래 사이트에 접속하여 원하는 링크에 접속하기

☞ 프로그래밍 언어 정리 모음