Poetry: Python の依存関係管理とパッケージングを支援するツール

macOS や Linux で curl が使える場合は以下を実行します。 python の部分は python3.6 など、メインで使っているインタープリタに適宜変更してください。

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

もちろん、url から get-poetry.py をダウンロードしてから実行しても構いません。

python get-poetry.py

Windows でもこれでインストールして使えるはずですが、私の環境では使えませんでした。 エンコーディングの問題な気がしますが調べられていません。

pip でもインストールできますが、Poetry 自体の依存パッケージがインストールされるので推奨されていません。

なお、Poetry が不要になったときは pip で削除しましょう。

python -m pip uninstall poetry

次のコマンドで Poetry が最新バージョンに更新されます。

poetry self:update

bash, zsh, fish を使っている場合は Tab キーで補完候補を表示できるようになります。 例えば、fish では次を実行します。

poetry completions fish > ~/.config/fish/completions/poetry.fish

プロジェクトの雛形を作成するコマンドです。

poetry new poetry-demo

作成されるディレクトリの構成は次のようになります。

poetry-demo
├── pyproject.toml
├── README.rst
├── poetry_demo
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_poetry_demo

pyproject.toml の項目は次のように指定します。 詳しくは ドキュメント を参照してください。

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

[tool.poetry.dev-dependencies]
pytest = "^3.0"

dependencies に依存関係、dev-dependencies には開発のための依存関係を記述します。 また、"^3.6" のように、バージョンは制約条件で指定することもできます。 制約条件の指定方法は ドキュメント を参照してください。

なお、pyproject.lock には、実際に環境で使われるパッケージの情報が記述されます。 パッケージを追加、更新、削除すると、pyproject.lock も自動的に更新されます。

プロジェクトに pyproject.toml がない場合に新規作成するためのコマンドです。 pyproject.toml の項目を対話的に入力していくことができます。 なお、 --dependency オプションなどで項目を直接指定することもできます。

poetry init

Poetry は install や add コマンドなどが実行されると、まずはディレクトリに仮想環境があるかをチェックします。 仮想環境がなければ、自動で ~/.cache/pypoetry/virtualenvs などに仮想環境を作成します。 そのため、プロジェクトごとに必ず環境は分離されます。 使うインタープリタのバージョンを指定したい場合は、venv などで仮想環境を作成しておきましょう。

python3.6 -m venv .venv

プロジェクトの pyproject.toml を読み込み、依存関係を解決してインストールするコマンドです。

poetry install

オプション:

• --no-dev: 開発用のパッケージはインストールしない
• --extras (-E): 追加でインストールしたいパッケージを指定

環境にインストールされているパッケージを最新バージョンに更新するコマンドです。

poetry update

更新するパッケージを指定することもできます。

poetry update requests toml

オプション:

• --dry-run: 実行はせず、どんな処理がされるかだけ表示

必要なパッケージを pyproject.toml に追加し、インストールするコマンドです。 バージョンの制約の指定がなければ、依存関係を解決して適切なバージョンが選択されます。

poetry add requests pendulum

オプション:

• --dev (-D): 開発用の依存パッケージとして追加
• --git: Git リポジトリの URL を指定
• --path: 依存パッケージへのパスを追加
• --extras (-E): 依存パッケージを有効にするための追加パッケージ
• --optional: オプションの依存パッケージとして追加
• --dry-run: 実行はせず、どんな処理がされるかだけ表示

環境にインストールされているパッケージを削除するコマンドです。

poetry remove pendulum

オプション:

• --dev (-D): 開発用の依存パッケージから削除
• --dry-run: 実行はせず、どんな処理がされるかだけ表示

利用可能なパッケージの一覧を表示します。

poetry show

特定のパッケージの詳細を表示することもできます。

poetry show pendulum

オプション:

• --tree: ツリー構造で依存関係を表示
• --latest (-l): 最新バージョンを表示
• --outdated (-o): バージョンの古いパッケージだけ表示

ソースコード配布物 (sdist、wheel のアーカイブ) を作成するコマンドです。 現時点では、pure python なパッケージだけ使えます。

poetry build

オプション:

• --format (-f): 形式を sdist か wheel だけに限定

build コマンドでビルドしたパッケージをリモートリポジトリに発行します。 初めての場合は、アップロードする前にパッケージを自動的に登録します。

poetry publish

オプション:

• --build: パッケージをビルドする
• --repository (-r): パッケージを登録するリポジトリ (デフォルト: pypi)。 config コマンドで設定したリポジトリ名と一致する必要があります。
• --username (-u): リポジトリにアクセスするユーザー名
• --password (-p): リポジトリにアクセスするパスワード

リポジトリなどの設定を編集するコマンドです。 例えば、新しく foo というリポジトリの url と認証情報を設定するには、次のように実行します。

poetry config repositories.foo https://foo.bar/simple/

poetry config http-basic.foo username password

なお、PyPI の認証情報も同じように設定しておけます。

オプション:

• --unset: 指定の設定変数の値を削除
• --list: 現在の設定変数のリストを表示

これで設定した foo リポジトリに発行できるようになります。

poetry publish -r foo

また、このリポジトリからも依存パッケージをインストールできるようにするには、pyproject.toml に次のように設定しておきます。

[[tool.poetry.source]]
name = "foo"
url = "https://foo.bar/simple/"

プロジェクトの仮想環境内でコマンドを実行します。 仮想環境を有効化する作業は不要です。

poetry run python -V

また、pyproject.toml で次のようにスクリプトを定義しておくと、

[tool.poetry.scripts]
my-script = "my_module:main"

それを直接実行することもできます。

poetry run my-script

pyproject.toml の構造を検証し、エラーがあるか詳細なレポートを返します。

poetry check

リポジトリのインデックスからパッケージを検索します。

poetry search requests pendulum

pyproject.toml で指定された依存パッケージをインストールせずに pyproject.lock を更新します。

poetry lock