基本的な使用方法
基本的な使用方法 #
基本的な使用方法の紹介では、日付時刻ライブラリである `pendulum` をインストールします。Poetryをまだインストールしていない場合は、はじめにの章を参照してください。
プロジェクトの設定 #
まず、新しいプロジェクトを作成しましょう。`poetry-demo` と名付けましょう。
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 セクションを参照してください。
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 を使用できます。
既存プロジェクトの初期化 #
新しいプロジェクトを作成する代わりに、Poetryを使用して既存のディレクトリを「初期化」できます。`pre-existing-project` ディレクトリに `pyproject.toml` ファイルを対話的に作成するには
cd pre-existing-project
poetry init
動作モード #
Poetryは2つの異なるモードで動作します。デフォルトモードは**パッケージモード**であり、プロジェクトをsdistまたはwheelにパッケージ化し、パッケージインデックスに公開する場合に適したモードです。このモードでは、パッケージ化に必要な `name` や `version` などのメタデータは必須です。さらに、`poetry install` を実行すると、プロジェクト自体が編集可能なモードでインストールされます。
パッケージ化ではなく、依存関係管理のみにPoetryを使用する場合は、**非パッケージモード**を使用できます。
[tool.poetry]
package-mode = false
このモードでは、`name` や `version` などのメタデータはオプションです。したがって、ディストリビューションをビルドしたり、プロジェクトをパッケージインデックスに公開したりすることはできません。さらに、`poetry install` を実行しても、Poetryはプロジェクト自体をインストールしようとせず、依存関係のみをインストールします（`poetry install --no-root` と同じです）。
依存関係の指定 #
プロジェクトに依存関係を追加する場合は、`tool.poetry.dependencies` セクションで指定できます。
[tool.poetry.dependencies]
pendulum = "^2.1"
ご覧のとおり、**パッケージ名**と**バージョン制約**のマッピングを受け取ります。
Poetryはこの情報を使用して、`tool.poetry.source` セクションで登録したパッケージ「リポジトリ」またはデフォルトでPyPIで適切なファイルセットを検索します。
また、`pyproject.toml` ファイルを手動で変更する代わりに、`add` コマンドを使用できます。
$ poetry add pendulum
適切なバージョン制約を自動的に検出し、パッケージとサブ依存関係を**インストール**します。
Poetryは、キャレット、チルダ、ワイルドカード、不等式、複数の制約要件を含む、豊富な依存関係の仕様構文をサポートしています。
仮想環境の使用 #
デフォルトでは、Poetryは`{cache-dir}/virtualenvs` に仮想環境を作成します。Poetryの設定を編集してcache-dirの値を変更できます。また、virtualenvs.in-project設定変数を使用して、プロジェクトディレクトリ内に仮想環境を作成することもできます。
この仮想環境内でコマンドを実行するには、いくつかの方法があります。
外部仮想環境管理
Poetryは、外部でアクティブ化された既存の仮想環境を検出して尊重します。これは、Poetryの組み込みの簡素化された環境管理の代替として意図された強力なメカニズムです。
これを利用するには、環境を操作するPoetryコマンドを実行する前に、好みの方法またはツールを使用して仮想環境をアクティブ化します。
poetry run の使用 #
スクリプトを実行するには、単に `poetry run python your_script.py` を使用します。同様に、`pytest` や `black` などのコマンドラインツールがある場合は、`poetry run pytest` を使用して実行できます。
外部で独自の仮想環境を管理する場合は、`poetry run` や `poetry shell` を使用する必要はありません。おそらく、既にその仮想環境をアクティブ化し、正しいpythonインスタンスを使用可能にしているからです。例えば、これらのコマンドは同じpythonパスを出力するはずです。
conda activate your_env_name
which python
poetry run which python
poetry shell
which python
仮想環境の有効化 #
仮想環境を有効化するには、`poetry shell` を使用してネストされたシェルを作成するのが最も簡単な方法です。
仮想環境を無効化してこの新しいシェルを終了するには、`exit` と入力します。シェルを終了せずに仮想環境を無効化するには、`deactivate` を使用します。
なぜネストされたシェルなのか？
子プロセスは親から環境を継承しますが、共有しません。そのため、子プロセスによって行われた変更は、子プロセスが終了した後も保持されません。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を実行します。これらを1行にまとめることもできます。例えば、source $(poetry env info --path)/bin/activate（PowerShellでは& ((poetry env info --path) + "\Scripts\activate.ps1")）です。
この仮想環境を非アクティブ化するには、単にdeactivateを使用します。
| POSIXシェル | Windows (PowerShell) | 終了/非アクティブ化 | |
|---|---|---|---|
| サブシェル | poetry shell |
poetry shell |
exit |
| 手動アクティブ化 | source {path_to_venv}/bin/activate |
{path_to_venv}\Scripts\activate.ps1 |
deactivate |
| 1行コマンド | source $(poetry env info --path)/bin/activate |
& ((poetry env info --path) + "\Scripts\activate.ps1") |
deactivate |
バージョン制約 #
例では、バージョン制約^2.1でpendulumパッケージを要求しています。これは、2.1.0以上3.0.0未満（>=2.1.0 <3.0.0）のバージョンを意味します。
バージョン、バージョンの関係、依存関係の指定方法の詳細については、依存関係の指定を参照してください。
Poetry はどのようにして正しいファイルダウンロードするのですか？
pyproject.tomlで依存関係を指定すると、Poetry はまず要求されたパッケージの名前を取得し、repositoriesキーを使用して登録したすべてのリポジトリで検索します。追加のリポジトリを登録していない場合、または指定したリポジトリにその名前のパッケージが見つからない場合、PyPIにフォールバックします。
Poetry が正しいパッケージを見つけると、指定したバージョン制約に最適な一致を見つける試みが行われます。
依存関係のインストール #
プロジェクトの定義済みの依存関係をインストールするには、installコマンドを実行するだけです。
poetry install
このコマンドを実行すると、次の2つのいずれかが発生する可能性があります。
poetry.lockなしでのインストール #
コマンドを一度も実行したことがなく、poetry.lockファイルが存在しない場合、Poetry はpyproject.tomlファイルにリストされているすべての依存関係を解決し、それらのファイルの最新バージョンをダウンロードします。
Poetry がインストールを完了すると、ダウンロードしたすべてのパッケージとその正確なバージョンがpoetry.lockファイルに書き込まれ、プロジェクトがそれらの特定のバージョンにロックされます。プロジェクトに関わっているすべての人が同じバージョンの依存関係を使用するように、poetry.lockファイルをプロジェクトのリポジトリにコミットする必要があります（詳細は後述）。
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ファイルにリストされている一部の依存関係は、ファイルの作成以降に新しいバージョンがリリースされている可能性があります）。これは意図的なもので、依存関係の予期しない変更によってプロジェクトが壊れるのを防ぎます。
バージョン管理へのpoetry.lockファイルのコミット #
アプリケーション開発者として #
アプリケーション開発者は、より再現性の高いビルドを得るためにpoetry.lockをコミットします。
このファイルをバージョン管理システムにコミットすることは重要です。なぜなら、プロジェクトを設定する人は誰でも、あなたが使用しているものとまったく同じバージョンの依存関係を使用することになるからです。CIサーバー、本番マシン、チーム内の他の開発者、すべての人が同じ依存関係で動作するため、デプロイメントの一部にのみ影響するバグの可能性を軽減できます。一人で開発している場合でも、6ヶ月後にプロジェクトを再インストールする際に、依存関係が多くの新しいバージョンをリリースしていても、インストールされた依存関係がまだ機能していることを確信できます。（アップデートコマンドの使用に関する下の注記を参照してください。）
[build-system]セクションをプロジェクトのpyproject.tomlに追加した場合、pip install -e .のようなコマンドを使用して、プロジェクトとその依存関係を仮想環境に正常にインストールできます。ただし、pip は、poetry-coreビルドシステムはライブラリ開発者向けであるため（次のセクションを参照）、ロックファイルを使用して依存関係のバージョンを決定しません。ライブラリ開発者として #
ライブラリ開発者は、さらに考慮すべき事項があります。ユーザーはアプリケーション開発者であり、ライブラリは制御できないPython環境で実行されます。
アプリケーションはライブラリのロックファイルを無視します。pyproject.tomlの制約を満たす任意のバージョンの依存関係を使用できます。アプリケーションはおそらく、最新互換の依存関係バージョンを使用します。ライブラリのpoetry.lockが、ユーザーにとって問題を引き起こす新しい依存関係バージョンに遅れを取っている場合、おそらく最後にそのことに気付くのはあなたでしょう。
このようなシナリオを回避する簡単な方法は、poetry.lockファイルを省略することです。ただし、そうすることで、再現性とパフォーマンスをある程度犠牲にすることになります。ロックファイルがないと、明らかなコード変更に加えて、気付かないうちにライブラリの更新が原因となっている可能性があるため、テストの失敗の原因を見つけるのが困難になる可能性があります。さらに、poetry.lockが省略されている場合、Poetry は依存関係をインストールする前にロックする必要があります。依存関係の数によっては、ロックにかなりの時間がかかる可能性があります。
再現性とパフォーマンスの利点を放棄したくない場合は、poetry.lockの定期的な更新を検討して、最新の状態を維持し、ユーザーにとって突然の破損のリスクを軽減してください。
依存関係のみのインストール #
現在のプロジェクトは、デフォルトで編集可能モードでインストールされます。
依存関係のみをインストールする場合は、--no-rootフラグを付けてinstallコマンドを実行します。
poetry install --no-root
依存関係の最新バージョンへの更新 #
上記のように、poetry.lockファイルは、依存関係の最新バージョンを自動的に取得するのを防ぎます。最新バージョンに更新するには、updateコマンドを使用します。これにより、（pyproject.tomlファイルに従って）最新のバージョンが取得され、ロックファイルが新しいバージョンで更新されます。（これは、poetry.lockファイルを削除してinstallをもう一度実行することと同じです。）
poetry.lockとpyproject.tomlが同期されていない場合、installコマンドを実行すると、Poetryは**警告**を表示します。