第5章実践的な高度な型注釈と型安全性

前章で学んだ基本的な型ヒントに加え、現代の Python では複雑なデータ構造や柔軟な設計パターンを安全に表現するための高度な型システムが整備されています。

本章では、実務の API 設計やライブラリ開発で頻出する TypedDict、Literal、ジェネリクス（Generics）、および Protocol などの実践的な型定義手法を解説します。

5.1 辞書の構造を定義する TypedDict

JSON や REST API のレスポンスなど、決まったキーと値のペアを持つ辞書データを扱う際、単なる dict[str, Any] では型の恩恵を受けられません。

TypedDict を使用すると、辞書のキー名とその値の型を厳密に定義できます。

from typing import TypedDict, NotRequired

class UserProfile(TypedDict):
    id: int
    username: str
    is_admin: bool
    # 省略可能なキーには NotRequired を指定する
    bio: NotRequired[str]

# 定義に適合する辞書
user: UserProfile = {
    "id": 101,
    "username": "taro",
    "is_admin": False,
}

# 存在しないキーへのアクセスや型の誤りは、型チェッカーが即座に検出する
print(user["username"])

クラス形式で定義しますが、実行時には純粋な Python 辞書として動作するため、JSON シリアライズや外部ライブラリとの連携が極めてスムーズです。

5.2 特定の文字列や数値に制限する Literal

関数の引数や設定値で、「あらかじめ定められた少数の値しか受け付けない」場合は Literal を使用します。

from typing import Literal

type LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR"]

def output_log(message: str, level: LogLevel = "INFO") -> None:
    print(f"[{level}] {message}")

# 正常な呼び出し
output_log("起動しました", level="INFO")

# 型チェッカーによるエラー検出: "TRACE" は LogLevel に含まれない
# output_log("通信中", level="TRACE")

エディタ上でも候補が自動補完されるため、スペルミスや不正な値の引き渡しを未然に防止できます。

5.3 汎用的なコンテナとジェネリクス (Generics)

「どんな型のデータでも受け取れるが、入力された型と出力される型の対応関係は保ちたい」という場合には、ジェネリクスを使用します。

Python 3.12 以降の新しい構文

Python 3.12 では、関数やクラス定義の直後に角括弧 [T] を記述するだけで型パラメータを宣言できるようになりました。

# T は任意の型を表す型パラメータ
def get_first_element[T](items: list[T]) -> T:
    """リストの先頭要素を返し、元の型をそのまま維持する。"""
    if not items:
        raise ValueError("リストが空です")
    return items[0]

# int のリストを渡せば戻り値は自動的に int と推論される
first_num = get_first_element([10, 20, 30])  # 型は int

# str のリストを渡せば戻り値は自動的に str と推論される
first_word = get_first_element(["apple", "banana"])  # 型は str

Python 3.11 以前の書き方 (TypeVar)

Python 3.11 以前の環境では、typing.TypeVar を明示的にインポートして定義します。

from typing import TypeVar

T = TypeVar("T")

def get_first_element_legacy(items: list[T]) -> T:
    if not items:
        raise ValueError("リストが空です")
    return items[0]

5.4 構造的サブタイピングと Protocol

Python の伝統的な特徴である「ダックタイピング（アヒルのように歩き、アヒルのように鳴くなら、それはアヒルである）」を静的型付けの世界で実現するのが Protocol です。

基底クラスを明示的に継承（名目型）していなくても、特定のメソッドや属性を持っているオブジェクトであれば同一の型として扱うことができます。

from typing import Protocol

class Renderable(Protocol):
    """render メソッドを持つオブジェクトを表すプロトコル"""
    def render(self) -> str:
        ...

# Renderable を継承していなくても、render メソッドを持っていれば適合する
class MarkdownDocument:
    def render(self) -> str:
        return "# Markdown Content"

class HtmlDocument:
    def render(self) -> str:
        return "<p>HTML Content</p>"

def publish(doc: Renderable) -> None:
    print(f"Publishing: {doc.render()}")

# どちらのクラスインスタンスも安全に引き渡せる
publish(MarkdownDocument())
publish(HtmlDocument())

これにより、ライブラリ同士の過度な依存や多重継承を避けつつ、安全で柔軟なインターフェース設計が可能になります。

5.5 Any と object の使い分け

型定義において、Any と object は似ているようで全く異なる挙動を示します。

Any: 型チェックを完全に無効化します。どんな操作やメソッド呼び出しも許可されるため、型安全性が破壊されます。どうしても型を特定できない過渡的なコード以外での利用は極力避けるべきです。
object: すべての Python オブジェクトの基底型です。どんな値でも代入できますが、isinstance() などで型を絞り込まない限り、オブジェクト固有のメソッド呼び出しは型エラーとなります。

from typing import Any

# Any の場合: 存在しないメソッドを呼んでも型チェッカーは警告しない（実行時エラーの温床）
def process_any(data: Any) -> None:
    data.non_existent_method()

# object の場合: 事前に型チェックを行うことを強制できる（安全）
def process_object(data: object) -> None:
    # data.split()  # 型エラー！ object に split メソッドはない
    if isinstance(data, str):
        print(data.split())  # ここでは str であることが保証される

5.6 次のステップ：データモデリングへの応用

本章で扱った TypedDict や Literal、ジェネリクス、Protocol などの高度な型システムは、クラスやデータ構造の設計において不可欠な構成要素となります。

Python において実務的なデータ構造（ドメインモデル、設定値、API スキーマなど）を構築する際には、標準ライブラリの dataclasses や、データ検証に特化した Pydantic が広く活用されます。次章「第6章 dataclass と Pydantic によるデータモデリング」では、これら 2 つのツールの特徴、使い分け、および詳細な活用手法を体系的に解説します。

Keyboard shortcuts