python-pypi-package-builder

Python PyPI パッケージビルダー スキル

本番環境で使える Python ライブラリを構築し、テスト、リント、バージョン管理、型付けを行い、PyPI に公開するための、完全で実戦で検証済みのガイドです。最初のコミットからコミュニティに公開できるリリースまでを網羅します。

AI エージェントへの指示： コードを1行でも書いたり、ファイルを作成したりする前に、このファイル全体を読んでください。レイアウト、バックエンド、バージョン管理戦略、パターン、CI など、すべての判断基準がここにあります。決定ツリーに沿って順番に進めてください。このスキルは、あらゆる種類の Python パッケージ（ユーティリティ、SDK、CLI、プラグイン、データライブラリ）に適用されます。セクションを省略しないでください。

---

クイックナビゲーション

このファイルのセクション	内容
1. スキルの適用条件	このスキルを読み込むタイミング
2. パッケージの種類の判断	構築するものを特定する
3. フォルダー構成の判断	src/、フラット構成、モノレポの比較
4. ビルドバックエンドの判断	setuptools / hatchling / flit / poetry
5. PyPA パッケージングの流れ	標準的な公開パイプライン
6. プロジェクト構成テンプレート	各選択肢の完全な構成
7. バージョン管理戦略	PEP 440、semver、動的管理と静的管理

リファレンスファイル	内容
references/pyproject-toml.md	4種類すべてのバックエンドのテンプレート、setuptools_scm、py.typed、ツール設定
references/library-patterns.md	OOP/SOLID、型ヒント、コアクラスの設計、ファクトリー、プロトコル、CLI
references/testing-quality.md	conftest.py、ユニットテスト／バックエンドテスト／非同期テスト、ruff/mypy/pre-commit
references/ci-publishing.md	ci.yml、publish.yml、Trusted Publishing、TestPyPI、CHANGELOG、リリースチェックリスト
references/community-docs.md	README、docstring、CONTRIBUTING、SECURITY、アンチパターン、総合チェックリスト
references/architecture-patterns.md	バックエンドシステム（プラグイン／ストラテジー）、設定レイヤー、トランスポートレイヤー、CLI、バックエンドの注入
references/versioning-strategy.md	PEP 440、SemVer、プレリリース、setuptools_scm の詳細、flit の静的管理、判断エンジン
references/release-governance.md	ブランチ戦略、ブランチ保護、OIDC、タグ作成者の検証、無効なタグの防止
references/tooling-ruff.md	Ruff のみを使う設定（black/isort の代替）、mypy の設定、pre-commit、asyncio_mode=auto

スキャフォールドスクリプト： python skills/python-pypi-package-builder/scripts/scaffold.py --name your-package-name を実行すると、ディレクトリ構成全体、スタブファイル、pyproject.toml を1つのコマンドで生成できます。

---

1. スキルの適用条件

ユーザーが次のことを求めたときは、このスキルを読み込んでください。

• Python パッケージまたはライブラリを作成、スキャフォールド、または PyPI に公開する
• pip でインストールできる SDK、ユーティリティ、CLI ツール、またはフレームワーク拡張を構築する
• Python プロジェクトの pyproject.toml、リント、mypy、pre-commit、または GitHub Actions を設定する
• バージョン管理（setuptools_scm、PEP 440、semver、静的バージョン管理）について理解する
• PyPA 仕様（py.typed、MANIFEST.in、RECORD、分類子）について理解する
• Trusted Publishing（OIDC）または API トークンを使って PyPI に公開する
• 既存のパッケージをリファクタリングし、最新の Python パッケージング標準に準拠させる
• Python ライブラリに型ヒント、プロトコル、ABC、またはデータクラスを追加する
• Python パッケージに OOP/SOLID の設計パターンを適用する
• ビルドバックエンド（setuptools、hatchling、flit、poetry）から選択する

次のような表現がある場合も適用します： 「Python SDK を構築する」、「ライブラリを公開する」、「PyPI CI を設定する」、「pip パッケージを作成する」、「PyPI に公開する方法」、「pyproject.toml の相談」、「PEP 561 の型付け」、「setuptools_scm のバージョン」、「Python の semver」、「PEP 440」、「git タグでリリース」、「Trusted Publishing」。

---

2. パッケージの種類の判断

コードを書く前に、ユーザーが何を構築するのかを特定してください。種類ごとに異なるパターンがあります。

判断表

種類	中核となるパターン	エントリーポイント	主な依存関係	パッケージの例
ユーティリティライブラリ	純粋関数とヘルパーのモジュール	API のインポートのみ	最小限	arrow、humanize、boltons、more-itertools
API クライアント／SDK	メソッド、認証、リトライロジックを備えたクラス	API のインポートのみ	httpx または requests	boto3、stripe-python、openai
CLI ツール	コマンド関数と引数パーサー	[project.scripts] または [project.entry-points]	click または typer	black、ruff、httpie、rich
フレームワークプラグイン	プラグインクラス、フックの登録	[project.entry-points."framework.plugin"]	フレームワークの依存関係	pytest-*、django-*、flask-*
データ処理ライブラリ	クラスと関数型パイプライン	API のインポートのみ	オプション：numpy、pandas	pydantic、marshmallow、cerberus
混合型／汎用型	上記の組み合わせ	さまざま	さまざま	多数の実際のパッケージ

判断ルール： 不明な場合はユーザーに確認してください。パッケージは複数の種類を組み合わせることがあります（例：CLI エントリーポイントを備えた SDK）。構造を決める際は主な種類を適用し、追加の種類のパターンを重ねてください。

各種類の実装パターンについては、references/library-patterns.md を参照してください。

パッケージの命名規則

• PyPI 名：すべて小文字で、ハイフンを使用します — my-python-library
• Python のインポート名：アンダースコアを使用します — my_python_library
• 利用可能か確認してください：着手前に https://pypi.org/search/ を確認します
• 人気のパッケージとの名前の衝突を避けてください（まず pip install <name> が失敗することを確認します）

---

3. フォルダー構成の決定

判断ツリー

Does the package have 5+ internal modules OR multiple contributors OR complex sub-packages?
├── YES → Use src/ layout
│         Reason: prevents accidental import of uninstalled code during development;
│         separates source from project root files; PyPA-recommended for large projects.
│
├── NO → Is it a single-module, focused package (e.g., one file + helpers)?
│         ├── YES → Use flat layout
│         └── NO (medium complexity) → Use flat layout, migrate to src/ if it grows
│
└── Is it multiple related packages under one namespace (e.g., myorg.http, myorg.db)?
          └── YES → Use namespace/monorepo layout

ルールの概要

状況	使用する構成
新規プロジェクトで、将来の規模が不明	src/ レイアウト（最も安全なデフォルト）
単一目的で、モジュールが1～4個	フラットレイアウト
大規模なライブラリで、貢献者が多い	src/ レイアウト
1つのリポジトリに複数のパッケージがある	名前空間／モノレポ
古いフラット構成のプロジェクトを移行する	フラット構成を維持し、次のメジャーバージョンで src/ に移行

---

4. ビルドバックエンドの決定

判断ツリー

Does the user need version derived automatically from git tags?
├── YES → Use setuptools + setuptools_scm
│         (git tag v1.0.0 → that IS your release workflow)
│
└── NO → Does the user want an all-in-one tool (deps + build + publish)?
          ├── YES → Use poetry (v2+ supports standard [project] table)
          │
          └── NO → Is the package pure Python with no C extensions?
                    ├── YES, minimal config preferred → Use flit
                    │   (zero config, auto-discovers version from __version__)
                    │
                    └── YES, modern & fast preferred → Use hatchling
                        (zero-config, plugin system, no setup.py needed)

Does the package have C/Cython/Fortran extensions?
└── YES → MUST use setuptools (only backend with full native extension support)

バックエンドの比較

バックエンド	バージョンの取得元	設定	C 拡張	最適な用途
setuptools + setuptools_scm	git タグ（自動）	pyproject.toml + オプションの setup.py シム	対応	git タグでリリースするプロジェクト。あらゆる複雑さに対応
hatchling	手動またはプラグイン	pyproject.toml のみ	非対応	新しい純粋 Python プロジェクト。高速でモダン
flit	__init__.py の __version__	pyproject.toml のみ	非対応	非常にシンプルな単一モジュールのパッケージ
poetry	pyproject.toml のフィールド	pyproject.toml のみ	非対応	依存関係管理の統合を求めるチーム

4種類すべての完全な pyproject.toml テンプレートについては、references/pyproject-toml.md を参照してください。

---

5. PyPA のパッケージングフロー

これは、ソースコードからユーザーによるインストールまでの標準的なエンドツーエンドのフローです。 公開する前に、すべての手順を理解しておく必要があります。

1. SOURCE TREE
   Your code in version control (git)
   └── pyproject.toml describes metadata + build system

2. BUILD
   python -m build
   └── Produces two artifacts in dist/:
       ├── *.tar.gz   → source distribution (sdist)
       └── *.whl      → built distribution (wheel) — preferred by pip

3. VALIDATE
   twine check dist/*
   └── Checks metadata, README rendering, and PyPI compatibility

4. TEST PUBLISH (first release only)
   twine upload --repository testpypi dist/*
   └── Verify: pip install --index-url https://test.pypi.org/simple/ your-package

5. PUBLISH
   twine upload dist/*          ← manual fallback
   OR GitHub Actions publish.yml  ← recommended (Trusted Publishing / OIDC)

6. USER INSTALL
   pip install your-package
   pip install "your-package[extra]"

PyPA の主な概念

概念	意味
sdist	ソース配布物 — ソースとメタデータを含みます。wheel が利用できない場合に使用されます
wheel (.whl)	ビルド済みのバイナリ — pip が site-packages に直接展開するため、ビルド手順は不要です
PEP 517/518	pyproject.toml の [build-system] テーブルを介した標準ビルドシステムインターフェース
PEP 621	pyproject.toml の標準 [project] テーブル。現在のすべてのバックエンドが対応しています
PEP 639	SPDX 文字列としての license キー（例："MIT"、"Apache-2.0"）。{text = "MIT"} ではありません
PEP 561	空のマーカーファイル py.typed。パッケージに型情報が含まれていることを mypy／IDE に伝えます

CI ワークフローと公開設定の詳細については、references/ci-publishing.md を参照してください。

---

6. プロジェクト構成のテンプレート

A. src/ レイアウト（新規プロジェクトに推奨されるデフォルト）

your-package/
├── src/
│   └── your_package/
│       ├── __init__.py           # Public API: __all__, __version__
│       ├── py.typed              # PEP 561 marker — EMPTY FILE
│       ├── core.py               # Primary implementation
│       ├── client.py             # (API client type) or remove
│       ├── cli.py                # (CLI type) click/typer commands, or remove
│       ├── config.py             # Settings / configuration dataclass
│       ├── exceptions.py         # Custom exception hierarchy
│       ├── models.py             # Data classes, Pydantic models, TypedDicts
│       ├── utils.py              # Internal helpers (prefix _utils if private)
│       ├── types.py              # Shared type aliases and TypeVars
│       └── backends/             # (Plugin pattern) — remove if not needed
│           ├── __init__.py       # Protocol / ABC interface definition
│           ├── memory.py         # Default zero-dep implementation
│           └── redis.py          # Optional heavy implementation
├── tests/
│   ├── __init__.py
│   ├── conftest.py               # Shared fixtures
│   ├── unit/
│   │   ├── __init__.py
│   │   ├── test_core.py
│   │   ├── test_config.py
│   │   └── test_models.py
│   ├── integration/
│   │   ├── __init__.py
│   │   └── test_backends.py
│   └── e2e/                      # Optional: end-to-end tests
│       └── __init__.py
├── docs/                         # Optional: mkdocs or sphinx
├── scripts/
│   └── scaffold.py
├── .github/
│   ├── workflows/
│   │   ├── ci.yml
│   │   └── publish.yml
│   └── ISSUE_TEMPLATE/
│       ├── bug_report.md
│       └── feature_request.md
├── .pre-commit-config.yaml
├── pyproject.toml
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE
├── README.md
└── .gitignore

B. フラットレイアウト（小規模／特化型パッケージ）

your-package/
├── your_package/         # ← at root, not inside src/
│   ├── __init__.py
│   ├── py.typed
│   └── ... (same internal structure)
├── tests/
└── ... (same top-level files)

C. 名前空間／モノレポの構成（複数の関連パッケージ）

your-org/
├── packages/
│   ├── your-org-core/
│   │   ├── src/your_org/core/
│   │   └── pyproject.toml
│   ├── your-org-http/
│   │   ├── src/your_org/http/
│   │   └── pyproject.toml
│   └── your-org-cli/
│       ├── src/your_org/cli/
│       └── pyproject.toml
├── .github/workflows/
└── README.md

各サブパッケージには、それぞれ独自の pyproject.toml があります。PEP 420 の暗黙的な名前空間パッケージを使って your_org 名前空間を共有します（名前空間のルートには __init__.py を置きません）。

内部モジュールのガイドライン

ファイル	目的	含めるタイミング
__init__.py	公開 API の窓口、再エクスポート、__version__	常に
py.typed	PEP 561 の型付きパッケージマーカー（空ファイル）	常に
core.py	主要なクラス／メインロジック	常に
config.py	設定用のデータクラスまたは Pydantic モデル	設定可能な場合
exceptions.py	例外の階層（YourBaseError → 個別の例外）	常に
models.py	データモデル／DTO／TypedDict	データが多い場合
utils.py	内部ヘルパー（公開 API の一部ではありません）	必要に応じて
types.py	共通の TypeVar、TypeAlias、Protocol の定義	複雑な型付けが必要な場合
cli.py	CLI エントリーポイント（click/typer）	CLI 型のみ
backends/	プラグイン／ストラテジーパターン	実装を切り替え可能にする場合
_compat.py	Python バージョン互換性用のシム	3.9～3.13 との互換性が必要な場合

---

7. バージョニング戦略

PEP 440 — 標準

Canonical form:  N[.N]+[{a|b|rc}N][.postN][.devN]

Examples:
  1.0.0          Stable release
  1.0.0a1        Alpha (pre-release)
  1.0.0b2        Beta
  1.0.0rc1       Release candidate
  1.0.0.post1    Post-release (e.g., packaging fix only)
  1.0.0.dev1     Development snapshot (not for PyPI)

セマンティックバージョニング（推奨）

MAJOR.MINOR.PATCH

MAJOR: Breaking API change (remove/rename public function/class/arg)
MINOR: New feature, fully backward-compatible
PATCH: Bug fix, no API change

setuptools_scm による動的なバージョニング（Git タグを使うワークフローに推奨）

# How it works:
git tag v1.0.0          →  installed version = 1.0.0
git tag v1.1.0          →  installed version = 1.1.0
(commits after tag)     →  version = 1.1.0.post1  (suffix stripped for PyPI)

# In code — NEVER hardcode when using setuptools_scm:
from importlib.metadata import version, PackageNotFoundError
try:
    __version__ = version("your-package")
except PackageNotFoundError:
    __version__ = "0.0.0-dev"    # Fallback for uninstalled dev checkouts

必須の pyproject.toml 設定：

[tool.setuptools_scm]
version_scheme = "post-release"
local_scheme   = "no-local-version"   # Prevents +g<hash> from breaking PyPI uploads

重要： すべての CI のチェックアウト手順で、必ず fetch-depth: 0 を設定してください。Git の完全な履歴がないと、setuptools_scm はタグを見つけられず、ビルドバージョンは警告なしに 0.0.0+dev にフォールバックします。

静的なバージョニング（flit、hatchling の手動設定、poetry）

# your_package/__init__.py
__version__ = "1.0.0"    # Update this before every release

依存関係のバージョン指定に関するベストプラクティス

# In [project] dependencies:
"httpx>=0.24"            # Minimum version — PREFERRED for libraries
"httpx>=0.24,<1.0"       # Upper bound only when a known breaking change exists
"httpx==0.27.0"          # Pin exactly ONLY in applications, NOT libraries

# NEVER do this in a library — it breaks dependency resolution for users:
# "httpx~=0.24.0"        # Too tight
# "httpx==0.27.*"        # Fragile

バージョン更新からリリースまでの流れ

# 1. Update CHANGELOG.md — move [Unreleased] entries to [x.y.z] - YYYY-MM-DD
# 2. Commit the changelog
git add CHANGELOG.md
git commit -m "chore: prepare release vX.Y.Z"
# 3. Tag and push — this triggers publish.yml automatically
git tag vX.Y.Z
git push origin main --tags
# 4. Monitor GitHub Actions → verify on https://pypi.org/project/your-package/

4 つのバックエンドすべてに対応した pyproject.toml の完全なテンプレートについては、references/pyproject-toml.md を参照してください。

---

次に進むには

設計上の判断と構成を理解したら、次の手順に進みます。

1. pyproject.toml を設定する → references/pyproject-toml.md
   4 つのバックエンドのテンプレート（setuptools+scm、hatchling、flit、poetry）、ツールの完全な設定、
   py.typed の設定、バージョニングの設定。

2. ライブラリのコードを書く → references/library-patterns.md
   OOP／SOLID の原則、型ヒント（PEP 484/526/544/561）、コアクラスの設計、ファクトリー関数、
   __init__.py、プラグイン／バックエンドパターン、CLI エントリーポイント。

3. テストとコード品質の設定を追加する → references/testing-quality.md
conftest.py、単体／バックエンド／非同期テスト、パラメーター化、ruff/mypy/pre-commit の設定。

4. CI/CD を設定して公開する → references/ci-publishing.md
   Trusted Publishing（OIDC、API トークン不要）を使用する ci.yml と publish.yml、CHANGELOG の形式、
   リリースチェックリスト。

5. コミュニティ／OSS 向けに仕上げる → references/community-docs.md
   README のセクション、docstring の形式、CONTRIBUTING、SECURITY、Issue テンプレート、アンチパターン
   の表、リリースの総合チェックリスト。

6. バックエンド、設定、トランスポート、CLI を設計する → references/architecture-patterns.md
   バックエンドシステム（プラグイン／ストラテジーパターン）、設定用データクラス、HTTP トランスポート層、
   click/typer による CLI、バックエンドの注入ルール。

7. バージョニング戦略を選んで実装する → references/versioning-strategy.md
   PEP 440 の標準形式、SemVer のルール、プレリリース識別子、setuptools_scm の詳細解説、
   flit の静的バージョニング、意思決定ガイド（DEFAULT/BEGINNER/MINIMAL）。

8. リリースを管理し、公開パイプラインを保護する → references/release-governance.md
   ブランチ戦略、ブランチ保護ルール、OIDC Trusted Publishing の設定、CI でのタグ作成者の検証、
   タグ形式の強制、管理機能をすべて備えた publish.yml。

9. Ruff でツール構成をシンプルにする → references/tooling-ruff.md
   black/isort/flake8 を置き換える Ruff のみの設定、mypy の設定、pre-commit フック、
   asyncio_mode=auto（@pytest.mark.asyncio を削除）、移行ガイド。