Python型ヒント入門｜型アノテーションで保守性を高める実践ガイド

Pythonは動的型付け言語であり、変数に型を宣言せずともコードが動作します。この柔軟性は開発の初速を高めますが、プロジェクトが大規模化するにつれ、「この関数の引数は何型なのか」「戻り値は何が返ってくるのか」が不明瞭になり、バグの原因となります。

Python 3.5で導入された型ヒント（Type Hints）を使えば、コードの可読性と保守性を大幅に向上できます。本記事では、型ヒントの基本から実務での活用方法、mypyによる静的型チェックまでを解説します。

型ヒントとは？導入するメリット

型ヒント（Type Hints）は、関数の引数や戻り値、変数にどのような型のデータが入るかを注釈として記述する機能です。Python 3.5でPEP 484として導入されました。

型ヒントなし vs 型ヒントあり

# 型ヒントなし：引数と戻り値の型が不明
def calculate_tax(price, tax_rate):
    return price * (1 + tax_rate)

# 型ヒントあり：型が明確
def calculate_tax(price: float, tax_rate: float) -> float:
    return price * (1 + tax_rate)

型ヒントを導入するメリット

可読性の向上：関数のシグネチャを見るだけで、引数と戻り値の型がわかる
IDEの支援が強化：VS CodeやPyCharmの自動補完がより正確になる
バグの早期発見：mypyなどの静的解析ツールで実行前にエラーを検出できる
ドキュメントとしての機能：型情報がコードに埋め込まれるため、別途ドキュメントを維持する必要が減る
リファクタリングの安全性：型の不整合を検出することで、変更による影響範囲を把握しやすくなる

重要な点として、型ヒントはあくまで「注釈」であり、実行時にはチェックされません。型チェックを行うには、mypyなどの外部ツールを別途使用する必要があります。

基本的な型ヒントの書き方

プリミティブ型

# 変数の型ヒント
name: str = "田中太郎"
age: int = 30
height: float = 175.5
is_active: bool = True

# 関数の型ヒント
def greet(name: str) -> str:
    return f"こんにちは、{name}さん！"

# 戻り値がない関数
def log_message(message: str) -> None:
    print(f"[LOG] {message}")

コレクション型

Python 3.9以降では、組み込み型を直接ジェネリクスとして使えます。

# Python 3.9以降の書き方
names: list[str] = ["田中", "佐藤", "鈴木"]
scores: dict[str, int] = {"国語": 80, "数学": 90}
coordinates: tuple[float, float] = (35.6762, 139.6503)
unique_ids: set[int] = {1, 2, 3}

# 関数でのコレクション型
def get_average(scores: list[float]) -> float:
    return sum(scores) / len(scores)

def merge_configs(base: dict[str, str], override: dict[str, str]) -> dict[str, str]:
    result = base.copy()
    result.update(override)
    return result

Optional型とUnion型

from typing import Optional, Union

# Optional：Noneを許容する型
def find_user(user_id: int) -> Optional[dict]:
    """ユーザーが見つからない場合はNoneを返す"""
    users = {1: {"name": "田中"}, 2: {"name": "佐藤"}}
    return users.get(user_id)

# Python 3.10以降は | 記法が使える
def find_user(user_id: int) -> dict | None:
    users = {1: {"name": "田中"}, 2: {"name": "佐藤"}}
    return users.get(user_id)

# Union：複数の型のいずれかを許容
def format_value(value: Union[int, float, str]) -> str:
    return str(value)

# Python 3.10以降
def format_value(value: int | float | str) -> str:
    return str(value)

高度な型ヒント

TypedDict

辞書のキーと値の型を厳密に定義したい場合に使います。

from typing import TypedDict, Optional


class UserProfile(TypedDict):
    id: int
    name: str
    email: str
    age: Optional[int]


class UserProfilePartial(TypedDict, total=False):
    """すべてのキーがオプション"""
    name: str
    email: str
    age: int


def create_user(profile: UserProfile) -> None:
    print(f"ユーザー作成: {profile['name']} ({profile['email']})")


# 正しい使い方
user: UserProfile = {
    "id": 1,
    "name": "田中太郎",
    "email": "tanaka@example.com",
    "age": 30,
}
create_user(user)

Literal型

from typing import Literal


def set_log_level(level: Literal["DEBUG", "INFO", "WARNING", "ERROR"]) -> None:
    print(f"ログレベルを {level} に設定しました")


# OK
set_log_level("INFO")

# mypyでエラーとして検出される
# set_log_level("VERBOSE")


# 関数のオーバーロード的な使い方
def get_data(format: Literal["json", "csv"]) -> str:
    if format == "json":
        return '{"key": "value"}'
    else:
        return "key,value"

Callable型

from typing import Callable


def apply_operation(
    values: list[int],
    operation: Callable[[int], int],
) -> list[int]:
    """各要素にoperationを適用する"""
    return [operation(v) for v in values]


# 使用例
double = lambda x: x * 2
result = apply_operation([1, 2, 3], double)  # [2, 4, 6]


# コールバック関数の型定義
ErrorHandler = Callable[[Exception], None]

def process_data(data: list[str], on_error: ErrorHandler) -> list[str]:
    results = []
    for item in data:
        try:
            results.append(item.upper())
        except Exception as e:
            on_error(e)
    return results

ジェネリクス

from typing import TypeVar, Generic

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:
        if not self._items:
            raise IndexError("スタックが空です")
        return self._items.pop()

    def peek(self) -> T:
        if not self._items:
            raise IndexError("スタックが空です")
        return self._items[-1]

    @property
    def is_empty(self) -> bool:
        return len(self._items) == 0


# 使用例：型が推論される
int_stack: Stack[int] = Stack()
int_stack.push(1)
int_stack.push(2)
value: int = int_stack.pop()

str_stack: Stack[str] = Stack()
str_stack.push("hello")

dataclassと型ヒントの組み合わせ

dataclassは型ヒントと非常に相性が良く、データを格納するクラスを簡潔に定義できます。

from dataclasses import dataclass, field
from datetime import datetime
from typing import Optional


@dataclass
class Employee:
    id: int
    name: str
    department: str
    email: str
    age: int
    salary: float
    is_active: bool = True
    joined_at: datetime = field(default_factory=datetime.now)
    skills: list[str] = field(default_factory=list)
    manager_id: Optional[int] = None


# インスタンス作成（型が強制的にチェックされるわけではないが、IDEが支援する）
employee = Employee(
    id=1,
    name="田中太郎",
    department="開発",
    email="tanaka@example.com",
    age=30,
    salary=600.0,
    skills=["Python", "SQL"],
)

print(employee)
print(employee.name)  # IDEで型が推論される


@dataclass(frozen=True)
class Config:
    """変更不可な設定データクラス"""
    database_url: str
    debug: bool = False
    max_connections: int = 10
    allowed_origins: tuple[str, ...] = ("http://localhost:3000",)

mypyによる静的型チェック

mypyはPythonの型ヒントを静的に解析し、型の不整合をコードの実行前に検出するツールです。

インストールと基本的な使い方

# インストール
pip install mypy

# 型チェックの実行
mypy src/
mypy src/calculator.py

# 厳密モードで実行
mypy --strict src/

mypy設定（pyproject.toml）

[tool.mypy]
python_version = "3.12"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
show_error_codes = true

# サードパーティライブラリの設定
[[tool.mypy.overrides]]
module = ["pandas.*", "openpyxl.*"]
ignore_missing_imports = true

mypyが検出するエラーの例

def process_name(name: str) -> str:
    return name.upper()

# mypyエラー: Argument 1 to "process_name" has incompatible type "int"; expected "str"
result = process_name(42)

# mypyエラー: Incompatible return value type (got "Optional[str]", expected "str")
def get_name(user_id: int) -> str:
    users = {1: "田中"}
    return users.get(user_id)  # get()はOptional[str]を返す

# 修正版
def get_name(user_id: int) -> str:
    users = {1: "田中"}
    name = users.get(user_id)
    if name is None:
        raise KeyError(f"ユーザーID {user_id} が見つかりません")
    return name

実務での型ヒント導入戦略

既存プロジェクトに型ヒントを導入する場合、一度にすべてのコードに適用する必要はありません。段階的に導入していく戦略が現実的です。

段階的な導入手順

Phase 1：公開APIに型ヒントを追加
外部から呼び出される関数やクラスのインターフェースに型ヒントを追加します。
Phase 2：新規コードには必ず型ヒントを付ける
チーム内のコーディング規約として、新しく書くコードには型ヒントを必須とします。
Phase 3：CIにmypyを導入
段階的にmypyのチェック範囲を広げ、最終的にはstrict モードを目指します。

pyproject.tomlでの段階的設定例

# Phase 1: 緩い設定
[tool.mypy]
python_version = "3.12"
check_untyped_defs = true
ignore_missing_imports = true

# Phase 2: 中程度の厳格さ
[tool.mypy]
python_version = "3.12"
disallow_untyped_defs = true
check_untyped_defs = true
warn_return_any = true

# Phase 3: 厳格モード
[tool.mypy]
python_version = "3.12"
strict = true

型ヒントのベストプラクティス

関数の引数と戻り値には必ず型ヒントを付ける
ローカル変数の型ヒントは、型推論で明らかな場合は省略してもよい
Any型の使用は最小限に抑える
複雑な型はTypeAliasで名前をつけて可読性を高める
PydanticのBaseModelを活用し、実行時のバリデーションも組み合わせる

from typing import TypeAlias

# 複雑な型にエイリアスをつける
UserId = int
UserData: TypeAlias = dict[str, str | int | list[str]]
ApiResponse: TypeAlias = dict[str, list[UserData]]

def fetch_users() -> ApiResponse:
    return {
        "users": [
            {"name": "田中", "age": 30, "skills": ["Python"]},
        ]
    }