python-packaging

Python パッケージング

最新のパッケージングツール、pyproject.toml を使用した Python パッケージの作成、構造化、配布、および PyPI への公開に関する包括的なガイドです。

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

• 配布用の Python ライブラリを作成する場合
• エントリポイントを備えたコマンドラインツールを構築する場合
• パッケージを PyPI またはプライベートリポジトリに公開する場合
• Python プロジェクトの構造を設定する場合
• 依存関係を備えたインストール可能なパッケージを作成する場合
• wheel およびソースディストリビューションをビルドする場合
• Python パッケージのバージョニングとリリースを行う場合
• 名前空間パッケージを作成する場合
• パッケージのメタデータと分類子を実装する場合

中核となる概念

1. パッケージ構造

• ソースレイアウト: src/package_name/（推奨）
• フラットレイアウト: package_name/（よりシンプルですが柔軟性は低くなります）
• パッケージメタデータ: pyproject.toml、setup.py、または setup.cfg
• 配布形式: wheel（.whl）およびソースディストリビューション（.tar.gz）

2. 最新のパッケージング標準

• PEP 517/518: ビルドシステムの要件
• PEP 621: pyproject.toml 内のメタデータ
• PEP 660: 編集可能インストール
• pyproject.toml: 設定の単一のソース

3. ビルドバックエンド

• setuptools: 伝統的で広く使用されています
• hatchling: モダンで意見が明確です
• flit: 純粋な Python 向けの軽量なツールです
• poetry: 依存関係管理 + パッケージング

4. 配布

• PyPI: Python Package Index（公開）
• TestPyPI: 本番環境前のテスト
• プライベートリポジトリ: JFrog、AWS CodeArtifact など

クイックスタート

最小限のパッケージ構造

my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
└── tests/
    └── test_module.py

最小限の pyproject.toml

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

[project]
name = "my-package"
version = "0.1.0"
description = "A short description"
authors = [{name = "Your Name", email = "[email protected]"}]
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=22.0",
]

パッケージ構造のパターン

パターン 1: ソースレイアウト（推奨）

my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── .gitignore
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       ├── utils.py
│       └── py.typed          # For type hints
├── tests/
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
└── docs/
    └── index.md

利点:

• ソースからの誤ったインポートを防止します
• テストのインポートがよりクリーンになります
• より良い分離が実現します

ソースレイアウト用の pyproject.toml:

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

パターン 2: フラットレイアウト

my-package/
├── pyproject.toml
├── README.md
├── my_package/
│   ├── __init__.py
│   └── module.py
└── tests/
    └── test_module.py

よりシンプルですが:

• インストールせずにパッケージをインポートできます
• ライブラリとしてはあまりプロフェッショナルではありません

パターン 3: マルチパッケージプロジェクト

project/
├── pyproject.toml
├── packages/
│   ├── package-a/
│   │   └── src/
│   │       └── package_a/
│   └── package-b/
│       └── src/
│           └── package_b/
└── tests/

詳細なパターンと実践例

詳細なパターンのドキュメントは references/details.md にあります。上記のナビゲーション階層では不十分な場合は、そのファイルをお読みください。