今回は Python のパッケージ「 Poetry 」を紹介します。

最初に Poetry とは何ぞや（ WHAT ）の説明をした後に Poetry の使い方（ HOW ）について説明します。最後に Pipenv からの移行方法についてかんたんに説明します。

Poetry とは

Poetry とは 2018 年 2 月頃から開発がスタートした Python パッケージの管理ツールです。

• ドキュメント: Poetry - Python dependency management and packaging made easy.
• リポジトリ: GitHub - python-poetry/poetry

pip と venv を組み合わせて、 npm ・ bundle ・ composer 等他の言語で定番のパッケージ管理ツールと似た使用感で使える Python パッケージ管理機能を提供しています。私自身はまだアプリケーションでしか使ったことがありませんが、アプリケーションでも配布用のパッケージでも使えるとのことです。

Pipenv をご存知の方には「 Pipenv の代替物」という説明の方がわかりやすいかもしれません。

Poetry の使い方

ここでは Poetry のバージョン 0.12.10 における使い方を説明します。 Poetry のバージョンが進むと使い方が変わると思いますので、参考にされる際はそのあたりににご注意ください。

尚、私は Poetry をアプリケーションのプロジェクトにしか使っていない（配布パッケージのプロジェクトには使っていない）ので、配布パッケージを管理するための情報はカバーできていません。

インストール

追記: 現在は https://install.python-poetry.org にあるスクリプトを使ってインストールする方法が推奨されています。 公式ドキュメント で最新の情報を確認してください。

公式に推奨されているインストール方法は、専用のスクリプト get-poetry.py を使ったものです。

$ curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python

異なるバージョンの Python が同居している環境では、適切な python コマンドを選択する必要があります。

$ curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python3.7

このコマンドを実際に実行すると私の場合は次のようなメッセージが出ました。

$ curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python
Retrieving Poetry metadata

# Welcome to Poetry!

This will download and install the latest version of Poetry,
a dependency and package manager for Python.

It will add the `poetry` command to Poetry's bin directory, located at:

$HOME/.poetry/bin

This path will then be added to your `PATH` environment variable by
modifying the profile files located at:

$HOME/.profile
$HOME/.bash_profile

You can uninstall at any time with `poetry self:uninstall`,
or by executing this script with the --uninstall option,
and these changes will be reverted.

Installing version: 0.12.10
  - Downloading poetry-0.12.10-darwin.tar.gz (7.12MB)

Poetry (0.12.10) is installed now. Great!

To get started you need Poetry's bin directory ($HOME/.poetry/bin) in your `PATH`
environment variable. Next time you log in this will be done
automatically.

To configure your current shell run `source $HOME/.poetry/env`

スクリプトの実行が成功すると、 Unix 系の OS なら $HOME/.poetry/bin に実行可能な poetry ファイルが置かれます。このディレクトリを環境変数 PATH に追加しておくと、その後はフルパスを指定しなくても poetry コマンドが実行できるようになります（ちなみに、私の環境では get-poetry.py が PATH に追加するコードを ~/.bash_profile に自動的に追加しました）。

~/.bashrc:

# for Python/Poetry
export PATH="$HOME/.poetry/bin:$PATH"

PATH の追加が終わったら poetry コマンドが使用できるようになっているはずです。例えば次のようにして正しく実行できればインストールは完了です。

$ poetry --version
Poetry 0.12.10

アンインストール

Poetry そのものをアンインストールしたくなったときは、インストールのときと同じ get-poetry.py スクリプトが使えます。

公式のドキュメントには、次のように get-poetry.py をいったんダウンロードしてから実行する方法が紹介されています。

$ python get-poetry.py --uninstall

get-poetry.py をファイルとして保存せずに直接実行する次のような方法も利用可能です。

$ curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | POETRY_UNINSTALL=1 python

自動補完の設定

サブコマンドの自動補完のための設定も公式に用意されています。

例えば、 Bash の場合は次のコマンドの出力を ~/.bash_profile 等に追加しておけば次回 ~/.bash_profile を読み込んだ後は自動補完が有効になります。

$ poetry completions bash

1. プロジェクトを作成する

Poetry を実際に利用し始めるときに最初に行うべきことはプロジェクトの作成です。プロジェクトを作成するときに使えるコマンドには次の 2 つがあります。

• poetry init
• poetry new

poetry init はインタラクティブな入力 UI を提供した後入力内容に沿って pyproject.toml ファイルを生成します。入力項目はおおよそ次のとおりです。

• Package name
• Version
• Description
• Author
• License
• Compatible Python versions

生成されるファイル pyproject.toml は、ちょうど npm における package.json と同等の役割を果たすファイルです。

他方の poetry new は pyproject.toml を含む、パッケージの雛形（ファイル一式）を生成します。

パッケージをゼロから作成する場合には poetry new が使えますが、おそらくほとんどのプロジェクトでは poetry init から始めることになるかと思います。

2. パッケージを追加する

poetry init 等でプロジェクトを作成したら、パッケージを追加します。パッケージの追加には poetry add を使用します。

$ poetry add flask

引数にはパッケージ名を指定します。パッケージ名は複数指定することもできます。

$ poetry add flask peewee gunicorn

開発用でパッケージを追加したいときは --dev オプションを使用します。

$ poetry add --dev pytest

ちなみに、パッケージの extras を追加したい場合は --extras オプションを使用します。

# pip なら
pip install django-anymail[mailgun]

# poetry なら
poetry add django-anymail --extras mailgun

3. パッケージをインストールする

poetry add で追加されたパッケージをインストールするには poetry install を使用します。

$ poetry install

パッケージはグローバルにではなく Poetry が管理する virtualenv の中にインストールされます。指定されたパッケージの依存パッケージも含めて、すべてのパッケージ情報は poetry.lock に保存されます。同じパッケージ環境を複数の環境で共有したい場合は poetry.lock を Git に登録するとよいかと思います。

ちなみに、私が実行したかぎりでは、 Poetry が現在のプロジェクトに対して用意している virtualenv の場所は poetry shell や poetry debug:info コマンドで確認することができました。

4. パッケージを表示する

利用パッケージとして登録されているパッケージを確認するときは poetry show を使用します。

$ poetry show

poetry show コマンドはさまざまなオプションを受け付けます。例えば、更新可能なパッケージを確認したい場合は --outdated オプションが使えます。

$ poetry show --outdated

5. パッケージを利用する

Poetry がインストールしたパッケージは Poetry がプロジェクト単位で用意した virtualenv 内にインストールされています。そのため、パッケージを利用したいときには専用のコマンドを使用します。利用できるコマンドは次の 2 つです。

• poetry run
• poetry shell

poetry run は、一コマンド単位で virtualenv を有効化して実行したいときに使用します。コマンドが終了したら対象の virtualenv を自動的に deactivate してくれます。

$ poetry run コマンド
$ # 例
$ poetry run python manage.py runserver

poetry shell は、対象の virtualenv を有効化します。 poetry run は対象コマンドを実行後に即 virtualenv から脱出しますが、 poetry shell は明示的に exit しないかぎり virtualenv が有効になったままとなります。

$ poetry shell
$ # virtualenv 内で実行したいコマンドを実行する
$ # ...
$ exit

6. パッケージ更新

すでに登録されているパッケージを更新するときは poetry update コマンドを使用します。

$ poetry update flask

原則、指定されたパッケージのみが更新されるようです。 Pipenv とは異なり直感的な動作をしてくれます。

7. パッケージ削除

登録されているパッケージを削除するときは poetry remove を使用します。

$ poetry remove flask

アプリケーションの依存パッケージの管理についてはおおよそ以上のコマンドを覚えておけば十分ではないかと思います。

私自身まだ実用する機会がありませんが、アプリケーションではなく配布パッケージ管理のためのコマンドとして次のもの等が用意されています。配布パッケージの管理に Poetry を利用したい方はこれらもチェックされてみるとよいでしょう。

• poetry build
• poetry publish

その他代表的なコマンドとして以下のコマンド等も用意されています。

• poetry list サブコマンドの一覧を表示
• poetry cache:clear poetry のキャッシュ（？）を削除
• poetry self:update poetry 自身を更新
• poetry help ヘルプを表示

このあたりは公式のドキュメントは poetry list で確認することもできるので、丸覚えしなくても必要に応じて確認すればよいのではないかと個人的には思います。

Pipenv からの乗り換え

おそらく Poetry を使い始める理由として多いのは Pipenv からの乗り換えでしょう。ここでは私の経験を踏まえて Pipenv からの乗り換えに際して必要な作業をかんたんにご紹介します。

1. Poetry をインストール

上の手順のとおりに Poetry 本体をインストールします。

2. Poetry プロジェクトを作成

Pipenv から Poetry に切り替えたいプロジェクトのディレクトリに移動し、 poetry init を実行します。

$ poetry init

各入力項目に適宜回答したら pyproject.toml ファイルが作成されます。

3. Pipfile から pyproject.toml への移行

Pipfile の中身を確認しながら、パッケージと開発用パッケージをすべて poetry add で追加します。

$ poetry add 利用パッケージの一覧
$ poetry add --dev 開発用パッケージの一覧

通常の利用パッケージと開発用のパッケージは別々に登録します。

4. スクリプトのコマンドを書き換え

Makefile や fabfile.py の中に pipenv run 等のコマンドがあればそれらを poetry run に変更します。主要なコマンドはおおよそ次のとおりに書き換えるとよいでしょう。

• pipenv run → poetry run
• pipenv install → poetry install
• pipenv shell → poetry shell
• pipenv update → poetry update

以上です。複雑なことをやっていなければ Pipenv から Poetry への移行は高々数ステップで問題なく行えるのではないかと思います。

おわりに

というわけで、 Python のパッケージ管理ツール Poetry の使い方についてでした。 Pipenv と同様まだできてから日の浅いツールなのでこの先どのようになるかはわかりません。ただ、導入の学習コストは少なく Pipenv のような非直感的なふるまいも特に見られない感じなので、興味のある方は気軽に試してみてよいのではないかと思います。

Poetry についてより詳しく知りたい方は公式のドキュメントをご覧になってみてください。

• Poetry - Python dependency management and packaging made easy

Pipenv の問題点とそれにまつわる議論については次のページ等が参考になります。

• Pipenv review, after using it in production – David Jetelina – Medium
• Pipenv: promises a lot, delivers very little | Chris Warrick
• Pipenv: promises a lot, delivers very little | Hacker News
• Pipenv: promises a lot, delivers very little : Python | reddit

追記 2018/12/25:

配布パッケージのプロジェクトで Poetry を使う方法については次の記事でとても丁寧に説明されています。興味のある方はご覧になってみてください。

• Poetryを使ったPythonパッケージ開発からPyPI公開まで - PYTHONIC BOOM BOOM HEAD