python-best-practices

Python のベストプラクティス

CLAUDE.md の型優先、関数型、エラー処理のパターンに従います。このスキルでは、言語固有のイディオムのみを扱います。

不正な状態を表現できないようにする

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 dataclasses are immutable — no accidental mutation

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:
    # Type checker prevents passing OrderId here
    ...

構造的部分型付けには Protocol を使用します：

from typing import Protocol

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

def process_input(source: Readable) -> bytes:
    # Accepts any object with a read() method — no inheritance required
    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          # run directly, no install needed
uvx ty check src/     # check specific path

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

選択の目安：

• ty — 最速で、CI や大規模なコードベースに適しています（初期段階で、急速に進化しています）
• pyright — 最も完全な型推論と VS Code 連携を備えています
• mypy — 成熟しており、プラグインのエコシステムが充実しています