Pythonは動的型付け言語であり、その柔軟性が大きな魅力です。しかし、プロジェクトが大規模になるにつれて、型に起因するバグが増加し、リファクタリングの難易度も上がります。型ヒント（Type Hints）は、Python 3.5で導入された機能で、変数や関数の型を明示的にアノテーションできます。
重要なのは、型ヒントはあくまでアノテーションであり、ランタイムの挙動には影響しないという点です。mypyなどの静的解析ツールと組み合わせることで、実行前にバグを検出できます。筆者のチームでは型ヒントの導入後、本番環境でのTypeError系のインシデントが約60%削減された。
まずは基本的な型アノテーションから見ていきましょう。
入会申込
ログイン# 変数の型ヒント
name: str = "Python"
age: int = 33
pi: float = 3.14159
is_active: bool = True
# 関数の型ヒント
def greet(name: str, times: int = 1) -> str:
return f"Hello, {name}! " * times
# コレクション型
from typing import Optional
numbers: list[int] = [1, 2, 3]
user_map: dict[str, int] = {"alice": 30, "bob": 25}
coordinates: tuple[float, float] = (35.6762, 139.6503)
unique_ids: set[str] = {"a1", "b2", "c3"}
# Optional型（Noneの可能性がある場合）
def find_user(user_id: str) -> Optional[dict]:
users = {"u001": {"name": "Alice"}}
return users.get(user_id)Python 3.10以降では、Optional[X]の代わりにX | Noneと書けます。よりシンプルで読みやすい構文です。
汎用的な関数を型安全に書くには、TypeVarを使う。
from typing import TypeVar, Sequence
T = TypeVar("T")
def first_element(items: Sequence[T]) -> T | None:
"""シーケンスの最初の要素を返す"""
return items[0] if items else None
# 型が自動的に推論される
result_int = first_element([1, 2, 3]) # int | None
result_str = first_element(["a", "b", "c"]) # str | NonePython 3.12からはTypeVarを明示的に宣言せずに、より簡潔な構文でジェネリクスを書けるようになった。
# Python 3.12以降の新しい構文
def first_element[T](items: Sequence[T]) -> T | None:
return items[0] if items else None実務でよく使うパターンをいくつか紹介します。
from dataclasses import dataclass, field
from datetime import datetime
from enum import Enum
class UserRole(Enum):
ADMIN = "admin"
EDITOR = "editor"
VIEWER = "viewer"
@dataclass
class User:
id: str
name: str
email: str
role: UserRole
created_at: datetime = field(default_factory=datetime.now)
tags: list[str] = field(default_factory=list)
def is_admin(self) -> bool:
return self.role == UserRole.ADMIN
def add_tag(self, tag: str) -> None:
if tag not in self.tags:
self.tags.append(tag)データクラスと型ヒントの組み合わせは非常に強力です。クラスのフィールドに型が明示されるため、IDEの補完が効き、mypyによる静的チェックも可能になります。
from typing import Callable, Protocol
# Callable型で関数の型を定義
def apply_operation(
values: list[float],
operation: Callable[[float], float]
) -> list[float]:
return [operation(v) for v in values]
# Protocol型で構造的部分型を定義
class Renderable(Protocol):
def render(self) -> str: ...
def render_all(items: list[Renderable]) -> str:
return "\n".join(item.render() for item in items)
# Renderableプロトコルを満たす任意のクラスが使える
class Button:
def __init__(self, label: str) -> None:
self.label = label
def render(self) -> str:
return f""
class TextBlock:
def __init__(self, text: str) -> None:
self.text = text
def render(self) -> str:
return f"{self.text}
"
# ButtonもTextBlockもRenderableとして扱える
html = render_all([Button("送信"), TextBlock("本文")])ProtocolはPythonにおける構造的部分型（ダックタイピングの型安全版）を実現します。明示的な継承なしに、必要なメソッドを持っていればその型として扱えます。これはPythonの柔軟性を損なわずに型安全性を得る素晴らしい仕組みです。
型ヒントの真価はmypyとの組み合わせで発揮されます。プロジェクトルートにmypy.iniを配置して設定します。
# mypy.ini
[mypy]
python_version = 3.12
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
# サードパーティライブラリのスタブがない場合
[mypy-some_untyped_library.*]
ignore_missing_imports = truestrict = trueは最も厳格な設定だが、新規プロジェクトでは最初からこの設定で始めることを推奨します。既存プロジェクトに段階的に導入する場合は、モジュール単位でdisallow_untyped_defsを有効化していくとよいです。
mypyをCI/CDパイプラインに組み込むことで、型エラーのあるコードがマージされるのを防げます。
# GitHub Actionsの例
name: Type Check
on: [push, pull_request]
jobs:
mypy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install mypy
- run: mypy src/ --strict既存プロジェクトへの導入は段階的に行うのが現実的です。以下の順序を推奨します。
型ヒントは書くのに時間がかかるように感じるかもしれないが、長期的にはデバッグ時間の短縮、リファクタリングの安全性向上、ドキュメンテーション効果によって、十分に元が取れる投資です。特にチーム開発では、コードの意図を型で伝えられることの価値は計り知れないです。まだ導入していないプロジェクトがあれば、今日からでも始めてみてほしい。
