Basic usage

基本的な使い方を紹介するために、datetimeライブラリであるpendulumをインストールします。 Poetryをまだインストールしていない場合は、Introductionの章を参照してください。

Project setup

まず、新しいプロジェクトを作成しましょう。

poetry new poetry-demo

これにより、次の内容のpoetry-demoディレクトリが作成されます。

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

ここで最も重要なのはpyproject.tomlファイルです。これはプロジェクトとその依存関係を調整します。今のところ、次のようになります。

[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["Sébastien Eustace <sebastien@eustace.io>"]
readme = "README.md"
packages = [{include = "poetry_demo"}]

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


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Poetryでは、プロジェクトのルートにあるtool.poetry.nameと同じ名前のパッケージがパッケージに含まれていることを前提としています。そうでない場合は、tool.poetry.packagesに入力して、パッケージとその場所を指定します。

同様に、従来のMANIFEST.inファイルはtool.poetry.readme、tool.poetry.include、およびtool.poetry.excludeセクションに置き換えられます。tool.poetry.excludeはさらに暗黙的に.gitignoreによって入力されます。 プロジェクトフォーマットの完全なドキュメントについては、ドキュメントのpyproject sectionを参照してください。

Setting a Python Version

Note

他のパッケージとは異なり、PoetryはPythonインタプリタを自動的にインストールしません。 パッケージ内のPythonファイルをスクリプトやアプリケーションのように実行したい場合は、実行するために独自のPythonインタプリタを_用意する_必要があります。

Poetryでは、サポートするPythonのバージョンを明示的に指定する必要があります。また、ユニバーサル・ロックによって、サポートされているすべてのPythonバージョンでプロジェクトをインストールできること(およびすべての依存関係がサポートを要求すること)が保証されます。 ここでも、他の依存関係とは異なり、Pythonのバージョンを設定するということは、サポートするPythonのバージョンを指定するだけであることを覚えておくことが重要です。

例えば、 pyproject.toml このように記述します:

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

3.7.0以降のバージョンのPython 3ならどれでも許可しています。

poetry installを実行する際には、システム上でこの制約を満たすPythonインタプリタのバージョンにアクセスできる必要があります。 PoetryはPythonインタープリターをインストールしません。 pyenvのようなツールを使用する場合は、実験的な構成値virtualenvs.prefer-active-pythonを使用できます。

Initialising a pre-existing project

新しいプロジェクトを作成する代わりに、Poetryを使用して、事前に設定されたディレクトリを"初期化"することができます。ディレクトリpre-existing-projectにpyproject.tomlファイルを対話的に作成するには:

cd pre-existing-project
poetry init

Operating modes

Poetryは2つの異なるモードで操作することができます。デフォルトのモードはパッケージモードです。これは、プロジェクトをsdistまたはwheelにパッケージ化し、パッケージインデックスにパブリッシュする場合に適したモードです。 このモードでは、パッケージ化に必要な"name"や"version"などのメタデータは必須です。 さらに、poetry installを実行すると、プロジェクト自体が編集可能モードでインストールされます。

Poetryを依存関係の管理のみに使用し、パッケージ化には使用しない場合は、非パッケージモードを使用できます。

[tool.poetry]
package-mode = false

このモードでは、nameやversionなどのメタデータはオプションです。 したがって、ディストリビューションを構築したり、プロジェクトをパッケージインデックスに公開したりすることはできません。 さらに、poetry installを実行すると、Poetryはプロジェクト自体をインストールするのではなく、その依存関係のみをインストールしようとします(poetry install--no-rootと同じです)。

Note

pyproject sectionでは、パッケージモードで必要なフィールドを確認できます。

Specifying dependencies

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

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

ご覧のように、パッケージ名とバージョン制約のマッピングを必要とします。

Poetryはこの情報を使用して、tool.poetry.sourceセクションまたはPyPIにデフォルトで登録されているパッケージ"リポジトリ"内の適切なファイルセットを検索します。

また、pyproject.tomlファイルを手動で変更する代わりに、addコマンドを使用することもできます。

$ poetry add pendulum

適切なバージョン制約を自動的に見つけて、パッケージとサブ依存関係をインストールします。

Poetryは、キャレット、チルダ、ワイルドカード、不等式、multiple constraints要件を含む、豊富なdependency specification構文をサポートしています。

Using your virtual environment

デフォルトでは、Poetryは{cache-dir}/virtualenvsに仮想環境を作成します。 cache-dirの値は、Poetryの設定を編集することで変更できます。 さらに、virtualenvs.in-project設定変数を使用して、プロジェクトディレクトリ内に仮想環境を作成できます。

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

Note

External virtual environment management

Poetryは、外部から活性化された既存の仮想環境を検出し、そちらを優先します。 これは、Poetryに組み込まれた単純化された環境管理の代替となることを目的とした強力なメカニズムです。

これを利用するには、環境を操作しようとするPoetryコマンドを実行する前に、任意のメソッドまたはツールを使用して仮想環境をアクティブにします。

Using poetry run

スクリプトを実行するには、単にpoetry run python your_script.pyを使用してください。 同様に、pytestやblackのようなコマンドラインツールがあれば、poetry run pytestを使って実行できます。

Note

自分の仮想環境を外部で管理する場合は、poetry runやpoetry shellを使用する必要はありません。おそらく、すでにその仮想環境を有効にして、正しいpythonインスタンスを利用できるようにしているからです。 たとえば、次のコマンドは同じPythonパスを出力します。

conda activate your_env_name
which python
poetry run which python
poetry shell
which python

Activating the virtual environment

仮想環境を有効にする最も簡単な方法は、poetry shellでネストされたシェルを作成することです。

仮想環境を無効にしてこの新しいシェルを終了するには、exitと入力します。 シェルを離れずに仮想環境を非アクティブにするには、deactivateを使用します。

Note

Why a nested shell?

子プロセスは親から環境を継承しますが、共有はしません。 そのため、子プロセスによって行われた変更は、子プロセスが終了した後は保持されません。 子プロセスであるPythonアプリケーション(Poetry)は、Poetryコマンドの実行が完了した後もアクティブな仮想環境がアクティブなままになるように、呼び出されたシェルの環境を変更することはできません。

したがって、Poetryは、後続のコマンドを仮想環境内から実行するために、仮想環境をアクティブにしたサブシェルを作成する必要があります。

仮想環境の起動時にpoetry shellがシェルプロンプトを変更しないようにしたい場合は、コマンドを実行する前に環境変数としてVIRTUAL_ENV_DISABLE_PROMPT=1を設定してください。

または、新しいシェルを作成しないようにするために、source{path_to_venv}/bin/activate(PowerShellでは{path_to_venv}\Scripts\activate.ps1)を実行して、仮想環境を手動でアクティブにすることもできます。 仮想環境へのパスを取得するには、poetry env info--pathを実行してください。 また、これをsource$(poetry env info--path)/bin/activate(&((poetry env info--path)+"\Scripts\activate.ps1")のように1行にまとめることもできます。

この仮想環境を無効にするには、単にdeactivateを使用してください。

	POSIX Shell	Windows (PowerShell)	Exit/Deactivate
Sub-shell	poetry shell	poetry shell	exit
Manual Activation	source {path_to_venv}/bin/activate	{path_to_venv}\Scripts\activate.ps1	deactivate
One-liner	source $(poetry env info --path)/bin/activate	& ((poetry env info --path) + "\Scripts\activate.ps1")	deactivate

Version constraints

この例では、バージョン制約^2.1を持つpendulumパッケージを要求しています。 これは、2.1.0以上3.0.0未満(>=2.1.0<3.0.0)の任意のバージョンを意味します。

バージョン、バージョン間の関係、依存関係を指定するさまざまな方法の詳細については、Dependency specificationを参照してください。

Note

How does Poetry download the right files?

pyproject.tomlで依存関係を指定すると、Poetryはまず要求したパッケージの名前を取得し、repositoriesキーを使用して登録した任意のリポジトリ内でそのパッケージを検索します。 追加のリポジトリーを登録していない場合、または指定したリポジトリー内にその名前のパッケージが見つからない場合は、PyPIに戻されます。

Poetryは適切なパッケージを見つけると、指定したバージョン制約に最も一致するパッケージを見つけようとします。

Installing dependencies

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

poetry install

このコマンドを実行すると、次のいずれかが発生する可能性があります。

Installing without poetry.lock

このコマンドを実行したことがなく、poetry.lockファイルも存在しない場合、Poetryは単にpyproject.tomlファイルにリストされているすべての依存関係を解決し、ファイルの最新バージョンをダウンロードします。

Poetryのインストールが完了すると、ダウンロードしたすべてのパッケージとその正確なバージョンがpoetry.lockファイルに書き込まれ、プロジェクトが特定のバージョンにロックされます。 プロジェクトで作業しているすべての人が同じバージョンの依存関係にロックされるように、poetry.lockファイルをプロジェクトリポジトリにコミットする必要があります(詳細は後述)。

Installing with poetry.lock

ここで2番目のシナリオに移ります。poetry installを実行したときにすでにpoetry.lockファイルとpyproject.tomlファイルが存在する場合は、以前にinstallコマンドを実行したか、プロジェクトの他の誰かがinstallコマンドを実行してpoetry.lockファイルをプロジェクトにコミットしたことを意味します(これは良いことです)。

いずれにしても、poetry.lockファイルが存在するときにinstallを実行すると、pyproject.tomlにリストされたすべての依存関係が解決されてインストールされますが、Poetryはpoetry.lockにリストされた正確なバージョンを使用して、プロジェクトで作業するすべての人に対してパッケージのバージョンが一貫していることを確認します。

その結果、pyproject.tomlファイルによって要求されたすべての依存関係がありますが、それらはすべて最新の利用可能なバージョンであるとは限りません(poetry.lockファイルにリストされている依存関係の中には、ファイルが作成されてから新しいバージョンがリリースされているものもあります)。

これは設計上のことであり、依存関係の予期しない変更によってプロジェクトが中断されないようにします。

Committing your poetry.lock file to version control

As an application developer

アプリケーション開発者は、より再現可能なビルドを得るためにpoetry.lockをコミットします。

このファイルをVCにコミットすると、プロジェクトを設定するすべてのユーザーが、使用している依存関係とまったく同じバージョンを使用することになるため、このファイルをVCにコミットすることが重要です。

CIサーバ、プロダクションマシン、チーム内の他の開発者、すべてのもの、すべての人が同じ依存関係で実行されます。 これにより、展開の一部にのみ影響するバグの可能性が軽減されます。

単独で開発したとしても、プロジェクトを再インストールする6か月後には、インストールされた依存関係が、それ以降に多くの新しいバージョンをリリースしたとしても、まだ機能していると確信できます(updateコマンドの使用については、以下の注を参照してください)。

Warning

推奨される[build-system]セクションをプロジェクトのpyproject.tomlに追加した場合、pip install-e.のようなコマンドを使用して、プロジェクトとその依存関係を仮想環境に正常にインストールできます。ただし、poetry-coreビルドシステムはライブラリ開発者を対象としているため(次のセクションを参照)、pipはロックファイルを使用して依存関係のバージョンを決定しません。

As a library developer

ユーザーはアプリケーション開発者であり、ライブラリは制御できないPython環境で実行されます。

アプリケーションはライブラリのロックファイルを無視します。pyproject.toml内の制約を満たす依存関係のバージョンを使用できます。アプリケーションはおそらく、互換性のある最新の依存関係のバージョンを使用します。ライブラリのpoetry.lockが、ユーザにとって問題となる新しい依存関係のバージョンに遅れをとっている場合、すぐにわかります。

このようなシナリオを避ける簡単な方法は、poetry.lockファイルを省略することです。しかし、そうすることで、再現性と性能がある程度犠牲になります。

ロックファイルがなければ、明らかなコード変更に加えて、気づかれないライブラリの更新が原因である可能性があるため、テストが失敗した理由を見つけるのが困難になる可能性があります。さらに、poetry.lockが省略されている場合、Poetryは依存関係をインストールする前にロックする必要があります。

依存関係の数によっては、ロックにかなりの時間がかかる場合があります。

再現性とパフォーマンスの利点を諦めたくない場合は、poetry.lockを定期的に更新して最新の状態に保ち、ユーザーが突然破損するリスクを減らすことを検討してください。

Installing dependencies only

既定では、現在のプロジェクトはeditableモードでインストールされます。

依存関係のみをインストールしたい場合は、--no-rootフラグを指定してinstallコマンドを実行します。

poetry install --no-root

Updating dependencies to their latest versions

前述したように、poetry.lockファイルは、依存関係の最新バージョンを自動的に取得できないようにします。 最新バージョンに更新するには、updateコマンドを使用してください。 これにより、(pyproject.tomlファイルに従って)一致する最新のバージョンが取得され、ロックファイルが新しいバージョンで更新されます。 (これはpoetry.lockファイルを削除してinstallをもう一度実行するのと同じことです。

Note

poetry.lockとpyproject.tomlが同期していない場合、Poetryはインストールコマンドの実行時に警告を表示します。