python-packaging

Python パッケージング

最新のパッケージングツール、pyproject.toml、PyPI への公開を活用して、Python パッケージを作成、構成、配布します。

呼び出すタイミング

• 配布用の Python ライブラリを作成するとき
• エントリーポイントを備えた CLI ツールを構築するとき
• PyPI またはプライベートリポジトリにパッケージを公開するとき
• Python プロジェクトの構成（src レイアウトかフラットレイアウトか）を設定するとき
• pyproject.toml、setup.py、または setup.cfg を設定するとき
• wheel とソース配布物をビルドするとき
• Python パッケージのバージョン管理とリリースを行うとき
• 名前空間パッケージや複数パッケージのプロジェクトを作成するとき

主な概念

パッケージ構成

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

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

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

ビルドバックエンド

• setuptools：従来から広く使われています
• hatchling：最新で、明確な方針を持っています
• flit：軽量で、純粋な Python 向けです
• poetry：依存関係管理とパッケージングを行います

配布

• 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.11"
dependencies = [
    "requests>=2.28.0",
]

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

ソースレイアウトの設定

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

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

ソースレイアウト（推奨）

my-package/
  pyproject.toml
  README.md
  LICENSE
  .gitignore
  src/
    my_package/
      __init__.py
      core.py
      utils.py
      py.typed
  tests/
    __init__.py
    test_core.py
    test_utils.py
  docs/
    index.md

利点：ソースからの意図しないインポートを防ぎ、テスト時のインポートをすっきりさせ、分離性を高めます。

フラットレイアウト

my-package/
  pyproject.toml
  README.md
  my_package/
    __init__.py
    module.py
  tests/
    test_module.py

よりシンプルですが、インストールせずにパッケージをインポートできます。

複数パッケージのプロジェクト

project/
  pyproject.toml
  packages/
    package-a/
      src/
        package_a/
    package-b/
      src/
        package_b/
  tests/

動的バージョン管理

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

[project]
name = "my-package"
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "my_package.__version__"}

init.py 内：

__version__ = "1.0.0"

# Or with setuptools-scm
from importlib.metadata import version
__version__ = version("my-package")

ビルドと公開

ローカルでパッケージをビルドする

pip install build twine

# Build distribution
python -m build

# Check the distribution
twine check dist/*

PyPI への公開

# Test on TestPyPI first
twine upload --repository testpypi dist/*

# Install from TestPyPI to verify
pip install --index-url https://test.pypi.org/simple/ my-package

# Publish to PyPI
twine upload dist/*

API トークンを使用する場合（推奨）：

# Create ~/.pypirc
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-...your-token...

[testpypi]
username = __token__
password = pypi-...your-test-token...

インストールのテスト

編集可能インストール

pip install -e .
pip install -e ".[dev]"
pip install -e ".[dev,docs]"

分離環境でのテスト

python -m venv test-env
source test-env/bin/activate

pip install dist/my_package-1.0.0-py3-none-any.whl
python -c "import my_package; print(my_package.__version__)"
my-tool --help

deactivate
rm -rf test-env

バージョン制約

dependencies = [
    "requests>=2.28.0,<3.0.0",  # Compatible range
    "click~=8.1.0",              # Compatible release (>=8.1.0,<8.2.0)
    "pydantic>=2.0",             # Minimum version
    "numpy==1.24.3",             # Exact version (avoid if possible)
]

ベストプラクティス

1. src/ レイアウトを使用すると、パッケージ構成がすっきりします
2. 最新のパッケージングには pyproject.toml を使用する
3. build-system.requires で ビルド依存関係を固定する
4. セマンティックバージョニングを使って 適切にバージョン管理する
5. すべてのメタデータを含める（分類子、URL など）
6. クリーンな環境で インストールをテストする
7. PyPI に公開する前に TestPyPI を使用する
8. README と docstring で 十分にドキュメントを整備する
9. LICENSE ファイルを含める
10. CI/CD で 公開を自動化する

公開チェックリスト

• コードのテストが完了している（pytest が成功する）
• ドキュメントが完成している（README、docstring）
• バージョン番号を更新した
• CHANGELOG.md を更新した
• ライセンスファイルを含めた
• pyproject.toml が完成している
• パッケージがエラーなくビルドできる
• クリーンな環境でインストールをテストした
• CLI ツールが動作する（該当する場合）
• PyPI メタデータが正しい（分類子、キーワード）
• GitHub リポジトリをリンクした
• 先に TestPyPI でテストした
• リリース用の Git タグを作成した

参考資料

• references/packaging-guide.md - すべてのツール設定を含む包括的な pyproject.toml の例、CLI のパターン（Click と argparse）、GitHub Actions を使った CI/CD 公開、マルチアーキテクチャ wheel、データファイル、名前空間パッケージ、C 拡張、Git ベースのバージョン管理、プライベートパッケージインデックス、ファイルテンプレート（.gitignore、MANIFEST.in、README.md）

リソース

• Python Packaging Guide：https://packaging.python.org/
• PyPI：https://pypi.org/
• TestPyPI：https://test.pypi.org/
• setuptools のドキュメント：https://setuptools.pypa.io/
• build：https://pypa-build.readthedocs.io/
• twine：https://twine.readthedocs.io/