Repositories

Poetryでは、PyPIとプライベートリポジトリを使用して、パッケージを検出したり、プロジェクトを公開したりすることができます。

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

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

これはほとんどのケースを表しており、ほとんどのユーザーにとっては十分である可能性があります。

Private Repository Example

Installing from private package sources

デフォルトでは、PoetryはPyPIからパッケージを検出してインストールします。しかし、simple API repository用の依存関係をプロジェクトにインストールしたい場合はどうすればよいでしょうか。

まず、package sourceをsupplemental(またはexplicit)パッケージソースとしてプロジェクトにconfigureします。

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

次に、リポジトリが認証を必要とすると仮定して、認証情報を設定します。

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

Warning

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

Note

パスワードを対話的に入力したい場合は、コマンド中の<password>を単に省略することができます。また、Poetryによって、認証情報を手動で入力するように求められます。

poetry config http-basic.foo <username>

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

poetry add --source foo private-package

Publishing to a private repository

あとはパッケージを公開するだけです。チームとプライベートに共有したい場合は、Upload APIエンドポイントをpublishable repository用に設定できます。

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

Note

package sourceに別の資格情報を使用する必要がある場合は、発行リポジトリに別の名前を使用することをお勧めします。

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

Note

環境変数を使用してレポジトリを設定する場合は、正しいサフィックスを使用する必要があります。

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

Package Sources

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

Note

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

Project Configuration

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

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

Note

パッケージソースにcredentialsまたはcertificatesが必要な場合は、以下の関連するセクションを参照してください。

これにより、pyproject.tomlファイルに次の設定スニペットが生成されます。

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

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

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

default source(非推奨)
primary sources
暗黙的なPyPI(別のprimary source、default sourceによって無効にされているか、明示的に設定されている場合を除く)
secondary sources(非推奨)
supplemental sources。

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

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

Note

PyPIの優先度を変更したい場合は、以下のように明示的に設定できます。

poetry source add --priority=primary PyPI

PyPIを完全に無効にしたい場合は、primary sourceを追加するか、PyPIをexplicit sourceとして設定します。

Default Package Source (DEPRECATED)

Deprecated in 1.8.0

Warning

デフォルトのパッケージソースの設定は、topmostprimary sourceと同じであるため、推奨されません。プライマリパッケージソースを設定し、それをパッケージソースのリストの最初に配置します。

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

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

Primary Package Sources

すべてのプライマリパッケージソースは、source constraintを使用せずに、依存関係ごとに検索されます。少なくとも1つのプライマリソースを設定すると、暗黙的なPyPIソースは無効になります。

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

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

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

Warning

少なくとも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で構成することはできません。poetry checkを使用して、pyproject.tomlファイルの有効性を常に確認できます。

Secondary Package Sources (DEPRECATED)

Deprecated in 1.5.0

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

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

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

セカンダリパッケージソースは複数存在する場合があります。

Warning

二次パッケージソースは廃止され、補助パッケージソースが使用されるようになりました。

Supplemental Package Sources

Introduced in 1.5.0

サプリメンタルとして設定されたパッケージソースは、互換性のあるパッケージディストリビューションを生成する他の(プライオリティの高い)ソースがない場合にだけ検索されます。これは、ソースの応答時間が長く、このソースから取得するパッケージ配布が比較的少ない場合に特に便利です。

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

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

複数の補足パッケージソースが存在する場合があります。

Warning

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

Explicit Package Sources

Introduced in 1.5.0

パッケージソースが明示的に設定されている場合、このソースが検索されるのは、パッケージ設定explicitly indicatesでこのパッケージソースで検出される必要がある場合だけです。

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

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

複数の明示的なパッケージソースを指定できます。

Note

明示的なパッケージソースが有用な実世界の例は、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

Package Source Constraint

すべてのパッケージソース(二次ソースおよび場合によっては補足ソースを含む)は、パッケージルックアッププロセス中に検索されます。このネットワーク要求は、パッケージが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 = ...

Note

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

Note

パッケージのsourceキーは、その依存関係によって継承されません。特に、package-Aがsource=internal-pypiにあるように設定されていて、package-Aがpackage-Bに依存しており、package-Bもinternal-pypiにある場合、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@*

Note

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

Supported Package Sources

Python Package Index (PyPI)

Poetryは、JSON APIを介してPyPIと相互作用します。これは、要求されたパッケージのバージョン、メタデータ、ファイルなどを取得するために使用されます。

Note

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

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

poetry add --source pypi httpx@^0.22.0

これにより、pyproject.tomlファイルに次の設定スニペットが生成されます。

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

Warning

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

Simple API Repository

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

Warning

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

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

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

Note

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

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

Note

メタデータが利用できないのに、なぜPoetryはすべてのプラットフォームのすべての候補ディストリビューションをダウンロードすることを主張するのですか?

これが必要なのは、Poetryのロック・ファイルがプラットフォームに依存しないためです。つまり、プロジェクトの依存関係を解決するために、Poetryはすべてのプラットフォーム固有のディストリビューションのメタデータを必要とします。また、このメタデータが容易に入手できない場合は、ディストリビューションをダウンロードしてローカルで検査することが、残された唯一の選択肢です。

Single Page Link Source

Introduced in 1.2.0

一部のプロジェクトでは、PEP 503のパッケージページの構造に部分的に従った単一ページリンクソースを介してバイナリディストリビューションをリリースすることを選択しています。

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

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

Note

単純なAPIリポジトリで説明されている解決時間の遅さに関するすべての警告は、ここでも適用されます。

Publishable Repositories

Poetryでは、package sourcesとは異なり、パッケージを公開するリポジトリをプロジェクト固有の構成ではなく、ユーザー固有の構成として扱います。現在、Poetryでは、プロジェクトを公開するときに、Legacy Upload API のみをサポートしています。

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

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

Note

Legacy Upload APIURLは、通常、シンプルAPIのリポジトリによって提供される同じURLとは異なります。 Test PyPIの例では、ホスト(test.PyPI.org)とパス(/legacy)の両方が単純なAPI(https://test.PyPI.org/simple)とは異なることに注意してください。

Configuring Credentials

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

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

パスワードを指定しない場合は、パスワードを書き込むように求められます。

Note

PyPIに公開するには、PyPIという名前のリポジトリに資格情報を設定します。

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

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

testpypiをPublishable Repositoryとして設定するときに、トークンを設定することができます。

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

自分のユーザ名とパスワードを使いたい場合は、次のようにconfigを呼び出してください。

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

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

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

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

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

poetry config keyring.enabled false

Note

Poetryはピップスタイルのキーリングの使用に戻り、次のようなバックエンドが Microsoftのartifacts-keyringは、有効な資格情報を取得する機会があります。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を設定する方法の詳細については、Using environment variablesを参照してください。

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

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

Certificates

Custom certificate authority and mutual TLS authentication

Poetryは、証明書ベースのクライアント認証を必要とするリポジトリだけでなく、カスタム認証局によって保護されたリポジトリもサポートします。次の例では、カスタム認証局を使用してリポジトリの証明書を検証し、クライアント証明書を使用するように"foo"リポジトリを設定します(この設定変数の両方を設定する必要はありません)。

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

Note

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

poetry config certificates.foo.cert false

Warning

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

Caches

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

第1レベルのキャッシュは、ほとんどすべてのHTTP要求に対するCache-Controlヘッダーベースのキャッシュです。

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

Debugging Issues

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

poetry --no-cache add pycowsay

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

あるいは、非常に冗長なロギング-vvvを--no-cacheとともに有効にして、ログ内で行われているネットワーク要求を確認することもできます。