相依性規範
相依性說明 #
專案的相依性可用各種形式說明，視相依性的類型和安裝它時可能需要使用的選擇性限制而定。
版本限制 #
脫字符號需求 #
脫字符號需求允許對指定版本進行 SemVer 相容性更新。如果新版本號碼不會修改主版本、次要版本、修正版本群組中最左邊的非零數字，則允許更新。例如，如果我們之前執行 poetry add requests@^2.13.0 並且要更新程式庫並執行 poetry update requests，如果 2.14.0 版本可用，Poetry 會將我們更新到該版本，但不會將我們更新到 3.0.0。如果我們將版本字串指定為 ^0.1.13，Poetry 將更新為 0.1.14，但不會更新為 0.2.0。0.0.x 不會與任何其他版本相容。
以下是脫字符號需求的幾個範例，以及允許使用的版本
| 需求 | 允許使用的版本 |
|---|---|
| ^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 |
波浪符號需求 #
波浪线需求指定了一个具有某些更新能力的最低版本。如果你指定了一个主版本、次版本和补丁版本或仅指定了一个主版本和次版本，则只允许补丁级别的更改。如果你仅指定了一个主版本，则允许次版本和补丁级别的更改。
~1.2.3 是波浪线需求的一个示例。
| 需求 | 允許使用的版本 |
|---|---|
| ~1.2.3 | >=1.2.3 <1.3.0 |
| ~1.2 | >=1.2.0 <1.3.0 |
| ~1 | >=1.0.0 <2.0.0 |
通配符需求 #
通配符需求允许在放置通配符的位置使用最新（依赖依赖项）版本。
*、1.* 和 1.2.* 是通配符需求的示例。
| 需求 | 允許使用的版本 |
|---|---|
| * | >=0.0.0 |
| 1.* | >=1.0.0 <2.0.0 |
| 1.2.* | >=1.2.0 <1.3.0 |
不等式需求 #
不等式需求允许手动指定版本范围或依赖的确切版本。
下面是一些不等式需求的示例
>= 1.2.0
> 1
< 2
!= 1.2.3
多重需求 #
多个版本需求也可以用逗号分隔，例如 >= 1.2, < 1.5。
精确需求 #
你可以指定程序包的确切版本。
1.2.3 是精确版本规范的一个示例。
这将告诉 Poetry 仅安装此版本。如果其他依赖项需要一个不同的版本，求解器最终会失败并终止任何安装或更新过程。
根据 PEP 440，精确版本也可以用 == 指定。
==1.2.3 就是一个例子。
使用 @ 运算符 #
通过 poetry add 添加依赖项时，可以使用 @ 运算符。这与 == 语法类似，但还允许为 pyproject.toml 中有效的任何说明符添加前缀。例如
poetry add django@^4.0.0
上面将转换为 pyproject.toml 中的以下条目
Django = "^4.0.0"
@ 运算符也可以识别特殊关键字 latest
poetry add django@latest
上面将转换为 pyproject.toml 中的以下条目，假定 django 的最新版本是 4.0.5
Django = "^4.0.5"
附加组件 #
附加组件和 @ 可以按预期组合（package[extra]@version）
poetry add django[bcrypt]@^4.0.0
git 依赖项 #
要依赖存储在 git 存储库中的库，你需要指定的最少信息是存储库的位置和 git 键
[tool.poetry.dependencies]
requests = { git = "https://github.com/requests/requests.git" }
由于我们没有指定任何其他信息，因此 Poetry 假定我们打算使用 main 分支上的最新提交来构建我们的项目。
你可以將 git 鍵與 branch 鍵結合使用，以使用另一個分支。或者，使用 rev 或 tag 分別將相依項固定到特定提交雜湊或標記的參考。例如
[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 存放庫子目錄的情況下，你可以使用 subdirectory 選項，類似於 pip 提供的選項
[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 基本驗證，你可以設定認證，類似於 存放庫認證 的設定方式。
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
對於 Poetry 1.2 版本，使用的預設 git 用戶端為 Dulwich。
在使用 gitcredentials 的情況下，我們會退回至舊版系統 git 用戶端實作。此退回機制將在未來版本移除，屆時將能原生支援 gitcredentials 輔助程式。
在遇到使用 Poetry 1.2 之前運作正常的預設實作問題時，你可能會希望透過 shell 子程序呼叫明顯設定使用系統 git 用戶端。
poetry config experimental.system-git-client true
但請記住，這麼做會顯示出 1.2 之前的版本中存在且因使用系統 git 用戶端而造成的錯誤。
路徑 相依項 #
若要依賴位於本機目錄或檔案的函式庫，你可以使用 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" }
develop 屬性，以確保所有 poetry 版本的行為相同。網址 相依項 #
若要依賴位於遠端封存的函式庫，你可以使用 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
相依項 extra #
你可以為相依項指定 PEP-508 Extra，如下所示。
[tool.poetry.dependencies]
gunicorn = { version = "^20.1", extras = ["gevent"] }
extra。來源 相依項 #
若要依賴 其他存放庫 的套件，你可以使用 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
foo 已正確設定。有關更多資訊，請參閱 使用私有存放庫。受限的 Python 相依項 #
你也可以指定僅針對特定 Python 版本安裝相依項
[tool.poetry.dependencies]
tomli = { version = "^2.0.1", python = "<3.11" }
[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", python = "^3.2" }
使用環境標記 #
如果您需要針對相依性設定較為複雜的安裝條件，Poetry 會透過 markers 屬性支援 環境標記
[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", markers = "python_version <= '3.4' or sys_platform == 'win32'" }
多重約束相依性 #
有時，您的其中一個相依性可能會依目標 Python 版本而有不同的版本範圍。
假設您有一個相依於封包 foo 的相依性，而這個相依性僅與 Python 3.6-3.7 相容至版本 1.9，並與 Python 3.8+ 相容至版本 2.0：您可如以下範例所示宣告該相依性
[tool.poetry.dependencies]
foo = [
{version = "<=1.9", python = ">=3.6,<3.8"},
{version = "^2.0", python = ">=3.8"}
]
python)；否則，在解析相依性時會導致錯誤。將 git / url / 路徑相依性與來源存放庫結合 #
直接來源 (git/ url/ path) 相依性可以滿足未明確指定來源的相依性需求，即使使用了互斥標記。例如，在以下範例中，url 封包對第二個需求也可以是一個有效的解決方案
foo = [
{ platform = "darwin", url = "https://example.com/example-1.0-py3-none-any.whl" },
{ platform = "linux", version = "^1.0" },
]
有時您可能希望針對特定條件使用直接來源相依性 (例如，PyPI 上在特定平台或架構中不可用的已編譯封包)，但在其他情況下會採用來源存放庫。在這情況下，您應明確要求您的相依性滿足於其他 來源。例如
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" },
]
擴充的相依性規格語法 #
對於較為複雜的相依性規格，您可能會發現最後會產生非常長且難以閱讀的行。在這些情況下，您可以從使用「內嵌表格」語法轉換為「標準表格」語法。
下列情況適合使用此語法
[tool.poetry.group.dev.dependencies]
black = {version = "19.10b0", allow-prereleases = true, python = "^3.7", markers = "platform_python_implementation == 'CPython'"}
作為一行陳述，這段範例資訊量相當多。若要讓此範例更容易操作，您可以進行以下步驟
[tool.poetry.group.dev.dependencies.black]
version = "19.10b0"
allow-prereleases = true
python = "^3.7"
markers = "platform_python_implementation == 'CPython'"
這段資訊仍和之前相同，最終提供完全相同的規格。它僅拆分為多行，稍微方便閱讀。