Poetry は Python の依存関係管理・パッケージングツールで、プロジェクトの初期化から依存関係の解決、インストール、ビルド、公開までを一貫して管理できます。以下に、主要な Poetry コマンドの手順とその仕組みを解説します。
目次
1. プロジェクトの初期化: poetry init
- 手順:
poetry initを実行すると、対話型のウィザードが起動し、プロジェクト名、バージョン、説明、ライセンス、依存パッケージなどを尋ねられます。 - 仕組み:
ユーザーの入力に基づいて、プロジェクトのメタデータや依存関係情報が記述されたpyproject.tomlファイルが生成されます。 - 目的:
プロジェクトの「マニフェスト」として、後の依存関係解決やパッケージビルドの基盤となる設定ファイルを作成します。
2. 依存関係の追加: poetry add <package>
- 手順:
例えばpoetry add fastapiと実行すると、fastapiパッケージがプロジェクトに追加されます。 - 仕組み:
Poetry は内部の依存解決エンジンを使用して、指定したパッケージとその依存パッケージのバージョン互換性をチェックし、最適なバージョンを選定します。- その結果、
pyproject.tomlに依存関係が追加されるとともに、正確なバージョン情報を記載したpoetry.lockファイルが生成され、今後のインストール時に再現性が確保されます。
- その結果、
3. 依存関係のインストール: poetry install
- 手順:
poetry installを実行すると、poetry.lockに記載された正確なバージョンの依存関係がインストールされます。 - 仕組み:
Poetry はプロジェクト専用の仮想環境（venv）を自動生成し、その環境内に依存パッケージをインストールします。これにより、システム全体に影響を与えずにプロジェクトごとの依存関係が管理されます。
4. 依存関係の更新: poetry update
- 手順:
poetry updateを実行すると、pyproject.tomlに定義された制約内で利用可能な最新のパッケージに更新され、poetry.lockが再生成されます。 - 仕組み:
依存関係の解決エンジンが再度動作し、互換性のある最新のバージョンを選び出し、ロックファイルをアップデートします。
5. パッケージのビルドと公開: poetry build / poetry publish
- ビルド:
poetry buildを実行すると、ソースディストリビューション（sdist）やホイール（wheel）などの配布可能なパッケージファイルが生成されます。 - 公開:
poetry publishを実行すると、ビルドされたパッケージを PyPI などのリポジトリにアップロードできます。
Poetry コマンドの内部の仕組み
- pyproject.toml と poetry.lock
pyproject.toml: プロジェクトの設定や依存関係の宣言を行うファイル。poetry.lock: 依存関係の正確なバージョン情報を固定し、再現性のあるインストールを実現するためのファイル。
- 依存解決エンジン
Poetry は内部で高度な依存解決アルゴリズムを利用して、複雑な依存関係の衝突を解決し、最適なパッケージセットを選定します。 - 仮想環境の管理
プロジェクトごとに隔離された仮想環境を自動で作成・管理し、システム全体の依存関係と干渉しないようにしています。 - CLI の実装
Poetry の各コマンドは Python で実装され、ユーザーからの入力を解析し、内部の設定ファイルの更新や、パッケージのインストール・ビルドなどの処理を行います。
まとめ
Poetry コマンドは、対話型のプロジェクト初期化、依存関係の追加、インストール、更新、ビルド、公開といった一連の作業をシンプルな CLI コマンドで実現します。
内部では、pyproject.toml による宣言、依存関係解決エンジンによるバージョン管理、仮想環境の自動管理、そして生成された poetry.lock による再現性の確保といった仕組みにより、Python プロジェクトの開発と運用がスムーズに行えるようになっています。