リポジトリ

リポジトリ #

Poetryは、パッケージの検出とプロジェクトの公開に、PyPIとプライベートリポジトリの両方を使用できます。

デフォルトでは、Poetryはパッケージのインストールと公開にPyPIリポジトリを使用するように設定されています。

そのため、プロジェクトに依存関係を追加する場合、PoetryはそれらがPyPIで利用可能であると想定します。

これはほとんどのケースを表しており、ほとんどのユーザーにとって十分でしょう。

プライベートリポジトリの例 #

プライベートパッケージソースからのインストール #

デフォルトでは、PoetryはPyPIからパッケージを検出してインストールします。しかし、シンプルなAPIリポジトリのためにプロジェクトに依存関係をインストールしたい場合はどうでしょうか？やってみましょう。

まず、パッケージソースを補足的（または明示的）パッケージソースとしてプロジェクトに設定します。

poetry source add --priority=supplemental foo https://pypi.example.org/simple/

次に、リポジトリが認証を必要とする場合は、その認証情報を設定します。

poetry config http-basic.foo <username> <password>

警告

システム構成によっては、認証情報がコマンドラインの履歴に保存される場合があります。多くのシェルは、コマンドの前にスペース文字が付いている場合、履歴にコマンドを保存しません。詳細については、シェルのドキュメントを参照してください。

注記

パスワードをインタラクティブに入力したい場合は、コマンドの<password>を省略するだけです。Poetryは認証を手動で入力するように求めます。

poetry config http-basic.foo <username>

これが完了したら、このソースからプロジェクトに依存関係を追加できます。

poetry add --source foo private-package

プライベートリポジトリへの公開 #

これで、パッケージを公開するだけです。チームとプライベートに共有したい場合は、公開可能なリポジトリのアップロードAPIエンドポイントを設定できます。

poetry config repositories.foo https://pypi.example.org/legacy/

注記

パッケージソースに別の認証情報を使用する必要がある場合は、公開リポジトリに別の名前を使用することをお勧めします。

poetry config repositories.foo-pub https://pypi.example.org/legacy/
poetry config http-basic.foo-pub <username> <password>

注記

環境変数を使用してリポジトリを設定する場合は、正しいサフィックスを使用する必要があることに注意してください。

export POETRY_REPOSITORIES_FOO_URL=https://pypi.example.org/legacy/
export POETRY_HTTP_BASIC_FOO_USERNAME=<username>
export POETRY_HTTP_BASIC_FOO_PASSWORD=<password>

これで、publishコマンドを使用してプロジェクトをビルドして公開するだけです。

poetry publish --build --repository foo-pub

パッケージソース #

デフォルトでは、PoetryはPythonエコシステムの標準パッケージインデックスであるPyPIを使用するように設定されています。

注記

pypiという名前のPyPI用に暗黙的に設定されたソースを除いて、パッケージソースはプロジェクトに対してローカルであり、プロジェクトのpyproject.tomlファイル内で設定する必要があります。これは、パッケージを公開するときに使用される設定と**同じではありませ**ん。

プロジェクト設定 #

これらのパッケージソースは、プロジェクトのsourceコマンドを使用して管理できます。

poetry source add foo https://foo.bar/simple/

注記

パッケージソースに認証情報または証明書が必要な場合は、以下の関連セクションを参照してください。

これは、pyproject.tomlファイルに次の設定スニペットを生成します。

[[tool.poetry.source]]
name = "foo"
url = "https://foo.bar/simple/"
priority = "primary"

priorityが未定義の場合、ソースはPyPI、セカンダリ、補足、および明示的なソースよりも優先されるプライマリソースと見なされます。

パッケージソースは次の順序で考慮されます.

デフォルトソース (非推奨)、
プライマリソース,
暗黙のPyPI（別のプライマリソース、デフォルトソースによって無効化されていないか、明示的に設定されていない限り）,
セカンダリソース (非推奨)、
補足ソース.

明示的なソースは、明示的にソースを示すパッケージに対してのみ考慮されます。

各優先度クラス内では、パッケージソースはpyproject.tomlでの出現順に考慮されます。

注記

PyPIの優先度を変更する場合は、明示的に設定できます。例：

poetry source add --priority=primary PyPI

PyPIを完全に無効にする場合は、プライマリソースを追加するか、PyPIを明示的なソースとして設定します.

デフォルトパッケージソース (非推奨) #

1.8.0で非推奨

警告

デフォルトパッケージソースの設定は、最上位のプライマリソースと同じであるため、非推奨です。プライマリパッケージソースを設定し、パッケージソースのリストの先頭に配置するだけです。

デフォルトでは、プライマリソースを設定していない場合、PoetryはプロジェクトのパッケージソースとしてPyPIを設定します。この動作を変更し、設定されたパッケージソースからのみパッケージを検索するようにするには、少なくとも1つのプライマリソースを追加する（推奨）か、priority = "default"を持つ**単一**のソースを追加します（非推奨）。

poetry source add --priority=default foo https://foo.bar/simple/

プライマリパッケージソース #

ソースの制約のない各依存関係について、すべてのプライマリパッケージソースが検索されます。少なくとも1つのプライマリソースを設定すると、暗黙のPyPIソースは無効になります。

poetry source add --priority=primary foo https://foo.bar/simple/

優先度のないソースもプライマリソースと見なされます。

poetry source add foo https://foo.bar/simple/

警告

少なくとも1つのプライマリソースが設定されている場合、暗黙のPyPIソースは自動的に無効になります。プライマリソースに加えてPyPIを使用する場合は、特定の優先度で明示的に設定します。例：

poetry source add --priority=primary PyPI

このようにして、PyPIの優先順位をきめ細かく設定できます。

pyproject.tomlにおける同等の仕様は次のとおりです。

[[tool.poetry.source]]
name = "pypi"
priority = "primary"

**PyPIを明示的に指定する場合は、urlを省略してください。** PyPIはPoetryで内部的に設定されているため、PyPIリポジトリを特定のURLで設定することはできません。pyproject.tomlファイルの有効性を確認するには、いつでもpoetry checkを使用できます。

セカンダリパッケージソース (非推奨) #

1.5.0で非推奨

パッケージソースがセカンダリとして設定されている場合、それは、デフォルトおよびプライマリパッケージソースにも存在する互換性のあるパッケージディストリビューションを選択する際に、これらの優先順位が低くなることを意味します. 代わりに、優先順位の高いリポジトリが結果を返さなかった場合にのみパッケージソースを検索する必要がある場合は、補足ソースを検討してください。

パッケージソースの設定でpriority = "secondary"と指定することで、パッケージソースをセカンダリソースとして設定できます。

poetry source add --priority=secondary foo https://foo.bar/simple/

複数のセカンダリパッケージソースを設定できます。

警告

セカンダリパッケージソースは、補足パッケージソースに代わって非推奨となっています。

#補助パッケージソース

バージョン 1.5.0 で導入

補助として設定されたパッケージソースは、他の（優先順位の高い）ソースが互換性のあるパッケージ配布を提供しない場合にのみ検索されます。これは、ソースの応答時間が長く、このソースから取得するパッケージ配布が比較的少ない場合に特に便利です。

パッケージソース設定で `priority = "supplemental"` を使用して、パッケージソースを補助ソースとして設定できます。

poetry source add --priority=supplemental foo https://foo.bar/simple/

補助パッケージソースは複数存在できます。

警告

誰かがプライマリソースに新しいパッケージを公開し、それが補助ソースのパッケージと一致する可能性があることに注意してください。彼らは偶然または意図的に、予期しないものと依存関係を置き換える可能性があります。

#明示的パッケージソース

バージョン 1.5.0 で導入

パッケージソースが明示的として設定されている場合、これらのソースは、パッケージ設定が明示的に示している場合にのみ検索されます。

パッケージソース設定で `priority = "explicit"` を使用して、パッケージソースを明示的ソースとして設定できます。

poetry source add --priority=explicit foo https://foo.bar/simple/

明示的パッケージソースは複数存在できます。

注記

明示的パッケージソースが役立つ実際の例は、PyTorch GPU パッケージです。

poetry source add --priority=explicit pytorch-gpu-src https://download.pytorch.org/whl/cu118
poetry add --source pytorch-gpu-src torch torchvision torchaudio

#パッケージソース制約

パッケージのルックアッププロセス中に、すべてのパッケージソース（セカンダリソースおよび場合によっては補助ソースを含む）が検索されます。これらのネットワークリクエストは、パッケージが1つ以上のソースで見つかったかどうかに関係なく、すべてのソースに対して発生します。

特定のパッケージの検索を特定のパッケージリポジトリに制限するには、ソースを明示的に指定できます。

poetry add --source internal-pypi httpx

これは、`pyproject.toml` で次の設定になります。

[tool.poetry.dependencies]
...
httpx = { version = "^0.22", source = "internal-pypi" }

[[tool.poetry.source]]
name = "internal-pypi"
url = ...
priority = ...

注記

特定のパッケージを取得するための唯一のソースとして設定されているリポジトリ自体は、任意の優先順位を持つことができます。特に、優先順位 ` "explicit"` を持つ必要はありません。リポジトリがパッケージのソースとして設定されている場合、そのパッケージに対して考慮される唯一のソースとなり、リポジトリの優先順位は解決に影響を与えません。

注記

パッケージの `source` キーは、その依存関係によって継承されません。特に、`package-A` が `source = internal-pypi` に設定されており、`package-A` が `internal-pypi` にも見つかる `package-B` に依存している場合、`package-B` は `pyproject.toml` でそのように設定する必要があります。これを達成する最も簡単な方法は、ワイルドカード制約を使用して `package-B` を追加することです。

poetry add --source internal-pypi package-B@*

これにより、`package-B` が `internal-pypi` パッケージソースでのみ検索されるようになります。 `package-B` のバージョン制約は、通常どおり `package-A`（およびその他のクライアントパッケージ）から派生します。

追加のメイン依存関係を避けたい場合は、専用の依存関係グループに `package-B` を追加できます。

poetry add --group explicit --source internal-pypi package-B@*

注記

依存関係の混乱攻撃を回避するために、1つの特定のソースによってのみ提供されることが予想されるすべてのパッケージに対して、パッケージソース制約を強く推奨します。

#サポートされているパッケージソース

#Python Package Index (PyPI)

Poetry は、JSON API を介して PyPI と対話します。これは、リクエストされたパッケージのバージョン、メタデータ、ファイルなどを取得するために使用されます。

注記

パッケージの公開されたメタデータが無効な場合、Poetry は利用可能な bdist/sdist をダウンロードしてローカルで検査し、関連するメタデータを識別します.

PyPI からパッケージを明示的に選択する場合は、以下に示すように、`add` コマンドで `--source` オプションを使用できます。

poetry add --source pypi httpx@^0.22.0

これは、`pyproject.toml` ファイルに次の設定スニペットを生成します。

httpx = {version = "^0.22.0", source = "pypi"}

警告

プロジェクト内のソースが `priority = "default"` で設定されている場合、暗黙的な `pypi` ソースは無効になり、どのパッケージにも使用されません。

#Simple API リポジトリ

Poetry は、PEP 503 で説明されているように、simple repository API を実装するパブリックまたはプライベートのカスタムリポジトリからパッケージの依存関係を取得してインストールできます。

警告

ファイル URL にファイルチェックサムを提供せずに大きなホイールを配布するソースを使用する場合、Poetry はチェックサムを生成するために各候補ホイールを少なくとも1回ダウンロードします。これは、このソースからパッケージを追加するときに、依存関係の解決時間が長くなる可能性があります。

これらのパッケージソースは、プロジェクトで次のコマンドを使用して設定できます。

poetry source add testpypi https://test.pypi.org/simple/

注記

末尾の `/simple/` に注意してください。PEP 503 準拠のパッケージソースを設定する場合、これは重要です。

PEP 503 に加えて、Poetry は PEP 658 を実装する simple API リポジトリも処理できます（*バージョン 1.2.0 で導入*）。これは、Poetry が関連するメタデータを決定するために各候補配布をダウンロードする必要がないため、これらのソースからのパッケージの依存関係解決時間を短縮するのに役立ちます。

注記

メタデータが利用できない場合、Poetry はなぜすべてのプラットフォームのすべての候補配布のダウンロードを主張するのですか？

これが必要なのは、Poetry のロックファイルがプラットフォームに依存しないためです。これは、プロジェクトの依存関係を解決するために、Poetry にはすべてのプラットフォーム固有の配布のメタデータが必要であることを意味します。そして、このメタデータがすぐに入手できない場合、配布をダウンロードしてローカルで検査することが唯一残された選択肢です。

#単一ページリンクソース

バージョン 1.2.0 で導入

一部のプロジェクトは、PEP 503 のパッケージページの構造に部分的に従う単一ページリンクソースを介してバイナリ配布をリリースすることを選択しています。

これらのパッケージソースは、プロジェクトで次のコマンドを使用して設定できます。

poetry source add jax https://storage.googleapis.com/jax-releases/jax_releases.html

注記

simple API リポジトリについて説明した解決時間の遅延に関するすべての注意事項は、ここにも適用されます。

#公開可能なリポジトリ

Poetry は、パッケージを公開するリポジトリを、パッケージソースとは異なり、ユーザー固有の設定として扱い、プロジェクト固有の設定としては扱いません。 Poetry は現在、プロジェクトを公開する際にレガシーアップロード API のみをサポートしています。

これらは、`config` コマンドを使用して、`repositories` キーの下に設定されます。

poetry config repositories.testpypi https://test.pypi.org/legacy/

注記

レガシーアップロード API の URL は、通常、simple API 用にリポジトリによって提供される URL とは異なります。 Test PyPI の例では、ホスト（`test.pypi.org`）とパス（`/legacy`）の両方が simple API（`https://test.pypi.org/simple`）とは異なることに注意してください。

#認証情報の構成

特定のリポジトリの認証情報を保存する場合は、簡単に実行できます。

poetry config http-basic.foo <username> <password>

パスワードを指定しない場合は、パスワードを入力するように求められます。

注記

PyPI に公開するには、`pypi` という名前のリポジトリの認証情報を設定できます。

PyPI にパッケージをアップロードする際は、API トークンを使用することをお勧めします。新しいトークンを作成したら、Poetry にそれを使用するように指示できます。

poetry config pypi-token.pypi <my-token>

**testpypi** を公開可能なリポジトリとして設定した場合、トークンは次のように設定できます。

poetry config pypi-token.testpypi <your-token>

それでもユーザー名とパスワードを使用する場合は、`config` を次のように呼び出すことで使用できます。

poetry config http-basic.pypi <username> <password>

`publish` コマンドを使用する際に、`--username` および `--password` オプションを使用してユーザー名とパスワードを指定することもできます。

システムキーリングが利用可能でサポートされている場合、パスワードはキーリングに保存され、キーリングから取得されます。上記の例では、認証情報は `poetry-repository-pypi` という名前を使用して保存されます。キーリングへのアクセスに失敗した場合、またはキーリングがサポートされていない場合は、ユーザー名とともに `auth.toml` ファイルにパスワードを書き込むことにフォールバックします。

キーリングのサポートは、keyring ライブラリを使用して有効になっています。サポートされているバックエンドの詳細については、ライブラリのドキュメントを参照してください。

キーリングを使用したくない場合は、Poetry にキーリングを無効にして認証情報をプレーンテキスト設定ファイルに保存するように指示できます。

poetry config keyring.enabled false

注記

Poetry は、Microsoft の artifacts-keyring などのバックエンドが有効な認証情報を取得できるように、Pip スタイルのキーリングの使用にフォールバックします。 Poetry の virtualenv に適切にインストールする必要があります。プラグインをインストールするのが望ましいです。

代わりに、環境変数を使用して認証情報を提供することもできます。

export POETRY_PYPI_TOKEN_FOO=my-token
export POETRY_HTTP_BASIC_FOO_USERNAME=<username>
export POETRY_HTTP_BASIC_FOO_PASSWORD=<password>

ここで、`FOO` はリポジトリの名前を大文字にしたものです（例：`PYPI`）。環境変数を使用した Poetry の設定方法の詳細については、環境変数の使用を参照してください。

パスワードがダッシュで始まる場合（例：CI 環境でランダムに生成されたトークン）、パスワードではなくコマンドラインオプションとして解析されます。これを防ぐには、二重ダッシュを追加して、後続の引数がオプションとして解析されないようにします。

poetry config -- http-basic.pypi myUsername -myPasswordStartingWithDash

#証明書

#カスタム認証局と相互 TLS 認証

Poetry は、カスタム認証局によって保護されているリポジトリと、証明書ベースのクライアント認証を必要とするリポジトリをサポートしています。以下は、「foo」リポジトリを構成して、カスタム認証局を使用してリポジトリの証明書を検証し、クライアント証明書を使用します（これらの設定変数の両方を設定する必要はありません）。

poetry config certificates.foo.cert /path/to/ca.pem
poetry config certificates.foo.client-cert /path/to/client.pem

注記

証明書の検証をスキップする必要がある場合、`certificates.<repository>.cert` の値を `false` に設定できます。これは、自己署名証明書を持つパッケージソースが使用される場合に役立ちます。

poetry config certificates.foo.cert false

警告

証明書の検証を無効にすることは、セキュリティのベストプラクティスに準拠していないため、お勧めしません。

#キャッシュ

Poetry は、ユーザーエクスペリエンスを向上させ、重複するネットワークリクエストを回避するために、パッケージソースの複数のキャッシュを使用します。

最初のレベルのキャッシュは、ほぼすべての HTTP リクエストの Cache-Control ヘッダーベースのキャッシュです。

さらに、すべての HTTP バックエンドパッケージソースは、パッケージに関連付けられたメタデータを、フェッチまたは生成されたらキャッシュします。さらに、ダウンロードされたファイル（パッケージ配布）もキャッシュされます。

#問題のデバッグ

パッケージソースで問題が発生した場合は、問題をデバッグするために行うことができる最も簡単な手順の1つは、`--no-cache` フラグを付けてコマンドを再実行することです。

poetry --no-cache add pycowsay

これで問題が解決した場合は、`cache` コマンドを使用してキャッシュをクリアすることを検討できます。

または、ログに作成されているネットワークリクエストを確認するために、`--no-cache` とともに非常に詳細なログ記録 `-vvv` を有効にすることもできます。