基本的な使い方🔗

基本的な使い方の入門として、 pendulum という日付ライブラリをインストールします。 Poetryをまだインストールしていない場合は、入門の章を参照してください。

プロジェクトのセットアップ🔗

最初に、新しいプロジェクトを作成し、 poetry-demo と名付けましょう:

poetry new poetry-demo

このコマンドは、次の内容を持つ poetry-demo ディレクトリを作成します:

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

pyproject.toml ファイルがここでは最も重要なものです。このファイルが、プロジェクトの依存関係を統括します。今のところの中身は、このようになっています:

[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["Sébastien Eustace <sebastien@eustace.io>"]

[tool.poetry.dependencies]
python = "*"

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

既存のプロジェクトの初期化🔗

Poetryは新規のプロジェクトを作るのではなく、既に使われているディクトリの「初期化」にも使えます。対話的に pre-existing-project ディレクトリに pyproject.toml ファイルを作成するには次のようにします:

cd pre-existing-project
poetry init

依存関係の指定🔗

プロジェクトに依存関係を追加したい場合は、 tool.poetry.dependencies セクションに指定できます。

[tool.poetry.dependencies]
pendulum = "^1.4"

見て分かるように、このセクションには パッケージ名 と バージョン制約 の対応付けを書きます。

Poetryはこの情報を使い、 tool.poetry.repositories セクションに登録されたパッケージ "レポジトリ" もしくはデフォルトの PyPI から、正しいファイル群を検索します。

pyproject.toml ファイルを手で編集する変わりに、 add コマンドも使えます。

$ poetry add pendulum

このコマンドは自動的に適切なバージョン制約を見付け、パッケージとその依存関係を インストールします 。

仮想環境の使用🔗

デフォルトでは、poetryは {cache-dir}/virtualenvs (Windowsでは {cache-dir}\virtualenvs) に仮想環境を作成します。poetry config を編集して cache-dir の値を変更できます。加えて、virtualenvs.in-project の設定変数を使い、プロジェクトのディレクトリ内に仮想環境を作成できます。

この仮想環境内でコマンドを実行する方法はいくつかあります。

`poetry run` の使用🔗

スクリプトを実行するには poetry run python your_script.py コマンドを使うだけです。同じように、 pytest や black のようなコマンドラインツールを持っている場合は、 poetry run pytest コマンドを使って実行できます。

仮想環境の起動🔗

仮想環境を起動する最も簡単な方法は、poetry shell コマンドで新しくシェルを作成することです。仮想環境を終了して新しいシェルを終了するには、exit コマンドを入力してください。シェルを無くさずに仮想環境を終了するには、deactivate コマンドを使ってください。

注意

なぜ新しいシェルなのか？ 子プロセスは親プロセスからその環境を引き継ぎますが、共有はしません。それなので、子プロセスで行われた変更はどれも子プロセスが終了した後は存続しません。子プロセスとして動いているPythonのアプリケーション（Poetry）は、 Poetryコマンドの実行が完了した後に起動中のままの仮想環境から呼び出されたシェルの環境を変更できません。

従って、Poetryは後々のコマンドを仮想環境内で実行するために、起動中の仮想環境でサブシェルを作成する必要があります。

そうではなく、新しいシェルの作成を避けるには、source {path_to_venv}/bin/activate (Windowsでは source {path_to_venv}\Scripts\activate.bat) コマンドを実行して、手動で仮想環境を起動する方法があります。仮想環境のパスを取得するには、 poetry env info --path コマンドを実行します。これらのコマンドを組み合わせて便利なワンライナーコマンド source $(poetry env info --path)/bin/activate To deactivate this virtual environment simply use deactivate にすることもできます

	POSIX Shell	Windows	Exit/Deactivate
New Shell	`poetry shell`	`poetry shell`	`exit`
Manual Activation	`source {path_to_venv}/bin/activate`	`source {path_to_venv}\Scripts\activate.bat`	`deactivate`
One-liner	source`poetry env info --path`/bin/activate		`deactivate`

バージョン制約🔗

今の例では、 ^1.4 というバージョン制約の付いた pendulum パッケージを要求しています。この制約は、1.4.0以上かつ2.0.0未満のバージョンという意味です (>=1.4.0 <2.0.0)。

バージョンやバージョンどうしの関係、依存関係を指定できる様々な方法について、より深いことについては依存関係仕様を読んでください。

注意

Poetryはどうやって正しいファイルをダウンロードするのか?

pyproject.toml に依存関係を指定したときは、 repositories キーを使って登録した任意のレポジトリ内の必要とし探し求めたパッケージ名を、Poetryは最初に取得します。追加のレポジトリが無いか、指定したレポジトリにその名前のパッケージが見付けられなった場合は、 PyPIにフォールバックします。

Poetryが正しいパッケージを複数見付けたときは、指定されたバージョン制約に最も適合するものを見付けようとします。

依存関係のインストール🔗

プロジェクトに定義された依存関係をインストールするには、 install コマンドを実行するだけです。

poetry install

このコマンドを実行すると、2つのうちどちらかが起こります:

`poetry.lock` 無しのインストール🔗

以前にこのコマンドを実行したことが無く、 poetry.lock ファイルも存在しない場合は、Poetryは pyproject.toml に並べられた全ての依存関係を解決し、それらのファイルの最新バージョンをダウンロードするだけです。

Poetryがインストールを完了すると、ダウンロードしたパッケージとその正確なバージョンを poetry.lock へ書き込み、その特定のバージョンでプロジェクトを固定します。プロジェクトレポジトリに poetry.lock ファイルをコミットし、このプロジェクトに携わる全ての人にとって、同じバージョンの依存関係を強制されるべきです (下でさらに解説します)。

`poetry.lock` 有りのインストール🔗

こちらの場合は先程とは別の第2のシナリオになります。 poetry install を実行するときに、 pyproject.toml に加えて既に poetry.lock ファイルがある場合は、以前に install コマンドを実行していたか、誰か他の人がそのプロジェクトで install コマンドを実行し poetry.lock ファイルをプロジェクトにコミット (これは良い行いです) していたことになります。

どちらにせよ、 poetry.lock ファイルがあるときに install コマンドを実行すると pyproject.toml に並べた全ての依存関係を解決しインストールしますが、Poetryは poetry.lock に並べられた正確なバージョンを使い、プロジェクトに携わる全ての人にとってパッケージバージョンが一貫性を持つことを保証します。その結果として、 pyproject.toml ファイルで要求された全ての依存関係が手に入りますが、必ずしも全ての依存関係が利用可能な最新バージョンではないかもしれません (poetry.lock ファイルに並べられている依存関係のうちいくつかは、そのファイルが作成された後により新しいバージョンがリリースされているかもしれません)。これは設計によるもので、プロジェクトが予期せぬ依存関係の変更で壊れないことを保証するものです。

`poetry.lock` ファイルをバージョン管理にコミット🔗

このファイルをVC (Version Control) にコミットするのが重要なのは、あなたが使っているバージョンと厳密に同じバージョンの依存関係を、プロジェクトをセットアップする人が使うようにするためです。あなたのCIサーバー、本番機、チームの他の開発者、全てのもの、全ての人が同じ依存関係の上で実行することで、配置物の一部だけに影響するバグが起きる恐れを軽減します。 6ヶ月間1人で開発をしたとしても、プロジェクトを再インストールするときには、インストールされた依存関係は今でも正常に動作すると確信を持てます。たとえ依存関係に多くの新バージョンがリリースされていたとしてもです。 (下にあるupdateコマンドの使い方についての注意書きを参照してください。)

注意

ライブラリについては、ロックファイルをコミットするのは必須ではありません。

依存関係のみのインストール🔗

現在のプロジェクトはデフォルトで編集可能 (editable) モードでインストールされます。

依存関係だけをインストールしたい場合は、 --no-root フラグを付けて install コマンドを実行してください:

poetry install --no-root

依存関係の最新バージョンへの更新🔗

上で言及したように、 poetry.lock ファイルは依存関係の最新バージョンを自動的に取得してしまうのを防止します。最新バージョンへ更新するには、 update コマンドを使ってください。このコマンドは適合する最新バージョンを (pyproject.toml ファイルに従って) 取ってきて、ロックファイルを新しいバージョンで更新します。 (この動作は、 poetry.lock ファイルを削除してから、改めて install を実行するのと同等です。)

注意

Poetryは、installコマンドを実行するときに poetry.lock と pyproject.toml が同期されていない場合、警告を表示します。