setting-up-python-libraries

Python ライブラリプロジェクトのセットアップ

クイックスタート

次の構成で新しいライブラリを作成します。

my-library/
├── src/my_library/
│   ├── __init__.py
│   └── py.typed
├── tests/
├── pyproject.toml
├── Makefile
├── .pre-commit-config.yaml
└── .github/workflows/ci.yml

開発用コードが誤ってインポートされるのを防ぐため、src/ レイアウトを使用します。

基本設定

テンプレートの全体については、次を参照してください。

• PYPROJECT.md - すべてのツール設定を含む完全な pyproject.toml
• CI.md - GitHub Actions と pre-commit のセットアップ
• MAKEFILE.md - Makefile による自動化のパターン

最小限の pyproject.toml

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-library"
version = "0.1.0"
description = "What it does"
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"  # SPDX expression
dependencies = []

[project.optional-dependencies]
dev = ["pytest>=7.0", "ruff>=0.1", "mypy>=1.0"]

[tool.setuptools.packages.find]
where = ["src"]

必須コマンド

# Setup
uv sync --extra dev
pre-commit install

# Daily workflow
ruff check src tests        # Lint
ruff format src tests       # Format
pytest                      # Test
mypy src                    # Type check

ローカルチェックを CI と同じに保つ

CI で最もよくある失敗はバグではありません。ローカルでは通るチェックが CI では失敗する（またはその逆）という、実行するコマンドが異なることによる問題です。次の 2 つのルールを守れば、「ローカルでは成功、CI では失敗」（そしてベースブランチが慢性的に失敗状態）になる問題の多くを防げます。

1. make lint は読み取り専用にし、--fix は使わないでください。 ruff check --fix を実行する lint ターゲットはファイルを変更し、ほとんどの場合終了コード 0 で終了するため、既存の違反がブランチに気付かれずに残る一方で、CI の読み取り専用 ruff check は失敗します。--fix は format と pre-commit フックでのみ使用してください。make lint では、CI で実行するコマンドとまったく同じコマンドを実行する必要があります。

2. CI（および make lint）ではフォーマットもチェックしてください。 ruff check と ruff format は異なるツールです。リンターに合格しても、フォーマットについては何も保証されません。両方を必須にしないと、フォーマットのずれがそのまま反映されたり、予期せずブランチが失敗状態になったりします。

ruff check src tests          # lint rules
ruff format --check src tests # formatting — REQUIRED, not implied by ruff check

Makefile と CI では、同じパスをリンティングしてください（Python を含む場合は examples/、docs/ なども追加してください）。ローカルの対象範囲が狭いと、CI がチェックするディレクトリに違反が蓄積します。ruff の設定は、非推奨のトップレベル select／ignore ではなく [tool.ruff.lint] に記述してください。また、ruff がサポートしていないバージョン向けのアップグレードルールを適用しないよう、requires-python と [tool.ruff] target-version の値を一致させてください。

カバレッジについては、サードパーティーサービスにアップロードするより、CI のログにターミナルレポート（--cov-report=term-missing）を出力する pytest --cov の実行をおすすめします。ゲートに外部アカウント、トークン、ネットワーク依存が不要になります。

主な選択事項

選択肢	推奨事項	理由
レイアウト	src/	パッケージングの問題を早期に検出できます
ビルドバックエンド	setuptools	成熟しており、幅広い互換性があります
リンター	ruff	高速で、flake8、isort、black を置き換えます
Python のバージョン範囲	>=3.10	バージョンを厳密に固定しないでください
依存関係	最小限	オプションの依存関係は extras に移します

チェックリスト

Project Setup:
- [ ] src/ layout with py.typed marker
- [ ] pyproject.toml (not setup.py)
- [ ] Makefile with dev/test/lint/format (lint read-only, no --fix)
- [ ] `make lint` runs the exact `ruff check` + `ruff format --check` CI runs
- [ ] Build-gating tools pinned (linter, formatter, toolchain, test runner) so upstream releases don't flip green/red on unrelated PRs
- [ ] .pre-commit-config.yaml
- [ ] .github/workflows/ci.yml
- [ ] README.md, LICENSE, CHANGELOG.md
- [ ] .gitignore

ヘルパースクリプト

新しいプロジェクト構成を作成します。

python scripts/create_project.py my-library --author "Name" --license MIT

--license には SPDX 識別子を指定します（デフォルトは MIT）。MIT と BSD-3-Clause の場合は LICENSE ファイルが生成されます。

詳細情報

このスキルは、Will McGinnis による 高品質な Python ライブラリを開発するためのガイド を基にしています。詳しい解説については、次の記事を参照してください。

• ライブラリの範囲を定義する
• 依存関係の管理
• プロジェクトのライセンスを選ぶ
• pyproject.toml の解説