JYP Garden

Python Types Intro

Properties1
tagspython, type-hints, type-annotations, fastapi, ide-support, knowledge

7 min read

Python Type Hints — FastAPI 공식 가이드

학습 목표 매핑

SKALA 3기 Module 1 — Python AI Native (Learning Objective 1-1)

  • Objective: Python 타입 힌트(type hints)를 함수·클래스에 적용하고, IDE 자동완성·검증 도구 활용하여 모든 함수 파라미터·반환값에 타입 명시 (Bloom L2-L3)
  • Evaluation: 코드 리뷰 (타입 커버리지 90% 이상)

타입 힌트 개요

정의

**타입 힌트(Type Hints)**는 변수, 함수 매개변수, 반환값의 타입을 선언하는 특수한 구문입니다.

효과:

  • ✅ 에디터와 도구의 자동완성 지원
  • ✅ 오류 검사 및 타입 검증
  • ✅ 코드 문서화 및 가독성 향상
  • ✅ IDE의 smart hints 제공

기본 문법

콜론(:)을 사용하여 타입 선언 (등호 아님):

def get_full_name(first_name: str, last_name: str) -> str:
    full_name = first_name.title() + " " + last_name.title()
    return full_name

구조:

  • first_name: str — 매개변수 타입
  • -> — 반환 타입 지시
  • str — 반환값 타입

기본 타입들

Simple Types (단순 내장 타입)

def process_data(
    name: str,           # 문자열
    age: int,            # 정수
    height: float,       # 실수
    is_active: bool,     # 불린
    data: bytes          # 바이트
) -> None:              # 반환값 없음
    pass

Generic Types (제네릭 타입)

List (리스트)

def process_items(items: list[str]) -> int:
    # IDE는 items의 각 원소가 str임을 인식
    # → 자동완성에서 str의 메서드만 제안
    for item in items:
        print(item.upper())  # ✅ IDE가 str 메서드 제안
    return len(items)

Tuple (튜플)

def get_coordinates() -> tuple[int, int, str]:
    # 정확히 3개 요소: int, int, str
    return (10, 20, "label")

Dict (딕셔너리)

def process_prices(prices: dict[str, float]) -> None:
    # 키: str (상품명), 값: float (가격)
    for item_name, price in prices.items():
        print(f"{item_name}: ${price}")

Set (집합)

def get_unique_ids(ids: set[int]) -> None:
    for id in ids:
        print(id)

Union Types (여러 타입 지원)

def process_item(item: int | str) -> None:
    # int 또는 str 모두 허용
    print(item)
 
def greet(name: str | None = None) -> None:
    # str 또는 None (기본값: None)
    if name is not None:
        print(f"Hello {name}!")
    else:
        print("Hello World!")

클래스를 타입으로 사용

class Person:
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age
 
def get_person_name(one_person: Person) -> str:
    # Person 클래스의 인스턴스만 허용
    return one_person.name

Pydantic과의 연동

FastAPI의 핵심인 Pydantic을 사용한 데이터 검증:

from datetime import datetime
from pydantic import BaseModel
 
class User(BaseModel):
    id: int
    name: str = "John Doe"           # 기본값 설정
    signup_ts: datetime | None = None # Optional
    friends: list[int] = []          # 기본값 (빈 리스트)
 
# 자동 검증 및 타입 변환
external_data = {
    "id": "123",                      # 문자열 → 정수 변환
    "signup_ts": "2017-06-01 12:22", # 문자열 → datetime 변환
    "friends": [1, "2", b"3"],       # 유형 정규화
}
 
user = User(**external_data)
print(user)
# User(
#   id=123, 
#   name='John Doe', 
#   signup_ts=datetime(2017, 6, 1, 12, 22), 
#   friends=[1, 2, 3]
# )

Annotated로 메타데이터 추가

from typing import Annotated
 
def say_hello(
    name: Annotated[str, "this is just metadata"]
) -> str:
    return f"Hello {name}"

FastAPI에서의 활용

FastAPI는 타입 힌트를 다음에 사용합니다:

용도설명
요구사항 정의경로 매개변수, 쿼리 매개변수, 헤더, 바디 등
데이터 변환요청 데이터를 적절한 타입으로 자동 변환
데이터 검증유효하지 않은 데이터에 자동 오류 반환
API 문서화OpenAPI를 통한 자동 문서 생성 (Swagger UI)

IDE 자동완성 설정

PyCharm / VS Code 설정:

  1. Python 인터프리터 설정
  2. “Editor → Code Completion” 활성화
  3. 타입 힌트 추가 → IDE가 자동으로 제안

효과:

# 타입 힌트 있음 ✅
user: User = User(...)
user.n  # IDE 제안: name, ...
user.name.upper()  # IDE는 str 메서드만 제안
 
# 타입 힌트 없음 ❌
user = User(...)
user.n  # IDE가 제안 불가

학습 설계 포인트

Cognitive Level (Bloom)

  • L2 (Understand): 타입 힌트 문법 이해, 기본 타입 인식
  • L3 (Apply): 함수·클래스에 타입 힌트 적용

권장 실습

  1. 점진적 추가: 간단한 함수부터 타입 힌트 추가
  2. IDE 검증: IDE에서 오류 표시 확인
  3. 코드 리뷰: 팀 코드에서 타입 힌트 90% 이상 적용

도구

  • mypy: 정적 타입 검사 (pip install mypy)
  • pyright: VS Code 내장 타입 검사
  • IDE built-in: PyCharm, VS Code 자동완성

참고

선행 개념

이 개념을 배우기 전에 필수로 알아야 할 것:

  • Module 1-1 이전: 없음 (이것이 Module 1의 첫 번째 학습목표)
  • Python 기본 문법: 함수, 매개변수, 반환값 개념 (고등학교 프로그래밍 수준)

후속 개념 (이 개념이 선행)

이 개념을 배운 후 다음 단계:

  1. Module 1-4 → pydantic-validation-velog: 타입 힌트와 Pydantic 검증 통합
    • 예: def create_user(user: UserModel) -> UserModel 패턴에서 타입 힌트로 request/response 명시
  2. Module 4-1 → fastapi-docker-official-deployment: FastAPI의 타입 기반 자동 검증·문서화
    • 예: @app.post("/users/") 엔드포인트에서 타입 힌트로 요청 바디 검증

타 소스와의 연계

pydantic-validation-velog (데이터 검증 - 타입 힌트의 실제 사용) python-asyncio-daleseo (비동기 함수 타입 힌트)

그래프 뷰