PythonのType Hints（型ヒント）は、大規模化するPythonコードベースで保守性を高める強力な仕組みです。mypy・pyrightといった型チェッカーと組み合わせれば、TypeScript並みの安全性が得られます。本記事では、実務で使えるType Hintsのテクニックを紹介します。
基本型と書き方
def greet(name: str, age: int) -> str:
return f"Hello, {name} ({age})"
names: list[str] = ["A", "B"]
mapping: dict[str, int] = {"a": 1}Optional / Union / リテラル
# Python 3.10+
def find_user(id: int) -> User | None:
...
# リテラル型
from typing import Literal
def set_mode(mode: Literal["dev", "prod"]) -> None:
...TypedDict
dictの構造を型として表現できます。JSONレスポンスや設定ファイルの型付けに最適。
from typing import TypedDict
class User(TypedDict):
id: int
name: str
email: str | None
def render(u: User) -> str:
return u["name"]dataclass / Pydantic
from dataclasses import dataclass
@dataclass
class Item:
id: int
name: str
price: float = 0.0
# Pydantic v2（バリデーションつき）
from pydantic import BaseModel
class Item(BaseModel):
id: int
name: str
price: float = 0.0ジェネリクス
# Python 3.12+ 新構文
def first[T](items: list[T]) -> T | None:
return items[0] if items else None
# 旧記法
from typing import TypeVar
T = TypeVar('T')
def first(items: list[T]) -> T | None: ...Protocol（構造的部分型）
from typing import Protocol
class HasName(Protocol):
name: str
def greet(x: HasName) -> str:
return f"Hi, {x.name}"型チェッカーの活用
- mypy：標準的な型チェッカー
- pyright：Microsoft製、VS Code（Pylance）の実体。高速
- ruff：lintツールだが基本的な型関連も警告
mypy src/
pyright src/実務でのコツ
- 新規コードはstrictモードで書き、徐々に既存コードに広げる
- publicな関数・APIの境界に型を必ず書く
- FastAPI・Pydantic・SQLModelなど型を活かすライブラリを選ぶ
- 型エラーをCIで検知
まとめ
PythonのType Hintsは、コードベースが大きくなるほど効果を発揮します。TypedDict・dataclass/Pydantic・Protocol・型チェッカーを押さえれば、TypeScriptに近い堅牢性を実現できます。新規プロジェクトでは最初から型を書く文化を作るのがおすすめです。
