Poetry Packaging

Poetry によるパッケージング

概要

Poetry を使った最新の Python 依存関係管理とパッケージングを習得します。再現可能なビルドと明確な依存関係解決により、プロフェッショナルな Python パッケージを作成、管理、公開する方法を学びます。

学習目標

• Poetry でプロジェクトの依存関係を管理する
• Python パッケージを作成して公開する
• バージョン制約と依存関係の解決に対応する
• ベストプラクティスに沿ってプロジェクトを構成する
• セマンティックバージョニングを導入する
• パッケージングのワークフローを自動化する

主なトピック

1. Poetry の基本

• Poetry のインストール
• 新しいプロジェクトの作成
• 依存関係の管理
• 仮想環境の管理
• ロックファイルと再現性
• Poetry のコマンドとワークフロー

コード例：

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Create new project
poetry new my-awesome-package
cd my-awesome-package

# Project structure created:
# my-awesome-package/
# ├── my_awesome_package/
# │   └── __init__.py
# ├── tests/
# │   └── __init__.py
# ├── pyproject.toml
# └── README.md

# Add dependencies
poetry add requests
poetry add pandas numpy
poetry add --group dev pytest black mypy

# Install dependencies
poetry install

# Run commands in virtual environment
poetry run python main.py
poetry run pytest

# Update dependencies
poetry update

# Show dependency tree
poetry show --tree

# Export to requirements.txt
poetry export -f requirements.txt --output requirements.txt

2. pyproject.toml の設定

• プロジェクトのメタデータ
• 依存関係の指定
• バージョン制約
• 開発用の依存関係
• ビルドシステムの設定
• スクリプトとエントリーポイント

コード例：

# pyproject.toml
[tool.poetry]
name = "my-awesome-package"
version = "0.1.0"
description = "An awesome Python package"
authors = ["Your Name <[email protected]>"]
license = "MIT"
readme = "README.md"
homepage = "https://github.com/username/my-awesome-package"
repository = "https://github.com/username/my-awesome-package"
documentation = "https://my-awesome-package.readthedocs.io"
keywords = ["awesome", "package", "python"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
]

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28.0"
pandas = "^2.0.0"
click = "^8.1.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0.0"
pytest-cov = "^4.0.0"
black = "^23.0.0"
mypy = "^1.0.0"
ruff = "^0.1.0"

[tool.poetry.scripts]
my-cli = "my_awesome_package.cli:main"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

# Version constraints examples:
# ^2.0.0  = >=2.0.0 <3.0.0  (caret)
# ~2.0.0  = >=2.0.0 <2.1.0  (tilde)
# 2.0.*   = >=2.0.0 <2.1.0  (wildcard)
# >=2.0.0 = 2.0.0 or higher (range)

3. パッケージの構成と公開

• パッケージ構成のベストプラクティス
• セマンティックバージョニングによるバージョン管理
• 配布パッケージ（sdist、wheel）のビルド
• PyPI/TestPyPI への公開
• パッケージのメタデータ
• ドキュメントの生成

コード例：

# Recommended package structure
my-awesome-package/
├── my_awesome_package/
│   ├── __init__.py           # Package initialization
│   ├── core.py               # Core functionality
│   ├── utils.py              # Utility functions
│   ├── cli.py                # Command-line interface
│   └── py.typed              # Type hints marker
├── tests/
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
├── docs/
│   ├── index.md
│   └── api.md
├── examples/
│   └── basic_usage.py
├── pyproject.toml
├── README.md
├── LICENSE
├── CHANGELOG.md
└── .gitignore

# my_awesome_package/__init__.py
"""
My Awesome Package

A comprehensive package for doing awesome things.
"""

__version__ = "0.1.0"
__author__ = "Your Name"
__email__ = "[email protected]"

from .core import main_function
from .utils import helper_function

__all__ = ["main_function", "helper_function"]

# Publishing workflow
# 1. Update version in pyproject.toml
poetry version patch  # 0.1.0 -> 0.1.1
poetry version minor  # 0.1.1 -> 0.2.0
poetry version major  # 0.2.0 -> 1.0.0

# 2. Build package
poetry build
# Creates dist/my_awesome_package-0.1.0.tar.gz
# Creates dist/my_awesome_package-0.1.0-py3-none-any.whl

# 3. Publish to TestPyPI first
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish -r testpypi

# 4. Test installation
pip install --index-url https://test.pypi.org/simple/ my-awesome-package

# 5. Publish to PyPI
poetry publish

# 6. Create git tag
git tag v0.1.0
git push origin v0.1.0

4. 高度な機能

• モノレポの管理
• プラグインシステム
• カスタムビルドスクリプト
• プライベートなパッケージリポジトリ
• CI/CD との統合
• 依存関係グループ

コード例：

# Advanced pyproject.toml configuration

[tool.poetry]
name = "advanced-package"
version = "1.0.0"
description = "Advanced packaging example"

# Include/exclude files
include = ["my_package/data/*.json"]
exclude = ["my_package/tests/*"]

[tool.poetry.dependencies]
python = "^3.9"

# Optional dependencies (extras)
psycopg2 = { version = "^2.9", optional = true }
mysqlclient = { version = "^2.1", optional = true }

[tool.poetry.extras]
postgresql = ["psycopg2"]
mysql = ["mysqlclient"]
all = ["psycopg2", "mysqlclient"]

# Multiple dependency groups
[tool.poetry.group.test.dependencies]
pytest = "^7.0.0"
pytest-cov = "^4.0.0"

[tool.poetry.group.docs.dependencies]
sphinx = "^5.0.0"
sphinx-rtd-theme = "^1.0.0"

[tool.poetry.group.lint.dependencies]
black = "^23.0.0"
ruff = "^0.1.0"
mypy = "^1.0.0"

# Platform-specific dependencies
[tool.poetry.dependencies.pywin32]
version = "^305"
platform = "win32"

# Plugins
[tool.poetry.plugins."my_package.plugins"]
plugin1 = "my_package.plugins:plugin1"

# CI/CD with GitHub Actions
# .github/workflows/publish.yml
name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install Poetry
        run: curl -sSL https://install.python-poetry.org | python3 -
      - name: Build and publish
        env:
          POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
        run: |
          poetry build
          poetry publish

実践演習

プロジェクト 1：CLI ツールパッケージ

コマンドラインツールを作成し、PyPI に公開します。

要件：

• Click/Typer で CLI を構築する
• 複数のサブコマンドを追加する
• 設定ファイルに対応する
• 包括的なテストを作成する
• ドキュメントを生成する
• PyPI に公開する

主なスキル： Poetry、CLI 開発、パッケージング

プロジェクト 2：ライブラリパッケージ

使いやすい API を備えた再利用可能なライブラリを開発します。

要件：

• 公開 API を設計する
• 全体に型ヒントを付ける
• 包括的な docstring を記述する
• 単体テストと統合テストを作成する
• API ドキュメントを作成する
• バージョン管理戦略を立てる

主なスキル： API 設計、ドキュメント作成、テスト

プロジェクト 3：プラグインシステム

プラグインアーキテクチャを備えたパッケージを作成します。

要件：

• プラグインの検出メカニズム
• エントリーポイントの設定
• プラグイン API の仕様
• プラグインのサンプル
• プラグインのドキュメント
• 配布戦略

主なスキル： 高度なパッケージング、アーキテクチャ

評価基準

• Poetry でプロジェクトを作成する
• 依存関係を効果的に管理する
• バージョン制約を理解する
• パッケージをビルドして公開する
• プロジェクトをプロフェッショナルな構成にする
• 明確なパッケージメタデータを記述する
• セマンティックバージョニングを導入する

リソース

公式ドキュメント

• Poetry Docs - 公式ドキュメント
• PyPI - Python Package Index
• Packaging Guide - Python パッケージングの公式ガイド

学習プラットフォーム

• Python Packaging - Real Python のガイド
• Modern Python Packaging - 動画チュートリアル
• Poetry Tutorial - 包括的なガイド

ツール

• Poetry - 依存関係管理
• Twine - PyPI アップロードツール
• bump2version - バージョンの更新
• setuptools - 代替のパッケージングツール

次のステップ

Poetry を習得したら、以下について学びましょう。

• Docker - コンテナー化されたパッケージング
• GitHub Actions - 公開の自動化
• Read the Docs - ドキュメントのホスティング
• Pre-commit - コード品質の自動化