Python プログラミング — 一般アプローチは何をしますか？

これは Python のマスターリファレンススキルです。このプロジェクトの全ての Python コードで使用される、非妥協的なデフォルト設定と「ファンクショナル・ライト」哲学を定義します。まずこれを読み、詳細なガイダンスについてはリンクされたドメインスキルを参照してください。

コアスタック

項目	選択肢
パッケージマネージャー & タスクランナー	`uv`
パッケージングマニフェスト	`pyproject.toml` のみ
リンター / フォーマッター	`ruff`
型チェッカー	`ty`
データ処理ライブラリ	`polars`（`pandas` は不可）
バックエンドフレームワーク	FastAPI
データベース	PostgreSQL
ORM	SQLAlchemy（非同期）
マイグレーション	Alembic
実行モデル	`asyncio` — 常に非同期
プログラミングスタイル	ファンクショナル・ライト

パッケージ管理 — 常に `uv`

決して pip、pip-tools、poetry、pipenv を直接使用しないでください。全てのインストール、実行、スクリプト処理は uv とそのネイティブコマンドを使用します。

# 依存関係のインストール
uv sync

# 依存関係の追加
uv add <package>

# 開発依存関係の追加
uv add --dev <package>

# スクリプトまたはモジュールの実行
uv run python script.py
uv run alembic upgrade head
uv run pytest

# 依存関係のアップグレード
uv lock --upgrade

再現可能なビルドのために、全ての本番依存関係は == で固定してください。依存関係管理に requirements.txt、requirements-dev.txt、または requirements ディレクトリを使用しないでください。全てのパッケージメタデータと依存関係設定は pyproject.toml に属します。パッケージ、ツール、ビルドに触れる全ての操作には uv を使用してください。このプロジェクトで pip、pip install、python -m pip、poetry、pipenv を直接実行しないでください。完全なアップグレードワークフローについては、upgrade-dependencies スキルを参照してください： .github/skills/upgrade-dependencies/SKILL.md ライブラリ固有のガイダンスについては、.github/skills/python-library-creation/SKILL.md を参照してください。

リンティングとフォーマット — Astral スタック必須

このリポジトリの Python プロジェクトでは Astral スタックが必須です。ruff が標準のリンター兼フォーマッターです。

開発依存関係として ruff を追加：uv add --dev ruff
コードをフォーマットするには uv run ruff format を使用します。
リンティングを実行し、可能な場合は自動的に修正するには uv run ruff check --fix を使用します。
これらのコマンドをプロジェクトのスクリプトまたは README に文書化してください。

ruff は、コード、テスト、設定全体にわたるフォーマットとスタイルの一貫性のための唯一の情報源です。

型チェック — `ty` 推奨

型アノテーションは必須です。ty はこのリポジトリで推奨される型チェッカーです。

開発依存関係として ty を追加：uv add --dev ty
uv run ty check で型チェックを実行します。
動作を比較したい場合は uv run --with ty ty check を使用してツールチェーンを検証します。

リポジトリは mypy や pyrefly などの他のチェッカーを実験することもありますが、ty が推奨される主要なチェッカーであり、CI で強制されるべきものです。

データ処理 — Polars vs DuckDB

このリポジトリでは、プロセス内データエンジニアリングには polars を、SQL ファーストの分析と大規模ファイルのクエリには DuckDB を推奨します。

エージェントが Speedster として動作する場合は Polars を使用します：
- Rust 駆動、シングルマシンでのマルチスレッド DataFrame 処理。
- 複雑なパイプライン連鎖、特徴量エンジニアリング、結合、ウィンドウ関数、プログラムによる変換に最適。
- スループットと計算速度を優先し、より厳格なスキーマと型安全性を備えています。
- モデルの前処理や Python の ML ツールとの統合に優れています。
エージェントが Librarian として動作する場合は DuckDB を使用します：
- 分析用 OLAP クエリに最適化されたインプロセス SQL データベース。
- SQL ファーストの意図は、自然言語をコードに変換する際により信頼性が高くなります。
- メモリ制約のあるワークロードに優れています：DuckDB は厳格なメモリ制限を強制し、非常に大きなデータセットを安全にクエリできます。
- S3 や Google Cloud 上のリモートファイルを URL 経由で直接クエリする、ゼロ ETL のクラウドクエリに最適です。

判断基準

タスクが次の場合：

新しいファイルやクラウドストレージの探索 → DuckDB
- 直接ファイルスキャンと SQL 探索に最適。
巨大なデータセットのフィルタリングや並べ替え → Polars
- シングルノードでの生のフィルタリングと読み込み速度で優位。
協業や引き継ぎ → DuckDB
- SQL は人間とエージェントの両方が保守・デバッグしやすい。
モデルの前処理 → Polars
- Python の ML ツールとの統合とスキーマセーフなパイプラインに優れている。

バックエンド — FastAPI

FastAPI は唯一サポートされるバックエンドフレームワークです。主要な規約：

常に async def をルートハンドラーと依存関係に使用します。
全てのリクエスト/レスポンスの形状には Pydantic v2 モデルを使用します。
依存関係は Depends() で宣言します — ハンドラー内でグローバル状態にアクセスしないでください。
型付けされたレスポンスモデルを返します；ルートハンドラーから生の dict を決して返さないでください。
ルーターは独自のモジュールに配置します；main.py はルーターのマウントとミドルウェアの設定のみを行います。

# ✅ 正しいパターン
@router.get("/items/{item_id}", response_model=ItemResponse)
async def get_item(item_id: int, db: AsyncSession = Depends(get_db)) -> ItemResponse:
    return await item_service.get(db, item_id)

構造化、テスト、セキュリティ、OpenAPI ドキュメントについては、FastAPI ドメインスキルを参照してください：

.github/skills/python-fastapi-project-structuring/SKILL.md
.github/skills/python-fastapi-routing-validation/SKILL.md
.github/skills/python-fastapi-dependency-injection/SKILL.md
.github/skills/python-fastapi-response-error-handling/SKILL.md
.github/skills/python-fastapi-security-authentication/SKILL.md
.github/skills/python-fastapi-security-attack-resistance/SKILL.md
.github/skills/python-fastapi-api-testing/SKILL.md
.github/skills/python-fastapi-openapi-documentation/SKILL.md

データベース — PostgreSQL + SQLAlchemy（非同期）

PostgreSQL は唯一サポートされるデータベースです。SQLAlchemy は ORM です。

常に非同期エンジンとセッションを使用します（AsyncEngine、AsyncSession）。
非同期コードから同期的な SQLAlchemy API を決して呼び出さないでください。
sqlalchemy から select()、insert()、update()、delete() を使用します — 生の SQL 文字列は使用しません。
async with AsyncSession(engine) as session でセッションライフサイクルを管理します。
DeclarativeBase でモデルを定義し、Mapped[T] 型のカラムアノテーションを使用します（SQLAlchemy 2.x スタイル）。

from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

engine = create_async_engine("postgresql+asyncpg://...", echo=False)

class Base(DeclarativeBase):
    pass

class Item(Base):
    __tablename__ = "items"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]

データベースマイグレーション — Alembic

Alembic は全てのスキーマ変更を管理します。データベーススキーマを手動で変更しないでください。

主要ルール：

マイグレーションは、非ローカル環境に一度適用されたら不変です。
各マイグレーションは可能な限り冪等でなければなりません。
全ての Alembic コマンドには uv run alembic を使用します。

uv run alembic revision --autogenerate -m "add_items_table"
uv run alembic upgrade head
uv run alembic history
uv run alembic current

マイグレーション作成ルールと RLS 適用の詳細については、以下を参照してください： .github/skills/python-alembic-migrations/SKILL.md

ローカル限定のマイグレーションブランチのリベースについては、以下を参照してください： .github/skills/python-alembic-migration-rebase/SKILL.md

非同期 — 常に

全ての I/O 操作は非同期でなければなりません。リクエストパスにブロッキング呼び出しを配置する場所はありません。

同時実行の独立したコルーチンには asyncio.gather() を使用します。
構造化された並行性とエラー伝播が重要な場合は asyncio.TaskGroup（Python 3.11+）を使用します。
バックプレッシャーとレート制限には asyncio.Queue または asyncio.Semaphore を使用します。
time.sleep() を決して呼び出さないでください — await asyncio.sleep() を使用します。
requests を決して使用しないでください — httpx.AsyncClient または aiohttp を使用します。

詳細なガイダンス：

.github/skills/python-asyncio/asyncio-concurrent-web-requests/SKILL.md
.github/skills/python-concurrent-processing/SKILL.md（CPU バウンド処理 → ProcessPoolExecutor + asyncio 統合）
.github/skills/python-asyncio/asyncio-synchronization/SKILL.md

ファンクショナル・ライトスタイル

コードベースは「ファンクショナル・ライト」アプローチを採用しています：関数型テクニックを複雑性を低減し明確性を向上させる場合に適用しますが、理論的な純粋性を強制するものではありません。

採用するもの

テクニック	使用するタイミング
純粋関数	ビジネスロジックのデフォルト。必要な場合を除き副作用なし。
不変データ	値オブジェクトには frozen dataclass / Pydantic モデルを使用。
高階関数	データパイプラインでは命令ループよりも `map`、`filter`、`functools.reduce` を優先。
ジェネレーター / 遅延シーケンス	大規模またはストリーミングデータセット — メモリ内に完全なリストを構築しない。
`functools` ユーティリティ	`lru_cache`、`cache`、`partial`、`wraps` — 自由に使用。
関数合成	データ変換パイプラインで小さく焦点を絞った関数を連結。
記述的デコレーター	横断的関心事（認証、キャッシュ、リトライ）をデコレーターとして表現。

強制しないもの

テクニック	明確に有益でない限り避ける理由
モナド（`Maybe`、`Either`、`Result`）	認知負荷が増加；代わりに例外 + 型付き戻り値を使用。
ポイントフリースタイル	ほとんどのチームメイトにとって可読性を損なう。
どこでも厳格な不変性	SQLAlchemy モデルと非同期状態は本質的に可変；必要な場所でのみ対処。
`pymonad` / `returns` ライブラリ	オプトインのみ；チームの合意なしに共有コードに押し付けない。

# ✅ ファンクショナル・ライト：焦点を絞った純粋関数のパイプライン
from functools import reduce

def parse_items(raw: list[dict]) -> list[Item]:
    return [Item(**r) for r in raw if r.get("active")]

def enrich(item: Item, overrides: dict) -> Item:
    return item.model_copy(update=overrides.get(item.id, {}))

def process(raw: list[dict], overrides: dict) -> list[Item]:
    return [enrich(item, overrides) for item in parse_items(raw)]

詳細なガイダンス — 統合および専門的な関数型スキル：

.github/skills/python-higher-order-functools/SKILL.md（map、filter、max/min、@cache、partial、reduce、@singledispatch）
.github/skills/python-lazy-evaluation-pipelines/SKILL.md（yield、yield from、ジェネレーターパイプライン、map/filter/reduce）
.github/skills/python-immutable-data-design/SKILL.md（NamedTuple、frozen dataclass、pyrsistent、コンテキストマネージャー）
.github/skills/python-functional-programming/python-decorator-design/SKILL.md
.github/skills/python-functional-programming/python-functional-web-services/SKILL.md（FastAPI 関数型ハンドラー）
.github/skills/python-functional-programming/python-toolz-composition/SKILL.md
.github/skills/python-functional-programming/python-itertools-combinatorics/SKILL.md
.github/skills/python-functional-programming/python-recursion-tco/SKILL.md
.github/skills/python-functional-programming/python-pymonad-strict-evaluation/SKILL.md ← オプトインのみ

一般的なコード規約

Python 3.11+ 最低限。最新の構文を使用：match、TypeAlias、Self など。
全てに型アノテーションを付ける — 関数シグネチャ、変数、戻り値の型。
Any は不可（型付けされていないサードパーティ境界と統合する場合を除く）。
値オブジェクトには dataclass(frozen=True) または Pydantic BaseModel を推奨。
関数は小さく単一目的に保つ。関数が何をするかを説明するコメントが必要な場合（なぜではなく）、分割する。
グローバルな可変状態を避ける。依存関係を明示的に渡す（コンストラクタまたは Depends()）。
logging を使用 — print は不可。アプリ起動時に設定；ライブラリコード内で basicConfig() を決して呼び出さない。完全なロギング、トレーシング、設定ガイダンスについては .github/skills/python-configuration-observability/SKILL.md を参照。

スキルマップ

python/SKILL.md  ← 現在地（マスターリファレンス）
│
├── バックエンドフレームワーク
│   ├── python-fastapi-project-structuring/SKILL.md
│   ├── python-fastapi-routing-validation/SKILL.md
│   ├── python-fastapi-dependency-injection/SKILL.md
│   ├── python-fastapi-response-error-handling/SKILL.md
│   ├── python-fastapi-security-authentication/SKILL.md
│   ├── python-fastapi-security-attack-resistance/SKILL.md
│   ├── python-fastapi-api-testing/SKILL.md
│   └── python-fastapi-openapi-documentation/SKILL.md
│
├── データベース & マイグレーション
│   ├── python-alembic-migrations/SKILL.md
│   └── python-alembic-migration-rebase/SKILL.md
│
├── 非同期パターン
│   ├── python-asyncio/asyncio-concurrent-web-requests/SKILL.md
│   └── python-asyncio/asyncio-synchronization/SKILL.md
│
├── 統合コアスキル
│   ├── python-configuration-observability/SKILL.md   (設定 + ロギング + トレーシング)
│   ├── python-data-structures-type-system/SKILL.md   (コレクション + 型 + Pydantic)
│   ├── python-lazy-evaluation-pipelines/SKILL.md     (ジェネレーター + map/filter/reduce)
│   ├── python-higher-order-functools/SKILL.md        (HOFs + cache + partial + singledispatch)
│   ├── python-immutable-data-design/SKILL.md         (NamedTuple + frozen DC + コンテキストマネージャー)
│   └── python-concurrent-processing/SKILL.md         (ProcessPool + asyncio 統合)
│
├── 関数型プログラミング（専門）
│   ├── python-functional-programming/python-decorator-design/SKILL.md
│   ├── python-functional-programming/python-functional-web-services/SKILL.md
│   ├── python-functional-programming/python-toolz-composition/SKILL.md
│   ├── python-functional-programming/python-itertools-combinatorics/SKILL.md
│   ├── python-functional-programming/python-recursion-tco/SKILL.md
│   └── python-functional-programming/python-pymonad-strict-evaluation/SKILL.md ← オプトイン
│
├── ライブラリ作成
│   ├── python-library-creation/SKILL.md
│   └── python-project-setup/SKILL.md
│
├── Polars
│   ├── python-polars-filtering-sorting/SKILL.md
│   ├── python-polars-groupby-aggregation/SKILL.md
│   ├── python-polars-joins-reshaping/SKILL.md
│   ├── python-polars-window-functions/SKILL.md
│   ├── python-polars-lazy-eager-execution/SKILL.md
│   ├── python-polars-schema-data-types/SKILL.md
│   ├── python-polars-performance-tuning/SKILL.md
│   └── python-polars-error-debugging/SKILL.md
│
├── DuckDB
│   ├── python-duckdb-query-fundamentals/SKILL.md
│   ├── python-duckdb-cloud-remote-access/SKILL.md
│   ├── python-duckdb-consume-with-polars/SKILL.md
│   ├── python-duckdb-insert-upsert-delete/SKILL.md
│   └── python-duckdb-connect-configuration/SKILL.md
│
├── ユニットテスト & プロパティベーステスト
│   ├── python-pytest-unit-testing/SKILL.md
│   └── python-property-based-testing/SKILL.md
│
├── テスト自動化
│   └── python-playwright-e2e-testing/SKILL.md
│
└── テンプレート
    └── SKILL.template.md

Python プログラミング — 一般アプローチ