仓库

仓库 #

Poetry 支持使用 PyPI 和私有仓库来发现包以及发布你的项目。

默认情况下，Poetry 配置为使用 PyPI 仓库，用于包安装和发布。

因此，当你向你的项目添加依赖项时，Poetry 会假设它们在 PyPI 上可用。

这代表了大多数情况，对于大多数用户来说可能已经足够了。

私有仓库示例 #

从私有包源安装 #

默认情况下，Poetry 从 PyPI 发现和安装包。但是，你想为你的项目安装一个 简单 API 仓库 的依赖项？让我们来做吧。

首先，配置 包源 作为你的项目的 补充（或 显式）包源。

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

然后，假设仓库需要身份验证，为它配置凭据。

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

poetry config http-basic.foo <username>

完成此操作后，你就可以从该源向你的项目添加依赖项了。

poetry add --source foo private-package

发布到私有仓库 #

太好了，现在剩下的就是发布你的包了。假设你想私下与你的团队共享它，你可以配置你的 可发布仓库 的 上传 API 端点。

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

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

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

包源 #

默认情况下，Poetry 配置为使用 Python 生态系统的规范包索引 PyPI。

项目配置 #

这些包源可以使用你的项目的 source 命令进行管理。

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

这将在你的 pyproject.toml 文件中生成以下配置片段。

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

如果 priority 未定义，则该源被视为优先于 PyPI、次要、补充和显式源的主要源。

包源按以下顺序考虑

1. 默认源（已弃用），
2. 主要源,
3. 隐式 PyPI（除非被其他 主要源、默认源 或显式配置禁用），
4. 次要源（已弃用），
5. 补充源.

显式源 仅考虑明确 指示其源 的包。

在每个优先级类别中，包源按其在 pyproject.toml 中出现的顺序考虑。

poetry source add --priority=primary PyPI

默认包源 (已弃用) #

在 1.8.0 中弃用

默认情况下，如果你没有配置任何主源，Poetry 将配置 PyPI 作为你项目的包源。你可以更改此行为，并仅从配置的包源中查找包，方法是添加至少一个主源（推荐）或一个带有 priority = "default" 的单个源（已弃用）。

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

主包源 #

所有主包源都将被搜索，以查找每个没有 源约束 的依赖项。如果你配置了至少一个主源，则隐式 PyPI 源将被禁用。

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

没有优先级的源也被认为是主源。

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

poetry source add --priority=primary PyPI

[[tool.poetry.source]]
name = "pypi"
priority = "primary"

辅助包源 (已弃用) #

在 1.5.0 中弃用

如果包源被配置为辅助源，这意味着在选择与你的默认和主包源中也存在的兼容包分发时，这些源将被赋予较低的优先级。如果包源应该只在更高优先级的存储库没有返回结果时才被搜索，请考虑使用 补充源。

你可以在你的包源配置中使用 priority = "secondary" 将包源配置为辅助源。

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

可以有多个辅助包源。

补充包源 #

在 1.5.0 中引入

配置为补充源的包源只有在没有其他（更高优先级）源产生兼容的包分发时才会被搜索。如果源的响应时间很长，并且从该源获取的包分发相对较少，这将特别方便。

你可以在你的包源配置中使用 priority = "supplemental" 将包源配置为补充源。

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

可以有多个补充包源。

显式包源 #

在 1.5.0 中引入

如果包源被配置为显式源，则只有在包配置 明确指示 应该在该包源上找到它时，才会搜索这些源。

你可以在你的包源配置中使用 priority = "explicit" 将包源配置为显式源。

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

可以有多个显式包源。

poetry source add --priority=explicit pytorch-gpu-src https://download.pytorch.org/whl/cu118
poetry add --source pytorch-gpu-src torch torchvision torchaudio

包源约束 #

在包查找过程中，将搜索所有包源（包括辅助源和可能存在的补充源）。这些网络请求将针对所有源发生，无论包是否在一个或多个源中找到。

为了将特定包的搜索限制在特定的包存储库中，你可以显式指定源。

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 = ...

poetry add --source internal-pypi package-B@*

poetry add --group explicit --source internal-pypi package-B@*

支持的包源 #

Python 包索引 (PyPI) #

Poetry 通过其 JSON API 与 PyPI 交互。这用于检索请求的包的版本、元数据、文件等。

如果你想显式地从 PyPI 中选择一个包，你可以使用 --source 选项以及 add 命令，如下所示。

poetry add --source pypi httpx@^0.22.0

这将在你的 pyproject.toml 文件中生成以下配置片段。

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

简单 API 存储库 #

Poetry 可以从实现简单存储库 API 的公共或私有自定义存储库中获取和安装包依赖项，如 PEP 503 中所述。

这些包源可以通过以下命令在你的项目中进行配置。

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

除了 PEP 503 之外，Poetry 还可以处理实现 PEP 658（在 1.2.0 中引入）的简单 API 存储库。这有助于减少从这些源获取的包的依赖项解析时间，因为 Poetry 可以避免必须下载每个候选分发，以确定相关的元数据。

单页链接源 #

在 1.2.0 中引入

一些项目选择通过部分遵循 PEP 503 中的包页结构的单页链接源发布其二进制分发。

这些包源可以通过以下命令在你的项目中进行配置。

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

可发布的存储库 #

与 包源 不同，Poetry 将你发布包的存储库视为用户特定配置，而不是项目特定配置。目前，Poetry 仅在发布你的项目时支持 传统上传 API。

这些是使用 config 命令在 repositories 键下配置的。

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

配置凭据 #

如果你想为特定存储库存储你的凭据，你可以轻松地做到这一点

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

如果你没有指定密码，系统将提示你输入密码。

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

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

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

您也可以在使用 publish 命令时，使用 --username 和 --password 选项指定用户名和密码。

如果系统密钥环可用且受支持，密码将存储到密钥环中并从密钥环中检索。在上面的示例中，凭据将使用名称 poetry-repository-pypi 存储。如果访问密钥环失败或不受支持，这将回退到将密码写入 auth.toml 文件以及用户名。

密钥环支持使用 keyring 库 启用。有关支持的后端的更多信息，请参阅 库文档。

如果您不想使用密钥环，您可以告诉 Poetry 禁用它并将凭据存储在纯文本配置文件中。

poetry config keyring.enabled false

或者，您可以使用环境变量来提供凭据。

export POETRY_PYPI_TOKEN_FOO=my-token
export POETRY_HTTP_BASIC_FOO_USERNAME=<username>
export POETRY_HTTP_BASIC_FOO_PASSWORD=<password>

其中 FOO 是存储库名称的大写形式（例如 PYPI）。有关如何使用环境变量配置 Poetry 的更多信息，请参阅 使用环境变量。

如果您的密码以连字符开头（例如，在 CI 环境中随机生成的令牌），它将被解析为命令行选项而不是密码。您可以通过添加双连字符来防止这种情况，以防止任何后续参数被解析为选项。

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

证书 #

自定义证书颁发机构和双向 TLS 身份验证 #

Poetry 支持由自定义证书颁发机构保护的存储库，以及那些需要基于证书的客户端身份验证的存储库。以下将配置“foo”存储库以使用自定义证书颁发机构验证存储库的证书，并使用客户端证书（请注意，这些配置变量不需要同时设置）。

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

poetry config certificates.foo.cert false

缓存 #

Poetry 为软件包源使用多个缓存，以改善用户体验并避免重复的网络请求。

第一级缓存是基于 Cache-Control 标头的缓存，用于几乎所有 HTTP 请求。

此外，每个 HTTP 支持的软件包源都会缓存与软件包关联的元数据，一旦它被获取或生成。此外，下载的文件（软件包分发）也会被缓存。

调试问题 #

如果您遇到软件包源问题，您可以采取的最简单的步骤之一是在使用 --no-cache 标志的情况下重新运行您的命令。

poetry --no-cache add pycowsay

如果这解决了您的问题，您可以考虑使用 cache 命令清除您的缓存。

或者，您也可以考虑启用非常详细的日志记录 -vvv 以及 --no-cache，以查看日志中正在进行的网络请求。