Dependency specification

プロジェクトの依存関係は、さまざまな形式で指定できます。この形式は、依存関係のタイプと、インストールに必要なオプションの制約によって異なります。

Version constraints

Caret requirements

Caret requirements SemVerと互換性のある特定のバージョンへの更新を許可します。新しいバージョン番号がメジャー、マイナー、パッチグループの左端の0以外の桁を変更しない場合、更新が許可されます。たとえば、以前にpoetry add requests@^2.13.0を実行し、ライブラリを更新したいと思ってpoetry update requestsを実行した場合、poetryはバージョン2.14.0が利用可能であればそれに更新しますが、3.0.0には更新しません。代わりにバージョン文字列を^0.1.13と指定した場合、poetryは0.1.14に更新されますが、0.2.0には更新されません。0.0.xは他のバージョンと互換性があるとは見なされません。

以下に、Caret requirementsの例と、それによって許可されるバージョンをいくつか示します。

Requirement	Versions allowed
^1.2.3	>=1.2.3 <2.0.0
^1.2	>=1.2.0 <2.0.0
^1	>=1.0.0 <2.0.0
^0.2.3	>=0.2.3 <0.3.0
^0.0.3	>=0.0.3 <0.0.4
^0.0	>=0.0.0 <0.1.0
^0	>=0.0.0 <1.0.0

Tilde requirements

Tilde requirementsは、何らかの更新機能を備えた最小バージョンを指定します。メジャーバージョン、マイナーバージョン、およびパッチバージョンを指定するか、メジャーバージョンとマイナーバージョンのみを指定すると、パッチレベルの変更のみが許可されます。メジャーバージョンのみを指定した場合は、マイナーレベルおよびパッチレベルの変更が許可されます。

~1.2.3 is an example of a tilde requirement.

Requirement	Versions allowed
~1.2.3	>=1.2.3 <1.3.0
~1.2	>=1.2.0 <1.3.0
~1	>=1.0.0 <2.0.0

Wildcard requirements

Wildcard requirementsは、ワイルドカードが配置されている最新の(依存関係に依存する)バージョンを許可します。

*、1.*、1.2.*はワイルドカードの必要条件の例です。

Requirement	Versions allowed
*	>=0.0.0
1.*	>=1.0.0 <2.0.0
1.2.*	>=1.2.0 <1.3.0

Inequality requirements

Inequality requirementsでは、依存するバージョンの範囲または正確なバージョンを手動で指定できます。

次に、不等式の要件の例をいくつか示します。

>= 1.2.0
> 1
< 2
!= 1.2.3

Multiple requirements

複数のバージョン要件は、例えば>=1.2, <1.5のように、コンマで区切ることもできます。

Exact requirements

パッケージの正確なバージョンを指定できます。

1.2.3は正確なバージョン指定の例です。

これは、このバージョンとこのバージョンのみをインストールするようにPoetryに指示します。他の依存関係が異なるバージョンを必要とする場合、ソルバーは最終的に失敗し、インストールまたは更新手順を中止します。

正確なバージョンは、PEP 440に従って==で指定することもできます。

==1.2.3はその一例です。

Using the `@` operator

poetry addで依存関係を追加する場合は、@演算子を使用できます。これは==構文と同様に理解されますが、pyproject.tomlで有効な任意の指定子を前に付けることもできます。例えば:

poetry add django@^4.0.0

上記は、pyproject.tomlの次のエントリに変換されます。

Django = "^4.0.0"

特別なキーワードlatestは@演算子によっても解釈されます。

poetry add django@latest

上記は、djangoの最新リリースが4.0.5であると仮定すると、pyproject.tomlの次のエントリに変換されます。

Django = "^4.0.5"

Extras

Extrasと@は期待通りに組み合わせることができます(package[extra]@version):

poetry add django[bcrypt]@^4.0.0

`git` dependencies

gitリポジトリにあるライブラリに依存するには、gitキーでリポジトリの場所を指定する必要があります。

[tool.poetry.dependencies]
requests = { git = "https://github.com/requests/requests.git" }

他の情報は何も指定していないので、Poetryはプロジェクトを構築するためにmainブランチの最新のコミットを使用することを想定しています。

gitキーとbranchキーを組み合わせて別のブランチを使用することができます。あるいは、revまたはtagを使用して、それぞれ特定のコミットハッシュまたはタグ付きrefに依存関係を固定します。次に例を示します。

[tool.poetry.dependencies]
# Get the latest revision on the branch named "next"
requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" }
# Get a revision by its commit hash
flask = { git = "https://github.com/pallets/flask.git", rev = "38eb5d3b" }
# Get a revision by its tag
numpy = { git = "https://github.com/numpy/numpy.git", tag = "v0.13.2" }

インストールするパッケージがVCSリポジトリのサブディレクトリにある場合は、pipが提供するものと同様に、subdirectoryオプションを使用できます。

[tool.poetry.dependencies]
# Install a package named `subdir_package` from a folder called `subdir` within the repository
subdir_package = { git = "https://github.com/myorg/mypackage_with_subdirs.git", subdirectory = "subdir" }

これに対応するadd呼び出しがあります。

poetry add "git+https://github.com/myorg/mypackage_with_subdirs.git#subdirectory=subdir"

プライベートリポジトリなどでSSH接続を使用するには、次の構文例を使用します。

[tool.poetry.dependencies]
requests = { git = "git@github.com:requests/requests.git" }

gitリポジトリでHTTP基本認証を使用するには、repository credentialsが設定される方法と同様の資格情報を設定できます。

poetry config repositories.git-org-project https://github.com/org/project.git
poetry config http-basic.git-org-project username token
poetry add git+https://github.com/org/project.git

Note

Poetry 1.2リリースでは、デフォルトのgitクライアントとしてDulwichが使用されています。

gitcredentialsが使用されている場合は、レガシーシステムのgitクライアント実装に戻ります。このフォールバックは将来のリリースで削除され、gitcredentialsヘルパーがネイティブにサポートされるようになります。

Poetry 1.2より前に動作していたデフォルト実装で問題が発生した場合は、シェルのサブプロセス呼び出しを使用して、システムgitクライアントの使用を明示的に設定することができます。

poetry config experimental.system-git-client true

ただし、そうすることで、システムgitクライアントの使用によって引き起こされた1.2より前のバージョンに存在していたバグが表面化することに注意してください。

`path` dependencies

ローカルディレクトリまたはファイルにあるライブラリに依存するには、pathプロパティを使用します。

[tool.poetry.dependencies]
# directory
my-package = { path = "../my-package/", develop = false }

# file
my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }

Note

poetry 1.1以前では、ディレクトリパスの依存関係はデフォルトで編集可能モードでインストールされていました。すべてのpoetryバージョンで動作が同じになるように、develop属性を明示的に設定する必要があります。

`url` dependencies

リモートアーカイブにあるライブラリに依存するには、urlプロパティを使用します。

[tool.poetry.dependencies]
# directory
my-package = { url = "https://example.com/my-package-0.1.0.tar.gz" }

これに対応するadd呼び出しがあります。

poetry add https://example.com/my-package-0.1.0.tar.gz

Dependency `extras`

ここに示すように、依存関係にPEP-508 Extrasを指定できます。

[tool.poetry.dependencies]
gunicorn = { version = "^20.1", extras = ["gevent"] }

Note

これは、依存関係に定義されたextraを有効にします。プロジェクト内のextraにオプションの依存関係を設定するには、extrasを参照してください。

`source` dependencies

alternate repositoryからのパッケージに依存するには、sourceプロパティを使用します。

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

[tool.poetry.dependencies]
my-cool-package = { version = "*", source = "foo" }

これに対応するadd呼び出しがあります。

poetry add my-cool-package --source foo

Note

この例では、fooが正しく設定されていることを想定しています。詳細については、using a private repositoryを参照してください。

Python restricted dependencies

特定のPythonバージョンに対してのみ依存関係をインストールするように指定することもできます。

[tool.poetry.dependencies]
tomli = { version = "^2.0.1", python = "<3.11" }

[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", python = "^3.2" }

Using environment markers

依存関係に対してより複雑なインストール条件が必要な場合、Poetryはmarkersプロパティを介してenvironment markersをサポートします。

[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", markers = "python_version <= '3.4' or sys_platform == 'win32'" }

Multiple constraints dependencies

ターゲットPythonのバージョンに応じて、依存関係のバージョン範囲が異なる場合があります。

バージョン1.9までのPython 3.6-3.7と互換性があり、バージョン2.0以降のPython 3.8+と互換性があるパッケージfooに依存しているとします。

次のように宣言します。

[tool.poetry.dependencies]
foo = [
    {version = "<=1.9", python = ">=3.6,<3.8"},
    {version = "^2.0", python = ">=3.8"}
]

Note

制約は(pythonのように)異なる要件を持たなければなりません。さもなければ、依存関係の解決時にエラーが発生します。

Combining git / url / path dependencies with source repositories

直接起点(git/url/path)依存関係は、相互に排他的なマーカーが使用されている場合でも、明示的にソースを指定しない依存関係の要件を満たすことができます。たとえば、次の例では、urlパッケージも2番目の要件の有効なソリューションになります。

foo = [
    { platform = "darwin", url = "https://example.com/example-1.0-py3-none-any.whl" },
    { platform = "linux", version = "^1.0" },
]

場合によっては、特定の条件(つまり、特定のプラットフォーム/アーキテクチャのPyPIでは利用できないコンパイルされたパッケージ)に対して直接の元の依存関係を使用し、他の場合にはソースリポジトリに頼ることもできます。この場合、別のsourceによって依存関係が満たされるように明示的に要求する必要があります。次に例を示します。

foo = [
    { platform = "darwin", url = "https://example.com/foo-1.0.0-py3-none-macosx_11_0_arm64.whl" },
    { platform = "linux", version = "^1.0", source = "pypi" },
]

Expanded dependency specification syntax

より複雑な依存性の指定の場合、非常に長く読みにくい行になることがあります。このような場合は、"インライン・テーブル"構文から"標準テーブル"構文に移行できます。

これが役立つ例を次に示します。

[tool.poetry.group.dev.dependencies]
black = {version = "19.10b0", allow-prereleases = true, python = "^3.7", markers = "platform_python_implementation == 'CPython'"}

1行として、これは消化すべきものがたくさんあります。これを少し簡単に操作するには、次のようにします。

[tool.poetry.group.dev.dependencies.black]
version = "19.10b0"
allow-prereleases = true
python = "^3.7"
markers = "platform_python_implementation == 'CPython'"

同じ情報がまだ存在し、最終的にはまったく同じ仕様が提供されます。それは単に複数の、少し読みやすい行に分割されています。

Dependency specification

Version constraints

Caret requirements

Tilde requirements

Wildcard requirements

Inequality requirements

Multiple requirements

Exact requirements

Using the @ operator

Extras

git dependencies

path dependencies

url dependencies

Dependency extras

source dependencies

Python restricted dependencies

Using environment markers

Multiple constraints dependencies

Combining git / url / path dependencies with source repositories

Expanded dependency specification syntax

Using the `@` operator

`git` dependencies

`path` dependencies

`url` dependencies

Dependency `extras`

`source` dependencies