python-patterns

プロジェクト構造（src レイアウト）

project/
├── src/project_name/
│   ├── __init__.py        # Public API のエクスポート
│   ├── domain/            # コアロジック（IO なし）
│   │   ├── models.py      # Dataclasses/Pydantic
│   │   └── services.py    # 純粋なビジネスロジック
│   ├── infra/             # IO、外部サービス
│   ├── config.py          # Pydantic Settings
│   └── cli.py             # typer のエントリーポイント
├── tests/
│   ├── conftest.py
│   ├── unit/
│   └── integration/
├── pyproject.toml         # 単一の情報源（uv）
└── Dockerfile

型注釈（3.11+）

def process(items: list[str], config: dict[str, int] | None = None) -> bool: ...

from typing import Protocol, runtime_checkable

@runtime_checkable
class Serializable(Protocol):
    def to_dict(self) -> dict[str, Any]: ...

type JsonDict = dict[str, Any]
type Result[T] = tuple[T, None] | tuple[None, str]

エラーハンドリング

class PipelineError(Exception):
    def __init__(self, stage: str, message: str, cause: Exception | None = None):
        super().__init__(f"[{stage}] {message}")
        self.stage = stage
        self.__cause__ = cause

# エラーの構造化ログ（structlog）
log.exception("pipeline_failed", stage=stage, input_id=item.id)

非同期パターン（3.11+）

# レート制限用セマフォ
sem = asyncio.Semaphore(10)
async def rate_limited(item):
    async with sem:
        return await process(item)

# 構造化並行処理用 TaskGroup
async with asyncio.TaskGroup() as tg:
    task1 = tg.create_task(fetch_data())
    task2 = tg.create_task(process_data())

# エラー分離を備えた gather
results = await asyncio.gather(*tasks, return_exceptions=True)
successes = [r for r in results if not isinstance(r, Exception)]

設定（Pydantic Settings）

from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field

class AppConfig(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="APP_", env_file=".env")
    db_url: str = Field(description="Database connection string")
    debug: bool = False
    workers: int = Field(default=4, ge=1, le=32)

テスト

• フィクスチャ付き pytest を使用します。エッジケースはパラメータ化します。
• 非同期テストには pytest-asyncio（オートモード）を使用します。
• ユニットテスト（高速、IO なし）と統合テスト（低速、実際のサービス）を分離します。
• モックより フェイク を優先します。モックは境界で使用し、内部では使わないようにします。
• 時間に依存するテストには time-machine を使用します。
• 許可なしにローカルでフルスイートを実行しないでください — それは CI の仕事です。

パッケージング（uv）

uv init --lib           # 新規ライブラリプロジェクト
uv add pydantic         # 依存関係の追加
uv run pytest           # プロジェクト venv での実行
uv build                # wheel + sdist のビルド
uv tool install ruff    # CLI ツールをグローバルにインストール