Zenn
🦄

Python Packaging Authority (PyPA) ドキュメント要約

2025/04/07に公開
Python
tech

概要

Python Packaging Authority (PyPA) は、Pythonのパッケージング関連ツールとライブラリの開発・維持を担当する作業グループです。PyPAは、Pythonパッケージのビルド、配布、インストールに関する標準とツールを提供しています。このドキュメントでは、PyPAのサイトで提供されている主要な情報とガイドラインを要約します。

https://packaging.python.org/en/latest/tutorials/installing-packages/

PyPAの目的

PyPAの主な目的は以下の通りです：

  1. 標準化: Pythonパッケージングの標準とベストプラクティスを確立する
  2. ツール開発: パッケージング関連ツール（pip, setuptools, wheel, twine など）の開発と保守
  3. 情報提供: パッケージングに関する包括的なドキュメントとガイダンスの提供
  4. コミュニティ支援: パッケージング関連の問題に対するコミュニティのサポート

プロジェクト構造とパッケージ化のベストプラクティス

PyPAドキュメントでは、以下のプロジェクト構造とパッケージ化に関するベストプラクティスを推奨しています：

1. 推奨されるプロジェクト構造

project_name/
├── LICENSE
├── pyproject.toml
├── README.md
├── src/
│   └── package_name/
│       ├── __init__.py
│       ├── module1.py
│       └── module2.py
└── tests/
    ├── __init__.py
    ├── test_module1.py
    └── test_module2.py

特に「src」レイアウト（ソースコードを src/ ディレクトリ内に配置）が強く推奨されています。この構造には以下の利点があります：

  • インポートの明確化
  • 開発モードとインストールモードの動作が一致する
  • テストがインストールされたパッケージを使用することを保証
  • 偶発的なインポートの防止

2. パッケージ構成ファイル

PyPAでは現在、pyproject.tomlを使用したプロジェクト構成を推奨しています：

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

[project]
name = "package_name"
version = "0.1.0"
description = "A short description of the package"
readme = "README.md"
authors = [
    {name = "Your Name", email = "your.email@example.com"}
]
license = {text = "MIT"}
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]
requires-python = ">=3.7"
dependencies = [
    "dependency1>=1.0.0",
    "dependency2>=2.0.0",
]

[project.urls]
"Homepage" = "https://github.com/yourusername/package_name"
"Bug Tracker" = "https://github.com/yourusername/package_name/issues"

[tool.setuptools]
package-dir = {"" = "src"}
packages = ["package_name"]

従来の setup.py と setup.cfg の代わりに、単一の pyproject.toml ファイルを使用することでプロジェクト構成がシンプルになります。

3. インポートに関する推奨事項

PyPAドキュメントでは、パッケージ化を前提としたインポートに関して以下の推奨事項を提供しています：

  1. 開発時のインストール: 開発中でもパッケージを開発モードでインストールする

    pip install -e .

  2. 絶対インポートの使用: パッケージ内でも絶対インポートを基本とする

    # 良い例
from package_name.submodule import function

# 避けるべき例（開発時だけ動作）
from src.package_name.submodule import function

  3. 相対インポートの限定的使用: 同一パッケージ内でのみ相対インポートを使用

    # 同一パッケージ内での相対インポート
from .submodule import function

パッケージングプロセス

PyPAでは、以下のパッケージング手順を推奨しています：

1. プロジェクトの準備

必要なファイル（pyproject.toml, README.md, LICENSEなど）を作成し、適切なプロジェクト構造を設定します。

2. ビルドツールのインストール

python -m pip install --upgrade pip
python -m pip install --upgrade build

3. パッケージのビルド

python -m build

これにより、dist/ ディレクトリに以下のディストリビューションが作成されます：

  • Source Distribution (.tar.gz)
  • Wheel Distribution (.whl)

4. パッケージのアップロード

PyPIにパッケージをアップロードする場合：

python -m pip install --upgrade twine
python -m twine upload dist/*

環境管理とパッケージングツール

PyPAドキュメントでは、以下のツールについても説明しています：

  1. pip: パッケージのインストールと管理
  2. venv/virtualenv: 分離された環境の作成
  3. setuptools: パッケージビルドと配布の基本ツール
  4. wheel: バイナリパッケージフォーマット
  5. twine: PyPIへのパッケージアップロード
  6. build: パッケージビルドプロセスの標準化ツール

また、以下の代替ツールについても言及しています：

  1. poetry: 依存関係管理とパッケージング機能を統合
  2. flit: シンプルなPythonパッケージング用ツール
  3. hatch: モダンなPythonパッケージングツール

パッケージインストールとインポートの関係

PyPAドキュメントでは、パッケージのインストール方法とインポートパスの関係について以下の点を強調しています：

  1. 通常インストール (pip install package_name): パッケージは site-packages ディレクトリにインストールされ、パッケージ名でインポート可能になります。

  2. 開発モードインストール (pip install -e .): プロジェクトディレクトリへの参照が作成され、コードの変更がすぐに反映されます。インポートはインストール済みパッケージと同じパスで行います。

  3. アンインストール済み状態: src レイアウトを使用している場合、インストールせずに直接インポートしようとすると失敗します（意図的な設計）。

まとめ

Python Packaging Authority (PyPA) は、Pythonパッケージングの標準とツールの開発・維持を担当する重要な組織です。PyPAのドキュメントは、プロジェクト構造、パッケージ化プロセス、インポート方法など、Pythonパッケージング全般に関する包括的なガイダンスを提供しています。特に「src」レイアウトの採用と、開発モードでのパッケージインストールが強く推奨されており、これらの実践によりインポートパス問題を効果的に解決できます。

モダンなPythonプロジェクトでは、pyproject.tomlを使用し、明確なプロジェクト構造を持ち、適切なパッケージングとインポート手法を採用することで、メンテナンス性と配布の容易さを高めることができます。

Discussion