Pythonの型ヒントを活用してコード品質を上げる

Pythonは動的型付け言語だが、型ヒント（Type Hints）を使うことで静的解析ツールによるバグ検出、IDEの補完精度向上、コードの可読性改善が得られる。本稿ではmypy・pyrightで使える実践的な型ヒントのパターンを整理する。

基本の型アノテーション

# 変数と関数の基本的な型ヒント
name: str = "Alice"
age: int = 30
score: float = 9.8
is_active: bool = True

def greet(name: str, count: int = 1) -> str:
    return f"Hello, {name}! " * count

# 戻り値なしの場合は None
def log_error(message: str) -> None:
    print(f"ERROR: {message}")

コレクション型

Python 3.9以降はlist[str]のように小文字で書ける。3.8以前はfrom typing import Listが必要。

from typing import Optional, Union

# Python 3.9+
def process_items(items: list[str]) -> dict[str, int]:
    return {item: len(item) for item in items}

# Optional（Noneを許容）
def find_user(user_id: int) -> Optional[str]:
    # None を返す可能性がある
    return None

# Union（複数の型を許容）
def parse_value(value: Union[str, int]) -> float:
    return float(value)

# Python 3.10以降はXでUnionを書ける
def parse_value_new(value: str | int) -> float:
    return float(value)

TypedDictとdataclass

辞書やデータ構造に型を与える2つの方法。

from typing import TypedDict
from dataclasses import dataclass

# TypedDict: 既存のdict互換が必要な場合
class UserData(TypedDict):
    id: int
    name: str
    email: str

def save_user(user: UserData) -> None:
    print(f"Saving: {user['name']}")

# dataclass: より多機能で推奨
@dataclass
class User:
    id: int
    name: str
    email: str
    is_active: bool = True

    def full_info(self) -> str:
        return f"{self.name} <{self.email}>"

Genericとプロトコル

from typing import TypeVar, Generic, Protocol

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

# Protocol: ダックタイピングの型安全な表現
class Serializable(Protocol):
    def to_json(self) -> str: ...

def send_response(data: Serializable) -> None:
    print(data.to_json())

mypyの設定と実行

# pyproject.toml
[tool.mypy]
strict = true          # 厳格モード（推奨）
python_version = "3.11"
ignore_missing_imports = true

# 実行
mypy src/
mypy --strict src/main.py

# pyrightはVS Code（Pylance）で自動有効、CLIでも使える
pyright src/

strictモードでは--disallow-untyped-defs（型なし関数をエラー）や--no-implicit-optional（Noneを暗黙に許容しない）などが自動的に有効になる。新規プロジェクトはstrictから始めるのが推奨だ。

---

まとめ

Pythonの型ヒントはstr・intなどの基本型から始め、Optional・Union・TypedDict・Genericと段階的に適用範囲を広げる。mypyまたはpyrightをCI/CDに組み込み、型エラーをコードレビュー前に検出する仕組みを整えることで、実行時エラーの削減とIDEの補完精度向上が得られる。既存コードへの導入は# type: ignoreコメントで部分的に抑制しながら漸進的に進めるのが現実的だ。