基本的な使い方🔗
基本的な使い方の入門として、 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
が同期されていない場合、
警告 を表示します。