파이썬 타입 힌트(Type Hint) 완벽 정리 - 초보자를 위한 개념부터 실전까지 한 번에-3

다음 내용은 입력이 없고 정수를 반환하는 함수의 문법 예시, 그리고 입력으로 정수를 하나 받아 결과를 반환하지 않는 형태를 설명한다. 또한 users 가 리스트이고 각 요소가 User 구조를 따르는 dict라는 점, 파이썬 실행 중 강제 검사 없이 타입 힌트를 기준으로 구조가 명확해진다는 점이 강조된다. 이 패턴은 API 응답 목록, DB 조회 결과의 여러 행, JSON 데이터 배열 상황에 정확히 맞아떨어지므로 TypedDict 와 list 의 조합이 실전에서 가장 자주 등장하는 형태로 해석된다. list[User] 는 User 구조를 가진 딕셔너리들이 들어 있는 리스트이고, 그 dict 안에는 name 과 address, city 구조가 항상 유지된다는 뜻이다. TypedDict 의 목적은 문법 암기가 아니라 코드를 보는 순간 데이터 구조가 떠오르는 것을 돕는 설명 역할이며, 이를 보고 바로 이해되면 정확한 이해로 이어진다.

TypedDict의 한계로는 런타임에서 자동으로 검사하지 않는다는 점이 있다. 실행 중에는 에러를 발생시키지 않으며, TypedDict 는 실행 흐름을 바꾸지 않는 약속의 역할에 그친다. 또한 TypedDict 로도 dict 는 여전히 dict 이므로 새로운 키를 추가하고 삭제하는 등의 동작을 막지 못한다. TypedDict 는 데이터의 구조를 설명하는 도구일 뿐이며, 외부 API 데이터나 사용자가 입력한 값, JSON 파일의 데이터는 TypedDict 만으로 자동 안전성을 확보하지 못한다. 이 점은 실행 시 강제 대신 설계도 역할로 이해하는 것이 중요하다.

TypedDict 를 언제 쓰는가에 대한 실무 가이드는 API 요청/응답 데이터, JSON 데이터, 설정 데이터, 그리고 함수 인자나 반환값으로 dict 를 사용할 때의 상황을 포함한다. 구조가 미리 정해진 데이터가 다루어질 때 TypedDict 를 코드에 명시해 두면 키 이름과 값 타입 실수를 줄이고, 코드 설명서 역할을 하여 구조를 외우지 않아도 된다. 이와 함께 dataclass 와 타입 힌트의 관계도 함께 다룬다. dataclass 는 데이터만 담는 클래스를 만들 때 반복적으로 작성되는 초기화 코드나 출력 코드, 동일 데이터의 비교 코드를 자동으로 생성해 주어 개발을 돕는 도구로 소개된다.

dataclass 의 본질은 새로운 문법이 아니라 기존 클래스에 편의 기능을 추가하는 데코레이터이며, 타입 힌트 전체를 읽는 것이 아니라 어노테이션이 붙은 속성을 바탕으로 필드를 구성한다는 점이 강조된다. 타입 힌트는 실행 규칙이 아니라 dataclass 가 구조를 만들기 위한 정보로 사용되며, 타입 힌트가 없는 속성은 필드로 인식되지 않는다. dataclass 가 자동으로 생성하는 주요 메서드로는 __init__ , __repr__ , __eq__ 가 있으며, 기본 형태에서 필드 정보를 바탕으로 객체 생성과 비교, 출력이 편리하게 된다. 또한 dataclass 는 상속이나 기타 일반 클래스의 기능과의 호환성을 유지한다는 점도 명시된다.