python-project-guidelines

Python プロジェクトのガイドライン

概要

基本原則： uv で管理する環境、最小限の依存関係、最新の Python バージョンを使用し、Web アプリケーションでは非同期処理を優先するアーキテクチャで Python プロジェクトを作成します。

重要な違い： このスキルは pyproject.toml を含む Python プロジェクト全体に適用されます。単独の単一ファイルスクリプトには、代わりに standalone-python-scripts スキルを使用してください。

使用する場合

• 複数のモジュールを含む新しい Python プロジェクトを始める場合
• Python アプリケーションやライブラリのひな型を作成する場合
• pyproject.toml を含むプロジェクト構成をセットアップする場合
• 複数のファイル、テスト、または複雑な依存関係が必要なプロジェクトの場合

使用しない場合：

• 単一ファイルのスタンドアロンスクリプト → standalone-python-scripts スキルを使用
• 簡単なユーティリティスクリプト → standalone-python-scripts スキルを使用
• 再構成が不要で、pyproject.toml を含まない既存のプロジェクト

スタンドアロンスクリプトの確認

作業を進める前に： プロジェクトが単一ファイルのツールまたはスクリプト（複数モジュールのアプリケーションではない）の場合は、作業を中止して、代わりに standalone-python-scripts スキルを使用してください。

判断基準：

• スタンドアロンで実行する単一の .py ファイル → standalone-python-scripts
• 複数のモジュール、テスト、または複雑な構成 → このスキルを続行

uv による環境管理

Python のバージョン管理と仮想環境の管理には uv を使用します。

プロジェクトの初期化

# Initialize new project
uv init myproject
cd myproject

# Specify Python version (see version policy below)
uv init myproject --python 3.12

依存関係の追加

# Add production dependencies
uv add click arrow sqlalchemy

# Add development dependencies
uv add --dev pytest ruff mypy

# Add with version constraints
uv add 'httpx>=0.24,<0.27'

コマンドの実行

# Run Python scripts
uv run python myscript.py

# Run installed tools
uv run pytest
uv run ruff check .

Python バージョンの方針

ルール： サポート終了となった Python バージョンや、サポート終了まで1年未満のバージョンを対象にしてはいけません。

現在の状況を確認： https://devguide.python.org/versions/

現在の安全な最小バージョン（2026-08-27 時点）： Python 3.11

• 3.10：EOL 2026-10（1年未満）→ 対象にしない
• 3.11：EOL 2027-10（1年以上）→ OK
• 3.12 以降：OK

pyproject.toml 内：

[project]
requires-python = ">=3.11"

確認： requires-python を設定する前に、上記の devguide URL を確認してください。バージョンの EOL が今日から12か月以内に迫っている場合は、そのバージョンを使用しないでください。

依存関係の管理

原則： タスクを効率よく達成するために必要最小限の外部要件だけを取り入れます。

判断手順：

1. 標準ライブラリで対応できますか？ → 標準ライブラリを使用
2. 広く確立され、メンテナンスされているライブラリはありますか？ → それを使用
3. 標準ライブラリに対して、依存関係の追加で大きな価値が得られますか？ → その理由を明確にする

例：

• JSON の解析 → 標準ライブラリの json（外部依存関係は不要）
• HTTP クライアント → httpx または requests（標準ライブラリの urllib は扱いにくい）
• 日時 → arrow（推奨ライブラリの表を参照）
• CLI の解析 → click（推奨ライブラリの表を参照）

ライブラリの推奨

外部依存関係が必要な場合は、以下のライブラリを優先してください。

必要な機能	ライブラリ	備考
引数の解析	Click	デコレーター方式で、すっきりした API
日時の処理	Arrow	標準ライブラリの datetime より優れています
データベース ORM	SQLAlchemy	絶対に必要な場合を除き、生の SQL は記述しないでください
データベースのマイグレーション	Alembic	SQLAlchemy と連携します
Web（非同期）	Quart、FastAPI、または AioHttp	プロジェクトのニーズに合わせて選択し、非同期フレームワークを優先してください

Web フレームワークの選択：

• FastAPI：OpenAPI ドキュメントの自動生成と型検証が必要な API に最適です
• Quart：非同期対応の Flask 代替で、従来型の Web アプリケーションに適しています
• AioHttp：低レベルで、高性能なサービスに適しています

データベースのルール： SQLAlchemy ORM を使用してください。生の SQL を記述するのは、以下の場合に限ります。

• ORM では効率的に表現できない複雑なクエリ
• 生の SQL のほうが測定可能なほど高速な、パフォーマンスが重要な処理
• 特定の SQL 機能が必要なレガシーデータベースとの連携

プロジェクト構成

myproject/
├── pyproject.toml
├── src/
│   └── myproject/
│       ├── __init__.py
│       ├── main.py
│       └── ...
├── tests/
│   └── ...
└── README.md

主な規約：

• パッケージには src/ レイアウトを使用する
• テストはソースコードと分ける
• すべてのプロジェクトメタデータに pyproject.toml を使用する（setup.py や setup.cfg は使用しない）

よくある間違い

間違い	正しいパターン
uv の代わりに pip を使う	環境管理には常に uv を使います
Python 3.10 以前を対象にする	devguide を確認し、3.11 以降を使います
生の SQL クエリを書く	SQLAlchemy ORM を使います
同期型の Web フレームワーク（Flask、Django）を使う	非同期型のフレームワーク（FastAPI、Quart、AioHttp）を使います
CLI に argparse を使う	Click を使います
標準ライブラリの datetime を多用する	Arrow を使います
依存関係が肥大化している	監査し、使っていないパッケージを削除します
setup.py を使う	pyproject.toml のみを使います

危険信号 — 作業を止めて確認してください

• サポート終了まで 1 年未満の Python バージョンを使っている
• SQLAlchemy を使わずに生の SQL を書いている
• 新規プロジェクトに同期型の Web フレームワークを使っている
• 正当な理由なく依存関係を追加している
• uv の代わりに pip／venv を使っている
• pyproject.toml に requires-python がない
• 非推奨のパッケージングツール（setup.py、setup.cfg）を使っている

検証

プロジェクトのセットアップを完了する前に、以下を確認してください。

1. Python バージョンを確認： uv run python --version → 3.11 以降であること
2. 依存関係を確認： uv tree → 不要なパッケージがないか確認します
3. 構成を確認： ls src/ → src レイアウトを使用していること
4. 実行をテスト： uv run python -m myproject → エラーなしで実行できること

参考資料

• Python バージョン： https://devguide.python.org/versions/
• Click： https://click.palletsprojects.com/
• Arrow： https://arrow.readthedocs.io/
• SQLAlchemy： https://docs.sqlalchemy.org/
• Alembic： https://alembic.sqlalchemy.org/
• Quart： https://quart.palletsprojects.com/
• FastAPI： https://fastapi.tiangolo.com/
• AioHttp： https://docs.aiohttp.org/
• uv のドキュメント： https://docs.astral.sh/uv/