首页 Poetry logo

依赖规范

依赖规范 #

项目的依赖可以以多种形式指定，这取决于依赖的类型以及可能需要的可选约束才能安装它。

版本约束 #

插入符号要求 #

插入符号要求允许对指定版本进行SemVer 兼容的更新。如果新版本号没有修改主版本、次版本、补丁分组中最左边的非零数字，则允许更新。例如，如果我们之前运行了 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 不被认为与任何其他版本兼容。

以下是插入符号要求及其允许版本的更多示例

要求 允许的版本
^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"

Extras #

Extras 和 @ 可以按预期组合（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 依赖 #

要依赖于位于本地目录或文件中的库，您可以使用 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" }
注意
在 poetry 1.1 之前，目录路径依赖项默认情况下以可编辑模式安装。您应该显式设置 develop 属性，以确保所有 poetry 版本的行为一致。

url 依赖项 #

要依赖位于远程存档的库，可以使用 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

依赖项 extras #

您可以为依赖项指定 PEP-508 Extras，如下所示。

[tool.poetry.dependencies]
gunicorn = { version = "^20.1", extras = ["gevent"] }
注意
这些激活为依赖项定义的额外内容，要为项目中的额外内容配置可选依赖项，请参考 extras。

source 依赖项 #

要依赖来自 备用存储库 的包，可以使用 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 / path 依赖项与源存储库结合使用 #

直接来源 (git/ url/ path) 依赖项可以满足没有显式指定来源的依赖项的要求，即使使用互斥标记也是如此。例如，在以下示例中，url 包也将是第二个要求的有效解决方案

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" },
]

扩展的依赖项规范语法 #

在更复杂的依赖项规范的情况下，您可能会发现最终得到非常长且难以阅读的行。在这种情况下，您可以从使用“内联表格”语法转换为“标准表格”语法。

以下是一个可能有用示例

[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'"

相同的信息仍然存在，最终提供完全相同的规范。它只是被拆分为多行，更易读。