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

本番環境対応の Python ライブラリを PyPI に構築、テスト、リント、バージョン管理、型チェック、 公開するための完全でバトルテスト済みのガイド — 最初のコミットからコミュニティ対応のリリースまで。

AI エージェント向け指示： このファイル全体を読んでから、1行のコードも記述してファイルも作成しないでください。すべての決定 — レイアウト、バックエンド、バージョン管理戦略、パターン、CI — にはここで決定ルールがあります。決定木に従って順序通りに進めてください。このスキルはあらゆる Python パッケージタイプ（ユーティリティ、SDK、CLI、プラグイン、データライブラリ）に適用できます。セクションをスキップしないでください。

---

クイックナビゲーション

このファイル内のセクション	説明内容
1. スキルトリガー	このスキルを読み込む時期
2. パッケージタイプ判定	何を構築しているか特定する
3. フォルダ構造判定	src/ vs flat vs monorepo
4. ビルドバックエンド判定	setuptools / hatchling / flit / poetry
5. PyPA パッケージング フロー	標準的な公開パイプライン
6. プロジェクト構造テンプレート	すべてのオプション向けの完全なレイアウト
7. バージョン管理戦略	PEP 440、semver、動的 vs 静的

リファレンスファイル	説明内容
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、ドキストリング、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、classifiers
• Trusted Publishing（OIDC）または API トークンを使用して PyPI に公開する
• 既存パッケージをモダン Python パッケージング標準に従うようリファクタリングする
• Python ライブラリに型ヒント、プロトコル、ABC、またはデータクラスを追加する
• OOP/SOLID デザインパターンを Python パッケージに適用する
• ビルドバックエンド（setuptools、hatchling、flit、poetry）を選択する

以下のようなフレーズでもトリガーされます： 「Python SDK を構築する」、「ライブラリを公開する」、「PyPI CI を設定する」、 「pip パッケージを作成する」、「PyPI に公開するにはどうする」、「pyproject.toml ヘルプ」、「PEP 561 型指定」、 「setuptools_scm バージョン」、「semver Python」、「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. フォルダ構造判定

判定木

パッケージが 5 個以上の内部モジュール、または複数のコントリビューター、または複雑なサブパッケージを持つ？
├── はい → src/ レイアウトを使用
│         理由：開発中に誤ってアンインストールされたコードのインポートを防止；
│         ソースをプロジェクトルートファイルから分離；大規模プロジェクト向け PyPA 推奨。
│
├── いいえ → 単一モジュール、フォーカスされたパッケージか（例：1 ファイル + ヘルパー）？
│         ├── はい → フラットレイアウトを使用
│         └── いいえ（中規模複雑さ） → フラットレイアウトを使用、拡張したら src/ に移行
│
└── 1 つのネームスペース下の複数関連パッケージか（例：myorg.http、myorg.db）？
          └── はい → ネームスペース/monorepo レイアウトを使用

クイックルール概要

状況	使用
新規プロジェクト、将来サイズ不明	src/ レイアウト（最も安全なデフォルト）
単一目的、1～4 モジュール	フラットレイアウト
大規模ライブラリ、多数のコントリビューター	src/ レイアウト
1 つのリポジトリ内の複数パッケージ	ネームスペース / monorepo
古いフラットプロジェクトのマイグレーション	フラットを保持；次のメジャーバージョンで src/ に移行

---

4. ビルドバックエンド判定

判定木

ユーザーがバージョンを git タグから自動的に導出する必要があるか？
├── はい → setuptools + setuptools_scm を使用
│         （git tag v1.0.0 → それがリリースワークフローそのもの）
│
└── いいえ → ユーザーがオールインワンツール（依存関係 + ビルド + 公開）を希望するか？
          ├── はい → poetry を使用（v2+ は標準 [project] テーブルをサポート）
          │
          └── いいえ → パッケージが C 拡張なし純 Python か？
                    ├── はい、最小限の設定を希望 → flit を使用
                    │   （ゼロ設定、__version__ から自動検出）
                    │
                    └── はい、モダン & 高速を希望 → hatchling を使用
                        （ゼロ設定、プラグインシステム、setup.py 不要）

パッケージが C/Cython/Fortran 拡張を持つか？
└── はい → setuptools を MUST で使用（ネイティブ拡張対応の唯一のバックエンド）

バックエンド比較

バックエンド	バージョンソース	設定	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. ソースツリー
   バージョン管理（git）内のコード
   └── pyproject.toml はメタデータ + ビルドシステムを記述

2. ビルド
   python -m build
   └── dist/ 内に 2 つのアーティファクトを生成：
       ├── *.tar.gz   → ソース配布（sdist）
       └── *.whl      → ビルド済み配布（wheel） — pip 優先

3. 検証
   twine check dist/*
   └── メタデータ、README レンダリング、PyPI 互換性をチェック

4. テスト公開（最初のリリースのみ）
   twine upload --repository testpypi dist/*
   └── 検証：pip install --index-url https://test.pypi.org/simple/ your-package

5. 公開
   twine upload dist/*          ← 手動フォールバック
   OR GitHub Actions publish.yml  ← 推奨（Trusted Publishing / OIDC）

6. ユーザーインストール
   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	license キーを SPDX 文字列として（例："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           # 公開 API：__all__、__version__
│       ├── py.typed              # PEP 561 マーカー — 空ファイル
│       ├── core.py               # 主要実装
│       ├── client.py             # （API クライアントタイプ）またはリムーブ
│       ├── cli.py                # （CLI タイプ）click/typer コマンド、またはリムーブ
│       ├── config.py             # 設定 / 設定データクラス
│       ├── exceptions.py         # カスタム例外階層
│       ├── models.py             # データクラス、Pydantic モデル、TypedDicts
│       ├── utils.py              # 内部ヘルパー（プライベートの場合は _utils 接頭辞）
│       ├── types.py              # 共有型エイリアス、TypeVars
│       └── backends/             # （プラグインパターン） — 不要な場合はリムーブ
│           ├── __init__.py       # プロトコル / ABC インターフェース定義
│           ├── memory.py         # デフォルトゼロ依存実装
│           └── redis.py          # オプション重い実装
├── tests/
│   ├── __init__.py
│   ├── conftest.py               # 共有フィクスチャ
│   ├── unit/
│   │   ├── __init__.py
│   │   ├── test_core.py
│   │   ├── test_config.py
│   │   └── test_models.py
│   ├── integration/
│   │   ├── __init__.py
│   │   └── test_backends.py
│   └── e2e/                      # オプション：エンドツーエンドテスト
│       └── __init__.py
├── docs/                         # オプション：mkdocs または 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/         # ← ルート内、src/ 内ではない
│   ├── __init__.py
│   ├── py.typed
│   └── ... （同じ内部構造）
├── tests/
└── ... （同じトップレベルファイル）

C. ネームスペース / Monorepo レイアウト（複数関連パッケージ）

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 / TypedDicts	データ重い場合
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 — 標準

標準形式：  N[.N]+[{a|b|rc}N][.postN][.devN]

例：
  1.0.0          安定版リリース
  1.0.0a1        アルファ（プレリリース）
  1.0.0b2        ベータ
  1.0.0rc1       リリース候補
  1.0.0.post1    ポストリリース（例：パッケージング修正のみ）
  1.0.0.dev1     開発スナップショット（PyPI 向けではない）

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

MAJOR.MINOR.PATCH

MAJOR：破壊的な API 変更（公開関数/クラス/引数の削除/名前変更）
MINOR：新機能、完全に後方互換
PATCH：バグ修正、API 変更なし

setuptools_scm を使用した動的バージョン管理（git タグワークフロー推奨）

# どのように動作するか：
git tag v1.0.0          →  インストール済みバージョン = 1.0.0
git tag v1.1.0          →  インストール済みバージョン = 1.1.0
（タグ後のコミット）     →  バージョン = 1.1.0.post1  （接尾辞は PyPI アップロード時に削除）

# コード内 — setuptools_scm 使用時は絶対にハードコードしない：
from importlib.metadata import version, PackageNotFoundError
try:
    __version__ = version("your-package")
except PackageNotFoundError:
    __version__ = "0.0.0-dev"    # アンインストール開発チェックアウト向けフォールバック

必須 pyproject.toml 設定：

[tool.setuptools_scm]
version_scheme = "post-release"
local_scheme   = "no-local-version"   # PyPI アップロード破壊の +g<hash> を防止

重要： すべての CI チェックアウトステップで常に fetch-depth: 0 を設定します。完全な git 履歴がないと、 setuptools_scm はタグを見つけられず、ビルドバージョンは沈黙裏に 0.0.0+dev にフォールバックします。

静的バージョン管理（flit、hatchling 手動、poetry）

# your_package/__init__.py
__version__ = "1.0.0"    # 毎回リリース前に更新

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

# [project] dependencies 内：
"httpx>=0.24"            # 最小バージョン — ライブラリ向け推奨
"httpx>=0.24,<1.0"       # 既知の破壊的変更が存在する場合のみ上限
"httpx==0.27.0"          # アプリケーション内でのみ正確にピン留め、ライブラリではない

# ライブラリ内では決してこれを行わない — ユーザーの依存関係解決を破壊：
# "httpx~=0.24.0"        # 厳しすぎる
# "httpx==0.27.*"        # 壊れやすい

バージョンバンプ → リリースフロー

# 1. CHANGELOG.md を更新 — [Unreleased] エントリを [x.y.z] - YYYY-MM-DD に移動
# 2. チェンジログをコミット
git add CHANGELOG.md
git commit -m "chore: prepare release vX.Y.Z"
# 3. タグをプッシュ — これにより publish.yml が自動的にトリガー
git tag vX.Y.Z
git push origin main --tags
# 4. GitHub Actions を監視 → 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、ユニット/バックエンド/非同期テスト、parametrize、ruff/mypy/pre-commit セットアップ。

4. CI/CD と公開を設定 → references/ci-publishing.md ci.yml、publish.yml (Trusted Publishing (OIDC、API トークン不要))、CHANGELOG 形式、 リリースチェックリスト。

5. コミュニティ / OSS 向けポリッシュ → references/community-docs.md README セクション、ドキストリング形式、CONTRIBUTING、SECURITY、Issue テンプレート、 アンチパターンテーブル、マスターリリースチェックリスト。

6. バックエンド、設定、トランスポート、CLI を設計 → references/architecture-patterns.md バックエンドシステム（プラグイン/ストラテジパターン）、Settings データクラス、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 Ruff のみセットアップで black/isort/flake8 置換、mypy 設定、pre-commit フック、 asyncio_mode=auto（@pytest.mark.asyncio 削除）、マイグレーションガイド。