言語バージョン管理ツール

Poetry

概要

Poetryは、Pythonプロジェクトの依存関係管理、パッケージング、仮想環境管理を統合したモダンなツールです。pyproject.tomlファイルによる設定管理とpoetry.lockファイルによる決定論的な依存関係解決により、再現可能なPython開発環境を提供します。NPMやYarnに触発された、現代的なPython開発ワークフローを実現します。

詳細

主な特徴

• 統合された依存関係管理: パッケージのインストール、更新、削除を一元管理
• 決定論的ビルド: poetry.lockファイルによる再現可能な環境
• 自動仮想環境管理: プロジェクトごとの独立した環境を自動作成
• pyproject.toml標準: PEP 518/621準拠の現代的な設定管理
• インテリジェントな依存関係解決: バージョン競合を自動解決
• ビルトインパッケージング: ホイールやsdistの作成機能
• PyPI統合: パッケージの公開とプライベートリポジトリ対応

アーキテクチャ

Poetryは、プロジェクトルートのpyproject.tomlファイルを設定の中心とし、poetry.lockファイルで具体的なバージョンを記録します。仮想環境はプロジェクトごとに自動作成され、システムPythonから完全に分離されます。

他ツールとの比較

• vs pip: より高レベルな依存関係管理とプロジェクト構造
• vs pipenv: より高速な依存関係解決とビルトインパッケージング
• vs conda: Python特化でより軽量、科学計算以外に最適

メリット・デメリット

メリット

• 開発体験の向上: 単一ツールで完結する統合ワークフロー
• 再現可能性: lockファイルによる環境の完全な再現
• チーム開発: pyproject.tomlとlockファイルでの環境共有
• モダンな標準: PEP準拠の将来性のある設計
• 高速な操作: 最適化された依存関係解決アルゴリズム
• 柔軟な設定: グループ化された依存関係管理
• プラグインシステム: 拡張可能なアーキテクチャ

デメリット

• 学習コスト: 従来のpip/virtualenvと異なるワークフロー
• メモリ使用量: 大規模プロジェクトでの依存関係解決時の負荷
• エコシステム: 一部のレガシーツールとの互換性問題
• Windows制限: 一部の機能でPOSIX環境が推奨
• ストレージ: プロジェクトごとの仮想環境によるディスク使用

参考ページ

• Poetry公式サイト
• Poetry公式ドキュメント
• Poetry GitHubリポジトリ
• PyPI Poetry

書き方の例

インストール（推奨方法）

# pipxを使用（推奨）
pipx install poetry

# または公式インストーラーを使用
curl -sSL https://install.python-poetry.org | python3 -

# macOSの場合、Homebrewも使用可能
brew install poetry

# インストール確認
poetry --version

基本的なプロジェクトの作成

# 新しいプロジェクトを作成
poetry new my-project
cd my-project

# 既存のプロジェクトでPoetryを初期化
poetry init

# プロジェクト構造の確認
tree my-project
# my-project/
# ├── pyproject.toml
# ├── README.md
# ├── my_project/
# │   └── __init__.py
# └── tests/
#     └── __init__.py

依存関係の管理

# パッケージの追加
poetry add requests
poetry add fastapi
poetry add "django>=4.0,<5.0"

# 開発依存関係の追加
poetry add pytest --group dev
poetry add black --group dev
poetry add mypy --group dev

# オプショナルグループの追加
poetry add sphinx --group docs
poetry add --group docs mkdocs

# 特定のPythonバージョンでの追加
poetry add "numpy; python_version >= '3.8'"

# GitHubリポジトリからの追加
poetry add git+https://github.com/user/repo.git
poetry add git+https://github.com/user/repo.git@branch-name

仮想環境の管理

# 仮想環境の情報表示
poetry env info

# 仮想環境のパス表示
poetry env info --path

# 使用可能な仮想環境一覧
poetry env list

# 特定のPythonバージョンを使用
poetry env use python3.11
poetry env use /usr/bin/python3.11

# 仮想環境の削除
poetry env remove python3.11

# 仮想環境での設定
poetry config virtualenvs.in-project true  # プロジェクト内に.venv作成
poetry config virtualenvs.create false     # 仮想環境の自動作成を無効

プロジェクトのインストールと実行

# 依存関係のインストール
poetry install

# プロダクション用（開発依存関係を除く）
poetry install --only main

# 特定のグループのみインストール
poetry install --only dev
poetry install --with docs

# 特定のグループを除外
poetry install --without dev,test

# 仮想環境内でコマンド実行
poetry run python app.py
poetry run pytest
poetry run black .

# 仮想環境のシェルを開始
poetry shell

依存関係の更新と管理

# すべての依存関係を更新
poetry update

# 特定のパッケージのみ更新
poetry update requests

# ロックファイルの再生成（インストールなし）
poetry lock

# 古いロックファイルと同期
poetry install --sync

# 依存関係の確認
poetry show
poetry show --tree
poetry show requests

# 脆弱性のあるパッケージの確認
poetry audit

パッケージの公開

# プロジェクトのビルド
poetry build

# PyPIにログイン（APIトークン推奨）
poetry config pypi-token.pypi your-api-token

# テストPyPIに公開
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish -r testpypi

# PyPIに公開
poetry publish

# ドライランでのテスト
poetry publish --dry-run

設定管理

# Poetryの設定確認
poetry config --list

# キャッシュディレクトリの設定
poetry config cache-dir /path/to/cache

# プライベートリポジトリの設定
poetry config repositories.private-repo https://repo.company.com/simple/
poetry config http-basic.private-repo username password

# 証明書の設定
poetry config certificates.private-repo.cert /path/to/cert.pem

# プロキシの設定
poetry config http-basic.proxy.url http://proxy.company.com:8080

CI/CDでの活用

# GitHub Actions例
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.9, 3.10, 3.11, 3.12]
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    
    - name: Install Poetry
      run: |
        curl -sSL https://install.python-poetry.org | python3 -
        echo "$HOME/.local/bin" >> $GITHUB_PATH
    
    - name: Configure Poetry
      run: |
        poetry config virtualenvs.create true
        poetry config virtualenvs.in-project true
    
    - name: Cache dependencies
      uses: actions/cache@v3
      with:
        path: .venv
        key: poetry-${{ hashFiles('poetry.lock') }}
    
    - name: Install dependencies
      run: poetry install
    
    - name: Run tests
      run: |
        poetry run pytest
        poetry run black --check .
        poetry run mypy .

プロジェクトテンプレートの活用

# カスタムテンプレートの使用
poetry new my-project --src  # src/レイアウト

# パッケージモードの無効化（アプリケーション開発）
# pyproject.tomlに追加
[tool.poetry]
package-mode = false

Poetryプラグインの活用

# プラグインのインストール
poetry self add poetry-plugin-export
poetry self add poetry-plugin-bundle

# requirements.txtの生成
poetry export -f requirements.txt --output requirements.txt
poetry export --only dev -f requirements.txt --output dev-requirements.txt

# プラグインの管理
poetry self show plugins
poetry self remove poetry-plugin-export

トラブルシューティング

# キャッシュのクリア
poetry cache clear pypi --all

# Poetryのアップデート
poetry self update

# 設定のリセット
poetry config --unset virtualenvs.in-project

# デバッグ情報の表示
poetry debug info
poetry debug resolve

# 環境の完全リセット
poetry env remove --all
poetry cache clear --all pypi