modern-python

モダンな Python

trailofbits/cookiecutter-python に基づいた、モダンな Python ツールとベストプラクティスのガイドです。

このスキルを使う場面

• 新しい Python プロジェクトまたはパッケージを作成する
• pyproject.toml の設定を行う
• 開発ツール（Lint、フォーマット、テスト）を設定する
• 外部依存関係を使用する 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] を使う	[dependency-groups]（PEP 735）
仮想環境を手動で有効化する（source .venv/bin/activate）	uv run <cmd>
pre-commit	prek（より高速で、Python ランタイムが不要）

主な原則：

• 依存関係の管理には必ず uv add と uv remove を使います
• 仮想環境を手動で有効化または管理しないでください。すべてのコマンドに uv run を使います
• 開発／テスト／ドキュメント用の依存関係には [project.optional-dependencies] ではなく、[dependency-groups] を使います

判断フロー

What are you doing?
│
├─ Single-file script with dependencies?
│   └─ Use PEP 723 inline metadata (./references/pep723-scripts.md)
│
├─ New multi-file project (not distributed)?
│   └─ Minimal uv setup (see Quick Start below)
│
├─ New reusable package/library?
│   └─ Full project setup (see Full Setup below)
│
└─ Migrating existing project?
    └─ See Migration Guide below

ツールの概要

ツール	目的	置き換えるもの
uv	パッケージ／依存関係の管理	pip、virtualenv、pip-tools、pipx、pyenv
ruff	Lint とフォーマット	flake8、black、isort、pyupgrade、pydocstyle
ty	型チェック	mypy、pyright（より高速な代替ツール）
pytest	カバレッジを含むテスト	unittest
prek	pre-commit フック（セットアップ）	pre-commit（より高速で、Rust ネイティブ）

セキュリティツール

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

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

クイックスタート：最小限のプロジェクト

配布を目的としない、シンプルな複数ファイルのプロジェクトの場合：

# Create project with uv
uv init myproject
cd myproject

# Add dependencies
uv add requests rich

# Add dev dependencies
uv add --group dev pytest ruff ty

# Run code
uv run python src/myproject/main.py

# Run tools
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]
# Strict from day 1 for new projects
possibly-unresolved-reference = "error"
unused-ignore-comment = "warn"

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

# Install all dependency groups
uv sync --all-groups

# Or install specific 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 を参照）

プロジェクトの場合：

# Initialize uv in existing project
uv init --bare

# Add dependencies using uv (not by editing pyproject.toml)
uv add requests rich  # add each package

# Or import from requirements.txt (review each package before adding)
# Note: Complex version specifiers may need manual handling
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>	仮想環境でコマンドを実行
uv run --with <pkg> <cmd>	一時的な依存関係を使って実行
uv build	パッケージをビルド
uv publish	PyPI に公開

--with を使ったアドホックな依存関係

プロジェクトに含まれていないパッケージが必要な単発のコマンドには、uv run --with を使います：

# Run Python with a temporary package
uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"

# Run a module with temporary deps
uv run --with rich python -m rich.progress

# Multiple packages
uv run --with requests --with rich python script.py

# Combine with project deps (adds to existing venv)
uv run --with httpx pytest  # project deps + 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% 以上）を適用します
• 開発ツールには extras ではなく依存関係グループを使います
• uv.lock をバージョン管理に追加します
• スタンドアロンのスクリプトには PEP 723 を使います

次に読む

• migration-checklist.md - 移行時のクリーンアップ手順
• pyproject.md - pyproject.toml の完全なリファレンス
• uv-commands.md - uv コマンドのリファレンス
• ruff-config.md - Ruff のリンティング／フォーマット設定
• testing.md - pytest とカバレッジの設定
• pep723-scripts.md - PEP 723 のインラインスクリプトメタデータ
• prek.md - prek による高速なコミット前フック
• security-setup.md - セキュリティフックと依存関係のスキャン
• dependabot.md - 依存関係の自動更新