Python ベストプラクティス

CLAUDE.md の型第一、関数型、エラーハンドリングのパターンに従います。このスキルはPython固有のイディオムのみをカバーしています。

不正な状態を表現不可能にする

Pythonの型システムを使って、型チェック時に無効な状態を防ぎます。

イミュータブルなドメインモデルのための Frozen dataclass:

from dataclasses import dataclass
from datetime import datetime

@dataclass(frozen=True)
class User:
    id: str
    email: str
    name: str
    created_at: datetime

# Frozen dataclass はイミュータブル — 不注意な変異はない

Literal を使った判別ユニオン:

from dataclasses import dataclass
from typing import Literal

@dataclass
class Success:
    status: Literal["success"] = "success"
    data: str

@dataclass
class Failure:
    status: Literal["error"] = "error"
    error: Exception

RequestState = Success | Failure

def handle_state(state: RequestState) -> None:
    match state:
        case Success(data=data):
            render(data)
        case Failure(error=err):
            show_error(err)

ドメインプリミティブのための NewType:

from typing import NewType

UserId = NewType("UserId", str)
OrderId = NewType("OrderId", str)

def get_user(user_id: UserId) -> User:
    # 型チェッカーが OrderId をここに渡すのを防ぐ
    ...

構造的部分型のための Protocol:

from typing import Protocol

class Readable(Protocol):
    def read(self, n: int = -1) -> bytes: ...

def process_input(source: Readable) -> bytes:
    # read() メソッドを持つ任意のオブジェクトを受け入れる — 継承は不要
    return source.read()

Python固有のエラーハンドリング

from err で例外をチェーンして、元のトレースバックを保持します:

try:
    data = json.loads(raw)
except json.JSONDecodeError as err:
    raise ValueError(f"invalid JSON payload: {err}") from err

構造化ログ

モジュールレベルのロガーと %s フォーマット（遅延文字列補間）を使用します:

import logging

logger = logging.getLogger("myapp.widgets")

def create_widget(name: str) -> Widget:
    logger.debug("creating widget: %s", name)
    widget = Widget(name=name)
    logger.debug("created widget id=%s", widget.id)
    return widget

オプション: ty

高速な型チェックのため、Astral（ruff と uv の開発元）による ty の使用を検討してください。Rust で書かれており、mypy や pyright より大幅に高速です。

uvx ty check          # インストール不要で直接実行
uvx ty check src/     # 特定のパスをチェック

# pyproject.toml
[tool.ty]
python-version = "3.12"

選択時のガイドライン:

• ty — 最速、CI と大規模なコードベースに最適（初期段階、急速に進化中）
• pyright — 最も完全な型推論、VS Code 統合
• mypy — 成熟、広範なプラグインエコシステム