Skip to content

Dependency configuration

Project dependenciesは、オプションのPEP 440 version specifiersを使用して、[PEP 440][]文字列で定義されます。

Version specifiers

バージョン指定子は、カンマで区切られた一連のバージョン句で構成されます。次に例を示します。:

[project]
...
dependencies = [
  "cryptography",
  "click>=7, <9, != 8.0.0",
  "python-dateutil==2.8.*",
  "numpy~=1.21.4",
]

カンマは論理AND演算子に相当します。つまり、候補バージョンは、指定子全体と一致するために、指定されたすべてのバージョン句と一致する必要があります。

Operators

Operators Function
~= Compatible release
== Version matching
!= Version exclusion
<=, >= Inclusive ordered comparison
<, > Exclusive ordered comparison
=== Arbitrary equality

Version matching

バージョンマッチング節には、バージョンマッチング演算子==とバージョン識別子が含まれます。

デフォルトでは、バージョン一致演算子は厳密な等価比較に基づいています。つまり、指定されたバージョンは要求されたバージョンとまったく同じである必要があります。

Clause Allowed versions
==1 1.0.0
==1.2 1.2.0

厳密な比較のかわりに、バージョン一致句のバージョン識別子に末尾の.*を追加して、接頭辞の一致を要求できます。これは、バージョン識別子が句に一致するかどうかを判断する際に、追加の末尾セグメントが無視されることを意味します。

Clause Allowed versions
~=1.2 >=1.2.0, <2.0.0
~=1.2.3 >=1.2.3, <1.3.0

Compatible release

互換リリース句は、互換リリース演算子~=とバージョン識別子で構成されます。指定したバージョンと互換性があると予想される任意の候補バージョンと一致します。

指定されたリリース識別子V.Nに対して、互換性のあるリリース句は、次の比較句のペアとほぼ同等です。:

>= V.N, == V.*

この演算子は、~=1のように単一セグメントのバージョン番号と一緒に使用することはできません。

Clause Allowed versions
~=1.2 >=1.2.0, <2.0.0
~=1.2.3 >=1.2.3, <1.3.0

Version exclusion

バージョン排他節には、バージョン排他演算子!=とバージョン識別子が含まれます。

使用できるバージョン識別子と比較の意味は、Version matching演算子と同じです。ただし、一致の意味は逆になります。

Ordered comparison

包括的な比較では、節のバージョン識別子の部分を使用できますが、排他的な比較では使用できません。たとえば、>=1.2ではバージョン1.2.0を使用できますが、>1.2では使用できません。

包含順序比較<=および>=とは異なり、排他順序比較<および>は、指定されたバージョンのプレリリース、ポストリリース、およびローカルバージョンを明確に除外します。

Arbitrary equality

強く推奨されるものではありませんが、任意の等価比較は、例えば===foobarのように、バージョンの意味を持たない単純な文字列マッチングを可能にします。

Environment markers

Environment markersを使用すると、特定の条件が満たされた場合にのみ依存関係をインストールできます。

たとえば、特定のPythonメジャーバージョンで利用可能な最新バージョンの「暗号化」をインストールする必要がある場合は、次のように定義できます。:

cryptography==3.3.2; python_version < "3"
cryptography>=35.0; python_version > "3"

あるいは、Windowsで実行しているときにPython 3でのみ必要な場合は、次のようにすることもできます。:

cryptography; python_version ~= "3.0" and platform_system == "Windows"

使用可能な環境マーカーは次のとおりです。

Marker Python equivalent Examples
os_name import os
os.name
  • posix
  • java
sys_platform import sys
sys.platform
  • linux
  • win32
  • darwin
platform_machine import platform
platform.machine()
  • x86_64
platform_python_implementation import platform
platform.python_implementation()
  • CPython
  • Jython
platform_release import platform
platform.release()
  • 1.8.0_51
  • 3.14.1-x86_64-linode39
platform_system import platform
platform.system()
  • Linux
  • Windows
  • Darwin
platform_version import platform
platform.version()
  • 10.0.19041
  • #1 SMP Fri Apr 2 22:23:49 UTC 2021
python_version import platform
'.'.join(platform.python_version_tuple()[:2])
  • 2.7
  • 3.10
python_full_version import platform
platform.python_version()
  • 2.7.18
  • 3.11.0b1
implementation_name import sys
sys.implementation.name
  • cpython
implementation_version See here
  • 2.7.18
  • 3.11.0b1

Features

extras構文を使用して、optional dependenciesのグループを選択してインストールできます。たとえば、fooという名前の依存関係が次のように定義されているとします。:

[project.optional-dependencies]
crypto = [
  "PyJWT",
  "cryptography",
]
fastjson = [
  "orjson",
]
cli = [
  "prompt-toolkit",
  "colorama; platform_system == 'Windows'",
]

cliとcryptoの機能は以下のように選択できます:

foo[cli,crypto]==1.*

機能はパッケージ名の直後、version specifiersの前に来ることに注意してください。

Self-referential

機能グループは、他の機能グループを自己参照的に拡張することができます。たとえば、awesome-projectというプロジェクトの場合、次のpyproject.tomlファイルのdev機能グループは、crypto機能グループのすべてとblackを選択します。:

[project]
name = "awesome-project"

[project.optional-dependencies]
crypto = [
  "PyJWT",
  "cryptography",
]
dev = [
  "awesome-project[crypto]",
  "black",
]

Direct references

通常のversion specifiersを使用してPyPIのようなインデックスからパッケージを取得する代わりに、明示的なURIを持つdirect referencesを使用して正確なソースを定義できます。

直接参照は、通常、パブリッシュされたプロジェクトの依存関係に使用されるのではなく、dependencies for an environmentを定義するために使用されます。

すべての直接参照型には、次のようにパッケージ名が接頭辞として付けられます。:

<NAME> @ <REFERENCE>

Version control systems

関連する実行ファイルがPATHで利用可能である限り、さまざまなバージョン管理システム(VCS)が[supported]されています(#supported-vcs)。

VCSダイレクト参照は、次のいずれかの形式を使用して定義されます。:

<NAME> @ <SCHEME>://<PATH>
<NAME> @ <SCHEME>://<PATH>@<REVISION>

Pythonパッケージがルートに配置されていない場合は、#subdirectory=<PATH>コンポーネントを追加して、Pythonパッケージへの相対パスを指定することもできます(例:#subdirectory=lib/foo)。

詳細については、thisを参照してください。

Supported VCS

Executable Schemes Revisions Example
git
  • git+file
  • git+https
  • git+ssh
  • git+http ⚠
  • git+git ⚠
  • git ⚠
  • Commit hash
  • Tag name
  • Branch name
 proj @ git+https://github.com/org/proj.git@v1
Executable Schemes Revisions Example
hg
  • hg+file
  • hg+https
  • hg+ssh
  • hg+http ⚠
  • hg+static-http ⚠
  • Revision hash
  • Revision number
  • Tag name
  • Branch name
 proj @ hg+file:///path/to/proj@v1
Executable Schemes Revisions Example
svn
  • svn+https
  • svn+ssh
  • svn+http ⚠
  • svn+svn ⚠
  • svn ⚠
  • Revision number
 proj @ svn+file:///path/to/proj
Executable Schemes Revisions Example
bzr
  • bzr+https
  • bzr+ssh
  • bzr+sftp
  • bzr+lp
  • bzr+http ⚠
  • bzr+ftp ⚠
  • Revision number
  • Tag name
 proj @ bzr+lp:proj@v1

Local

次の形式のfileスキームを使用して、ローカルパッケージをインストールできます。:

<NAME> @ file://<HOST>/<PATH>

<HOST>はWindowsシステムでのみ使用され、ネットワーク共有を参照できます。省略した場合はlocalhostと見なされ、3番目のスラッシュも存在する必要があります。

<PATH>は、ソースアーカイブ、ホイール、またはPythonパッケージを含むディレクトリを参照できます。

Type Unix Windows
Source archive proj @ file:///path/to/pkg.tar.gz proj @ file:///c:/path/to/pkg.tar.gz
Wheel proj @ file:///path/to/pkg.whl proj @ file:///c:/path/to/pkg.whl
Directory proj @ file:///path/to/pkg proj @ file:///c:/path/to/pkg

Tip

また、context formattingを使用して、すべてのプラットフォームでプロジェクトのルートディレクトリに対する相対パスを指定することもできます。

<NAME> @ {root:uri}/pkg_inside_project
<NAME> @ {root:parent:uri}/pkg_alongside_project

Remote

次のURLを参照するだけで、ソースアーカイブとホイールをインストールできます。:

black @ https://github.com/psf/black/archive/refs/tags/21.10b0.zip
pytorch @ https://download.pytorch.org/whl/cu102/torch-1.10.0%2Bcu102-cp39-cp39-linux_x86_64.whl

期待されるハッシュ値を指定するには、#<HASH_ALGORITHM>=<EXPECTED_HASH>要素を追加します。:

requests @ https://github.com/psf/requests/archive/refs/tags/v2.26.0.zip#sha256=eb729a757f01c10546ebd179ae2aec852dd0d7f8ada2328ccf4558909d859985

ハッシュが予想されるハッシュと異なる場合、インストールは失敗します。

ハッシュには、標準ライブラリのhashlib moduleの最新バージョンによって無条件に提供されるハッシュのみを使用することをお勧めします。Python 3.10では、このリストは次のように構成されています。:

  • md5
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512
  • blake2b
  • blake2s

Complex syntax

次の例では、featuresとenvironment markersを使用しています。:

pkg[feature1,feature2] @ <REFERENCE> ; python_version < "3.7"

セミコロンの前にはスペースが必要です。