python-error-handling

出典に関する声明：本スキルの内容は wshobson/agents （MIT License, Copyright (c) 2024 Seth Hobson）に由来します。完全なライセンステキストは同じディレクトリの LICENSE.txt をご覧ください。 使用、変更、再配布は当該 MIT ライセンスの条項に従い、著作権表示を保持する必要があります。

日本語の説明

本スキルでは、フルスタック開発に関するベストプラクティスとパターンを案内します。

---

name: python-error-handling description: 入力検証、例外階層、部分的な失敗への対処など、Python のエラー処理パターンです。検証ロジックの実装、例外戦略の設計、バッチ処理での失敗への対処、堅牢な API の構築に使用します。

Python のエラー処理

適切な入力検証、意味のある例外、適切な障害処理によって、堅牢な Python アプリケーションを構築します。適切なエラー処理により、デバッグが容易になり、システムの信頼性が向上します。

このスキルを使用する場面

• ユーザー入力と API パラメーターの検証
• アプリケーションの例外階層の設計
• バッチ処理での部分的な失敗への対処
• 外部データからドメイン型への変換
• ユーザーにとってわかりやすいエラーメッセージの作成
• フェイルファスト検証パターンの実装

基本概念

1. フェイルファスト

コストの高い処理を始める前に、早い段階で入力を検証します。可能な場合は、すべての検証エラーを一度に報告します。

2. 意味のある例外

コンテキストを含む適切な例外型を使用します。メッセージでは、何が失敗したのか、なぜ失敗したのか、どう修正すればよいのかを説明します。

3. 部分的な失敗

バッチ処理では、1 つの失敗によってすべてを中断させないようにします。成功と失敗をそれぞれ記録します。

4. コンテキストの保持

例外をチェーンして、デバッグに必要なエラーの全履歴を保持します。

クイックスタート

def fetch_page(url: str, page_size: int) -> Page:
    if not url:
        raise ValueError("'url' is required")
    if not 1 <= page_size <= 100:
        raise ValueError(f"'page_size' must be 1-100, got {page_size}")
    # Now safe to proceed...

基本パターン

パターン 1：早期の入力検証

処理を始める前に、API の境界ですべての入力を検証します。

def process_order(
    order_id: str,
    quantity: int,
    discount_percent: float,
) -> OrderResult:
    """Process an order with validation."""
    # Validate required fields
    if not order_id:
        raise ValueError("'order_id' is required")

    # Validate ranges
    if quantity <= 0:
        raise ValueError(f"'quantity' must be positive, got {quantity}")

    if not 0 <= discount_percent <= 100:
        raise ValueError(
            f"'discount_percent' must be 0-100, got {discount_percent}"
        )

    # Validation passed, proceed with processing
    return _process_validated_order(order_id, quantity, discount_percent)

パターン 2：早期のドメイン型への変換

システムの境界で、文字列や外部データを型付きドメインオブジェクトにパースします。

from enum import Enum

class OutputFormat(Enum):
    JSON = "json"
    CSV = "csv"
    PARQUET = "parquet"

def parse_output_format(value: str) -> OutputFormat:
    """Parse string to OutputFormat enum.

    Args:
        value: Format string from user input.

    Returns:
        Validated OutputFormat enum member.

    Raises:
        ValueError: If format is not recognized.
    """
    try:
        return OutputFormat(value.lower())
    except ValueError:
        valid_formats = [f.value for f in OutputFormat]
        raise ValueError(
            f"Invalid format '{value}'. "
            f"Valid options: {', '.join(valid_formats)}"
        )

# Usage at API boundary
def export_data(data: list[dict], format_str: str) -> bytes:
    output_format = parse_output_format(format_str)  # Fail fast
    # Rest of function uses typed OutputFormat
    ...

パターン 3：複雑な検証には Pydantic を使用する

構造化された入力検証と自動エラーメッセージには、Pydantic モデルを使用します。

from pydantic import BaseModel, Field, field_validator

class CreateUserInput(BaseModel):
    """Input model for user creation."""

    email: str = Field(..., min_length=5, max_length=255)
    name: str = Field(..., min_length=1, max_length=100)
    age: int = Field(ge=0, le=150)

    @field_validator("email")
    @classmethod
    def validate_email_format(cls, v: str) -> str:
        if "@" not in v or "." not in v.split("@")[-1]:
            raise ValueError("Invalid email format")
        return v.lower()

    @field_validator("name")
    @classmethod
    def normalize_name(cls, v: str) -> str:
        return v.strip().title()

# Usage
try:
    user_input = CreateUserInput(
        email="[email protected]",
        name="john doe",
        age=25,
    )
except ValidationError as e:
    # Pydantic provides detailed error information
    print(e.errors())

パターン 4：エラーを標準例外に対応付ける

Python 組み込みの例外型を適切に使用し、必要に応じてコンテキストを追加します。

失敗の種類	例外	例
無効な入力	ValueError	不正なパラメーター値
型の不一致	TypeError	文字列が必要ですが、int が渡されました
項目が見つからない	KeyError	dict のキーが見つかりません
操作上の失敗	RuntimeError	サービスを利用できません
タイムアウト	TimeoutError	操作に時間がかかりすぎました
ファイルが見つからない	FileNotFoundError	パスが存在しません
アクセス拒否	PermissionError	アクセスが禁止されています

# Good: Specific exception with context
raise ValueError(f"'page_size' must be 1-100, got {page_size}")

# Avoid: Generic exception, no context
raise Exception("Invalid parameter")

詳細な実例とパターン

詳細なセクション（## Advanced Patterns 以降）は references/details.md にあります。上記の概要だけでは不十分な場合は、そのファイルを参照してください。

ベストプラクティスのまとめ

1. 早期に検証する - コストの高い処理の前に入力を確認します
2. 具体的な例外を使用する - 汎用的な Exception ではなく、ValueError や TypeError を使用します
3. コンテキストを含める - メッセージで、何が起きたのか、なぜ起きたのか、どう修正すればよいのかを説明します
4. 境界で型を変換する - 文字列を早い段階で列挙型やドメイン型にパースします
5. 例外をチェーンする - raise ... from e を使用してデバッグ情報を保持します
6. 部分的な失敗に対処する - 1 件のエラーでバッチ処理を中断しないようにします
7. Pydantic を使用する - 構造化されたエラーを伴う複雑な入力検証に使用します
8. 失敗モードを文書化する - docstring に発生する可能性のある例外を記載します
9. コンテキストを含めてログに記録する - ID、件数、その他のデバッグ情報を含めます
10. エラー経路をテストする - 例外が正しく発生することを確認します

ワークフロー

ステップ 1：要件分析

プロジェクトの要件と技術的制約を理解します

ステップ 2：アーキテクチャ設計

システムアーキテクチャとコンポーネントの分割を設計します

ステップ 3：実装のガイダンス

具体的な実装の提案とコードパターンを提供します

ステップ 4：コードレビュー

コードの品質とベストプラクティスへの準拠状況を確認します

ステップ 5：最適化の提案

パフォーマンスの最適化と改善の提案を行います

注意点

1. 過剰設計

単純な場面で複雑な設計パターンを使用しないようにします

2. パフォーマンスの軽視

特に本番環境では、パフォーマンスの最適化を軽視しないでください

3. セキュリティへの配慮

セキュリティとデータ保護を常に考慮します

4. テストカバレッジ

特に境界条件について、十分なテストカバレッジを確保します

5. ドキュメントの保守

ドキュメントをコードに合わせて常に更新します