コンテンツにスキップ

FAQ

Why is the dependency resolution process slow?

Poetryの中心にある依存関係リゾルバは高度に最適化されており、ほとんどのケースで十分に高速である必要がありますが、特定の依存関係のセットでは、有効なソリューションを見つけるのに時間がかかる場合があります。

これは、PyPI上のすべてのライブラリがメタデータを適切に宣言しているわけではなく、PyPI JSON APIを介して利用できないためです。 この時点で、Poetryはパッケージをダウンロードし、必要な情報を得るために検査する以外に選択の余地はありません。これは、帯域幅と時間の両方において高価な操作であり、そのため、時間がかかるプロセスであると思われます。

今のところ、それを回避する方法はありません。ただし、Poetryが1つのパッケージの多数のバージョンをダウンロードしていることに気付いた場合は、pyproject.toml内のその1つのパッケージをより狭く制限することで、作業負荷を軽減できます。 そうすることで、Poetryは多くのバージョンをふるいにかける必要がなくなり、場合によってはロック処理が大幅に高速化される可能性があります。

Note

Poetryがリリースの情報をマシンにキャッシュしてしまえば、依存関係の解決プロセスはずっと速くなります。

What kind of versioning scheme does Poetry use for itself?

Poetryは、PEP 440で言及されているように、"major.minor.micro"バージョン識別子を使用します。

バージョンアップは、Pythonのバージョン管理と同様に行われます。

  • メジャーバージョンアップ(最初の番号のインクリメント)は、非推奨サイクルが不可能で、多くのユーザがあるバージョンから次のバージョンに移行するためにいくつかの手動ステップを実行しなければならない場合に、重大な変更に対してのみ行われます。
  • マイナーバージョンアップ(2番目の数字を増分)には、新機能だけでなく、以前のマイナー・リリースで非推奨になった新しい非推奨機能や削除機能が含まれる場合があります。
  • マイクロバージョンアップ(3番目の数字を増分)には、通常、バグ修正のみが含まれます。非推奨の機能はマイクロリリースでは削除されません。

Why does Poetry not adhere to semantic versioning?

ユーザーベースが大きいため、ほとんどのユーザーが適切と考えていない小さな変更であっても、後になって一部のユーザーにとっては重大な変更となる可能性があります。 厳密なセマンティックバージョニングに固執し、(ほぼ)常にマイナーバージョンではなくメジャーバージョンをアップすることは、マイナーバージョンがもはや何の意味も持たないので、望ましくないように思われます。

Are unbound version constraints a bad idea?

*や>=3.4のような上限のないバージョン制約では、依存関係の将来のバージョンを更新することができます。 これには、下位互換性を破る主要なバージョンも含まれます。

パッケージのリリースが公開されると、依存関係がBCを壊した場合にその依存関係を調整することはできなくなります。新しいリリースを実行する必要がありますが、以前のリリースは壊れたままです。(ユーザは、自分で制限することで、壊れた依存関係を回避することができます。)

このような問題を避けるために、制約の上限を定義することができます。上限は、パッケージが新しいメジャーバージョンの依存関係と互換性があることをテストした後、新しいリリースで増やすことができます。

例えば、>=3.4を使用する代わりに、^3.4を使用して、すべてのバージョン<4.0を許可することができます。 ^演算子は、semantic versioningに従ったライブラリで非常にうまく動作します。

ただし、上限を定義する場合、パッケージのユーザーは、上限を超えて依存関係を更新することはできません。上限が何も壊れておらず、パッケージと完全に互換性がある場合でもです。 まず、上限を増やした新しいバージョンのパッケージをリリースする必要があります。

パッケージが他のパッケージのライブラリとして使用される場合は、上限を避け、不要な依存関係の競合を避けることをお勧めします(ただし、依存関係の次のリリースでパッケージが破損することが確実にわかっている場合は除きます)。 パッケージをアプリケーションとして使用する場合は、上限を定義する価値があります。

Is tox supported?

Yess tox>=4を使用している場合は、Poetryが提供するPEP 517準拠のビルドシステムと組み合わせて使用できます(tox 3では、isolated buildオプションを設定する必要があります)。

そのため、pyproject.tomlファイルに次のセクションが存在しない場合は追加します。

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

toxは複数の方法で設定できます。それはテスト対象のコードが何であるべきか、そしてどの依存関係がインストールされるべきかによって異なります。

Use case #1

[tox]

[testenv]
deps =
    pytest
commands =
    pytest tests/ --import-mode importlib

toxはプロジェクトのsdistパッケージを作成し、pipを使用して新しい環境にインストールします。 したがって、依存関係はpipによって解決されます。

Use case #2

[tox]

[testenv]
allowlist_externals = poetry
commands_pre =
    poetry install --no-root --sync
commands =
    poetry run pytest tests/ --import-mode importlib

toxはプロジェクトのsdistパッケージを作成し、pipを使用して新しい環境にインストールします。 したがって、依存関係は最初にpipによって解決されます。しかし、その後、ロックされた依存関係を環境にインストールするPoetryを実行します。

Use case #3

[tox]

[testenv]
skip_install = true
allowlist_externals = poetry
commands_pre =
    poetry install
commands =
    poetry run pytest tests/ --import-mode importlib

toxはインストールを行いません。Poetryはすべての依存関係と現在のパッケージを編集可能モードでインストールします。 そのため、テストは構築およびインストールされたパッケージではなく、ローカルファイルに対して実行されます。

Note about credentials

toxはデフォルトでは現在のシェルセッションの環境変数を転送しないことに注意してください。 これにより、Linuxシステムでシステムのキーリングを使用して、または一般的な環境変数を使用して認証情報を設定した場合、Poetryがtox環境に依存関係をインストールできなくなる可能性があります。 passenvconfiguration optionを使用して必要な変数を明示的に転送するか、passenv="*"を使用してすべての変数を転送できます。 Linuxシステムでは、システムのキーリングへのアクセスを許可するためにDBUS_SESSION_BUS_ADDRESS変数の転送が必要になる場合がありますが、これはデスクトップ環境によって異なる場合があります。

または、キーリングを完全に無効にすることもできます。

poetry config keyring.enabled false

これにより、Poetryがプレーンテキストのconfigファイルにパスワードを書き込むことに注意してください。 この設定を変更した後、資格情報を再度設定する必要があります。

Is Nox supported?

nox-poetryパッケージを使用して、poetry.lockで指定された依存関係のロックされたバージョンをNoxセッションにインストールします。

I don't want Poetry to manage my virtual environments. Can I disable it?

Poetryは、グローバルなPythonインストールから常に分離されて動作する仮想環境を自動的に作成するが、Poetryで管理された仮想環境を使用できない、または好まれないまれなシナリオがあります。

この場合、virtualenvs.create設定をfalseに設定して、この機能を無効にすることができます。

poetry config virtualenvs.create false

Warning

コンテナ内にアプリケーションをインストールする場合を含め、推奨されるベストプラクティスは、仮想環境を利用することです。これは、別のツールで管理することもできます。

Poetryチームは、仮想環境の使用を強く推奨しています。

Why is Poetry telling me that the current project's supported Python range is not compatible with one or more packages' Python requirements?

pipとは異なり、Poetryは現在の環境でPythonだけを解決するのではなく、pyproject.tomlで指定されたPythonバージョンの範囲内で依存関係が解決できることを確認します。

以下のpyproject.tomlがあるとします。

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

これは、プロジェクトが3.7以上4.0未満の任意のPythonバージョンと互換性を持つことを目的としていることを意味します。 Pythonの要件が範囲全体と一致しない依存関係を追加しようとすると、Poetryは次のように答えます。

The current project's supported Python range (>=3.7.0,<4.0.0) is not compatible with some of the required packages Python requirement:
    - scipy requires Python >=3.7,<3.11, so it will not be satisfied for Python >=3.11,<4.0.0

通常は、プロジェクトでサポートされているPythonの範囲と、失敗した依存関係の上限を一致させます。 あるいは、すべてのバージョンで必要なわけではないことがわかっている場合は、Poetryにこの依存関係をインストールするように指示only for a specific range of Python versionsすることもできます。

Why does Poetry enforce PEP 440 versions?

これは、より広範なPythonエコシステムに準拠するために行われています。

たとえば、PoetryがPEP 440に従って有効でないバージョンを使用するプロジェクトのディストリビューションを構築した場合、サードパーティのツールはそのバージョンを正しく解析できません。

Poetry busts my Docker cache because it requires me to COPY my source files in before installing 3rd party dependencies

デフォルトでは、poetry install ...を実行するには、ソースファイルが存在している必要があります("ルート"パッケージと、ディレクトリパスの依存関係の両方)。 これは、Dockerのキャッシングメカニズムとの相互作用が悪い。ソースファイルを変更すると、レイヤ(Dockerfile内の後続のコマンド)が再実行されます。 たとえば、次のようなDockerfileがあるとします。

FROM python
COPY pyproject.toml poetry.lock .
COPY src/ ./src
RUN pip install poetry && poetry install --only main

任意のソースファイルが変更されるとすぐに、RUNレイヤのキャッシュは無効になり、src/内のファイルを変更した場合は、すべてのサードパーティの依存関係(おそらくこの中で最も遅いステップ)が強制的に再インストールされます。

このキャッシュバスを回避するには、次の2つの手順に分けます。

  1. サードパーティの依存関係をインストールします。
  2. ソースコードをコピーして、ソースコードだけをインストールします。

これは次のようになります。

FROM python
COPY pyproject.toml poetry.lock .
RUN pip install poetry && poetry install --only main --no-root --no-directory
COPY src/ ./src
RUN poetry install --only main

ここで使用している2つの主要なオプションは、--no-root(プロジェクトソースのインストールをスキップします)と--no-directory(ローカルディレクトリパスの依存関係のインストールをスキップします。依存関係がない場合は省略できます)です。poetry installで利用可能なオプションに関する詳細情報。

My requests are timing out!

PIP_REQUESTS_TIMEOUTと同様に、試験的な環境変数POETRY_REQUESTS_TIMEOUTを設定してこの値を変更することができます。