Modern Python

最新のPythonツーリングとベストプラクティスの ガイドです。trailofbits/cookiecutter-python に基づいています。

このスキルを使用する場合

• 新しいPythonプロジェクトやパッケージを作成する場合
• pyproject.toml の設定を行う場合
• 開発ツール (linting、formatting、testing) を設定する場合
• 外部依存関係を持つPythonスクリプトを記述する場合
• レガシーツールからの移行を行う場合 (ユーザーが明示的に要求した場合)

このスキルを使用しない場合

• ユーザーがレガシーツールを維持したい場合: 明示的に要求されている場合は既存のワークフローを尊重する
• Python < 3.11 が必須の場合: これらのツールは最新のPythonを対象としている
• 非Pythonプロジェクト: Pythonがメインではない混在するコードベース

避けるべきアンチパターン

避けるべき	代わりに使用する
[tool.ty] python-version	[tool.ty.environment] python-version
uv pip install	uv add と uv sync
依存関係を追加するために pyproject.toml を手動編集	uv add <pkg> / uv remove <pkg>
hatchling ビルドバックエンド	uv_build (シンプルで、ほとんどのケースに十分)
Poetry	uv (高速、シンプル、優れたエコシステム統合)
requirements.txt	スクリプトの場合は PEP 723、プロジェクトの場合は pyproject.toml
mypy / pyright	ty (高速、Astral チームより)
[project.optional-dependencies] でのdev ツール管理	[dependency-groups] (PEP 735)
仮想環境の手動アクティベーション (source .venv/bin/activate)	uv run <cmd>
pre-commit	prek (高速、Python ランタイムが不要)

主な原則:

• 常に uv add と uv remove を使用して依存関係を管理する
• 仮想環境を手動でアクティベートまたは管理しない。すべてのコマンドで uv run を使用する
• dev/test/docs 依存関係には [dependency-groups] を使用し、[project.optional-dependencies] は使用しない

デシジョンツリー

何を行っていますか？
│
├─ 依存関係を持つシングルファイルスクリプト？
│   └─ PEP 723 インラインメタデータを使用 (./references/pep723-scripts.md)
│
├─ 新しいマルチファイルプロジェクト (配布しない)？
│   └─ 最小限の uv セットアップ (下記の「クイックスタート」を参照)
│
├─ 新しい再利用可能なパッケージ/ライブラリ？
│   └─ 完全なプロジェクトセットアップ (下記の「フルセットアップ」を参照)
│
└─ 既存プロジェクトの移行？
    └─ 下記の「移行ガイド」を参照

ツール概要

ツール	目的	置き換える
uv	パッケージ/依存関係管理	pip、virtualenv、pip-tools、pipx、pyenv
ruff	Linting と formatting	flake8、black、isort、pyupgrade、pydocstyle
ty	型チェック	mypy、pyright (高速な代替手段)
pytest	カバレッジ付きテスト	unittest
prek	pre-commit フック (セットアップ)	pre-commit (高速、Rust ネイティブ)

セキュリティツール

ツール	目的	実行タイミング
shellcheck	シェルスクリプト linting	pre-commit
detect-secrets	シークレット検出	pre-commit
actionlint	ワークフロー構文検証	pre-commit、CI
zizmor	ワークフローセキュリティ監査	pre-commit、CI
pip-audit	依存関係の脆弱性スキャン	CI、手動
Dependabot	依存関係の自動更新	スケジュール実行

設定と使用方法については security-setup.md を参照してください。

クイックスタート: 最小プロジェクト

配布を目的としない単純なマルチファイルプロジェクト向け:

# uv でプロジェクトを作成
uv init myproject
cd myproject

# 依存関係を追加
uv add requests rich

# 開発用依存関係を追加
uv add --group dev pytest ruff ty

# コードを実行
uv run python src/myproject/main.py

# ツールを実行
uv run pytest
uv run ruff check .

フルプロジェクトセットアップ

ゼロから始める場合は、ユーザーに Trail of Bits の cookiecutter テンプレートを使用して、すでに設定されている完全なプロジェクトを起動するかどうかを確認してください。

uvx cookiecutter gh:trailofbits/cookiecutter-python

1. プロジェクト構造を作成

uv init --package myproject
cd myproject

以下の構造を作成します:

myproject/
├── pyproject.toml
├── README.md
├── src/
│   └── myproject/
│       └── __init__.py
└── .python-version

2. pyproject.toml を設定

完全な設定リファレンスについては pyproject.md を参照してください。

主要なセクション:

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = []

[dependency-groups]
dev = [{include-group = "lint"}, {include-group = "test"}, {include-group = "audit"}]
lint = ["ruff", "ty"]
test = ["pytest", "pytest-cov"]
audit = ["pip-audit"]

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["ALL"]
ignore = ["D", "COM812", "ISC001"]

[tool.pytest]
addopts = ["--cov=myproject", "--cov-fail-under=80"]

[tool.ty.terminal]
error-on-warning = true

[tool.ty.environment]
python-version = "3.11"

[tool.ty.rules]
# 新しいプロジェクトから厳密性を維持
possibly-unresolved-reference = "error"
unused-ignore-comment = "warn"

3. 依存関係をインストール

# すべての依存関係グループをインストール
uv sync --all-groups

# または特定のグループをインストール
uv sync --group dev

4. Makefile を追加

.PHONY: dev lint format test build

dev:
	uv sync --all-groups

lint:
	uv run ruff format --check && uv run ruff check && uv run ty check src/

format:
	uv run ruff format .

test:
	uv run pytest

build:
	uv build

移行ガイド

ユーザーがレガシーツールからの移行を要求した場合:

requirements.txt + pip からの移行

まず、コードの性質を決定します:

スタンドアロンスクリプトの場合: PEP 723 インラインメタデータに変換 (pep723-scripts.md を参照)

プロジェクトの場合:

# 既存プロジェクトで uv を初期化
uv init --bare

# uv を使用して依存関係を追加 (pyproject.toml を手動編集しない)
uv add requests rich  # 各パッケージを追加

# または requirements.txt からインポート (各パッケージを確認してから追加)
# 注: 複雑なバージョン指定子は手動対応が必要な場合があります
grep -v '^#' requirements.txt | grep -v '^-' | grep -v '^\s*$' | while read -r pkg; do
    uv add "$pkg" || echo "Failed to add: $pkg"
done

uv sync

その後:

1. requirements.txt、requirements-dev.txt を削除
2. 仮想環境を削除 (venv/、.venv/)
3. uv.lock をバージョン管理に追加

setup.py / setup.cfg からの移行

1. uv init --bare を実行して pyproject.toml を作成
2. uv add を使用して install_requires から各依存関係を追加
3. 開発用依存関係に uv add --group dev を使用
4. 非依存メタデータ (name、version、description など) を [project] にコピー
5. setup.py、setup.cfg、MANIFEST.in を削除

flake8 + black + isort からの移行

1. uv remove で flake8、black、isort を削除
2. .flake8、pyproject.toml の [tool.black]、[tool.isort] 設定を削除
3. ruff を追加: uv add --group dev ruff
4. ruff 設定を追加 (ruff-config.md を参照)
5. uv run ruff check --fix . を実行して修正を適用
6. uv run ruff format . を実行してフォーマット

mypy / pyright からの移行

1. uv remove で mypy/pyright を削除
2. mypy.ini、pyrightconfig.json、または [tool.mypy]/[tool.pyright] セクションを削除
3. ty を追加: uv add --group dev ty
4. uv run ty check src/ を実行

クイックリファレンス: uv コマンド

コマンド	説明
uv init	新しいプロジェクトを作成
uv init --package	配布可能なパッケージを作成
uv add <pkg>	依存関係を追加
uv add --group dev <pkg>	依存関係グループに追加
uv remove <pkg>	依存関係を削除
uv sync	依存関係をインストール
uv sync --all-groups	すべての依存関係グループをインストール
uv run <cmd>	venv でコマンドを実行
uv run --with <pkg> <cmd>	一時的な依存関係で実行
uv build	パッケージをビルド
uv publish	PyPI に公開

--with を使用したアドホック依存関係

プロジェクトに含まれていないパッケージが必要なワンオフコマンドに uv run --with を使用します:

# 一時的なパッケージで Python を実行
uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"

# 一時的な依存関係でモジュールを実行
uv run --with rich python -m rich.progress

# 複数のパッケージ
uv run --with requests --with rich python script.py

# プロジェクト依存関係と組み合わせ (既存の venv に追加)
uv run --with httpx pytest  # プロジェクト依存関係 + httpx

--with と uv add をどちらを使用するか:

• uv add: パッケージがプロジェクト依存関係 (pyproject.toml/uv.lock に追加)
• --with: ワンオフ使用、テスト、またはプロジェクト外のスクリプト

完全なリファレンスについては uv-commands.md を参照してください。

クイックリファレンス: 依存関係グループ

[dependency-groups]
dev = ["ruff", "ty"]
test = ["pytest", "pytest-cov", "hypothesis"]
docs = ["sphinx", "myst-parser"]

インストール: uv sync --group dev --group test

ベストプラクティスチェックリスト

• パッケージに src/ レイアウトを使用
• requires-python = ">=3.11" を設定
• select = ["ALL"] と明示的な無視で ruff を設定
• 型チェックに ty を使用
• テストカバレッジの最小値を強制 (80% 以上)
• dev ツールには extras ではなく依存関係グループを使用
• uv.lock をバージョン管理に追加
• スタンドアロンスクリプトに PEP 723 を使用

次のステップ

• migration-checklist.md - ステップバイステップの移行クリーンアップ
• pyproject.md - 完全な pyproject.toml リファレンス
• uv-commands.md - uv コマンドリファレンス
• ruff-config.md - Ruff linting/formatting 設定
• testing.md - pytest とカバレッジセットアップ
• pep723-scripts.md - PEP 723 インラインスクリプトメタデータ
• prek.md - prek を使用した高速 pre-commit フック
• security-setup.md - セキュリティフックと依存関係スキャン
• dependabot.md - 依存関係の自動更新