本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # CodeArtifact 与 Python 一起使用 这些主题描述了如何使用 `pip` Python 包管理器以及 `twine` Python 包发布实用工具 CodeArtifact。 **Topics** + [配置并使用 pip CodeArtifact](python-configure-pip.md) + [配置和使用麻线 CodeArtifact](python-configure-twine.md) + [Python 程序包名称规范化](python-name-normalization.md) + [Python 兼容性](python-compatibility.md) + [从上游和外部连接请求 Python 程序包](python-upstream-external-connections-request.md) # 配置并使用 pip CodeArtifact [pip](https://pypi.org/project/pip/) 是 Python 程序包的程序包安装程序。要使用 pip 从 CodeArtifact 仓库中安装 Python 软件包，必须先使用存储 CodeArtifact 库信息和凭据配置 pip 客户端。 pip 只能用于安装 Python 程序包。要发布 Python 程序包，您可以使用 [twine](https://pypi.org/project/twine/)。有关更多信息，请参阅 [配置和使用麻线 CodeArtifact](python-configure-twine.md)。 ## 使用 `login` 命令配置 pip 首先，配置您的 AWS 凭证以与一起使用 AWS CLI，如中所述[开始使用 CodeArtifact](getting-started.md)。然后，使用 CodeArtifact`login`命令获取凭据并使用它们`pip`进行配置。 **注意** 如果您要访问您拥有的域中的存储库，则无需包括 `--domain-owner`。有关更多信息，请参阅 [跨账户域](domain-overview.md#domain-overview-cross-account)。 要配置 pip，请运行以下命令。 ``` aws codeartifact login --tool pip --domain my_domain --domain-owner 111122223333 --repository my_repo ``` `login` CodeArtifact 使用您的 AWS 凭证获取授权令牌。该`login`命令将配置`pip`为与一起使用， CodeArtifact 通过编辑`~/.config/pip/pip.conf``index-url`将其设置为`--repository`选项指定的存储库。 调用 `login` 后的默认授权期为 12 小时，且必须调用 `login` 来定期刷新令牌。有关使用 `login` 命令创建的授权令牌的更多信息，请参阅 [使用 `login` 命令创建的令牌](tokens-authentication.md#auth-token-login)。 ## 不使用 login 命令配置 pip 如果您无法使用 `login` 命令来配置 `pip`，则可以使用 `pip config`。 1. 使用 AWS CLI 获取新的授权令牌。 **注意** 如果您要访问您拥有的域中的存储库，则无需包括 `--domain-owner`。有关更多信息，请参阅 [跨账户域](domain-overview.md#domain-overview-cross-account)。 ``` CODEARTIFACT_AUTH_TOKEN=`aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --query authorizationToken --output text` ``` 1. `pip config`用于设置 CodeArtifact 注册表 URL 和凭据。以下命令将仅更新当前的环境配置文件。要更新系统范围的配置文件，请将 `site` 替换为 `global`。 ``` pip config set site.index-url https://aws:$CODEARTIFACT_AUTH_TOKEN@my_domain-111122223333.d.codeartifact.region.amazonaws.com/pypi/my_repo/simple/ ``` **注意** 要使用双堆栈端点，请使用 `codeartifact.region.on.aws` 端点。 **重要** 注册 URL 必须以正斜杠 (/) 结尾。否则，您无法连接到存储库。 **示例 pip 配置文件** 以下是设置 CodeArtifact 注册表 URL 和凭据后的`pip.conf`文件示例。 ``` [global] index-url = https://aws:eyJ2ZX...@my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/pypi/my_repo/simple/ ``` ## 运行 pip 要运行`pip`命令，必须`pip`使用进行配置 CodeArtifact。有关更多信息，请参阅以下文档。 1. 按照[使用进行设置 AWS CodeArtifact](get-set-up-for-codeartifact.md)部分中的步骤配置您的 AWS 账户、工具和权限。 1. 按照 [配置和使用麻线 CodeArtifact](python-configure-twine.md) 中的步骤配置 `twine`。 假设您的存储库或其中一个上游存储库中存在程序包，则可以使用 `pip install` 来安装。例如，使用以下命令来安装 `requests` 程序包。 ``` pip install requests ``` 使用该`-i`选项暂时恢复为从 [https://pypi.org](https://pypi.org) 安装软件包，而不是从存储 CodeArtifact 库安装软件包。 ``` pip install -i https://pypi.org/simple requests ``` # 配置和使用麻线 CodeArtifact [twine](https://pypi.org/project/twine/) 是一款适用于 Python 程序包的程序包发布实用程序。要使用 twine 将 Python 包发布到 CodeArtifact 仓库，必须先使用仓 CodeArtifact 库信息和凭据配置 twine。 twine 只能用于发布 Python 程序包。要安装 Python 程序包，您可以使用 [pip](https://pypi.org/project/pip/)。有关更多信息，请参阅 [配置并使用 pip CodeArtifact](python-configure-pip.md)。 ## 使用 `login` 命令配置 twine 首先，配置您的 AWS 凭证以与一起使用 AWS CLI，如中所述[开始使用 CodeArtifact](getting-started.md)。然后，使用 CodeArtifact`login`命令获取凭据并使用它们配置 twine。 **注意** 如果您要访问您拥有的域中的存储库，则无需包括 `--domain-owner`。有关更多信息，请参阅 [跨账户域](domain-overview.md#domain-overview-cross-account)。 要配置 twine，请运行以下命令。 ``` aws codeartifact login --tool twine --domain my_domain --domain-owner 111122223333 --repository my_repo ``` `login` CodeArtifact 使用您的 AWS 凭证获取授权令牌。该`login`命令将 twine 配置为 CodeArtifact 通过编辑`~/.pypirc`添加`--repository`选项指定的带有凭据的存储库来使用。 调用 `login` 后的默认授权期为 12 小时，且必须调用 `login` 来定期刷新令牌。有关使用 `login` 命令创建的授权令牌的更多信息，请参阅 [使用 `login` 命令创建的令牌](tokens-authentication.md#auth-token-login)。 ## 不使用 `login` 命令配置 twine 如果无法使用 `login` 命令来配置 twine，则可以使用 `~/.pypirc` 文件或环境变量。要使用 `~/.pypirc` 文件，请在文件添加以下条目。密码必须是 `get-authorization-token` API 获取的身份验证令牌。 ``` [distutils] index-servers = codeartifact [codeartifact] repository = https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/pypi/my_repo/ password = auth-token username = aws ``` **注意** 要使用双堆栈端点，请使用 `codeartifact.region.on.aws` 端点。 要使用环境变量，请执行以下操作： **注意** 如果您要访问您拥有的域中的存储库，则无需包括 `--domain-owner`。有关更多信息，请参阅 [跨账户域](domain-overview.md#domain-overview-cross-account)。 ``` export TWINE_USERNAME=aws export TWINE_PASSWORD=`aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --query authorizationToken --output text` export TWINE_REPOSITORY_URL=`aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format pypi --query repositoryEndpoint --output text` ``` ## 运行 twine 在使用 twine 发布 Python 包资源之前，必须先配置 CodeArtifact 权限和资源。 1. 按照[使用进行设置 AWS CodeArtifact](get-set-up-for-codeartifact.md)部分中的步骤配置您的 AWS 账户、工具和权限。 1. 按照 [使用 `login` 命令配置 twine](#python-configure-twine-login) 或 [不使用 `login` 命令配置 twine](#python-configure-twine-without-login) 中的步骤配置 twine。 配置 twine 之后，就可以运行 `twine` 命令。使用以下命令来发布 Python 程序包资产。 ``` twine upload --repository codeartifact mypackage-1.0.tgz ``` 有关如何构建和打包 Python 应用程序的信息，请参阅 Python 打包权威机构网站上的[生成分发存档](https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives)。 # Python 程序包名称规范化 CodeArtifact 在存储软件包名称之前对其进行标准化，这意味着中的软件包名称 CodeArtifact 可能与发布软件包时提供的名称不同。 对于 Python 程序包，在执行规范化时，程序包名称转为小写，所有 `.`、`-` 和 `_` 字符都替换为单个 `-` 字符。因此，程序包名称 `pigeon_cli` 和 `pigeon.cli` 会规范化并存储为 `pigeon-cli`。pip 和 twine 可以使用非标准化名称，但必须在 CLI 或 AP CodeArtifact I 请求（例如`list-package-versions`）和中使用标准化名称。 ARNs有关 Python 程序包名称规范化的更多信息，请参阅 Python 文档中的 [PEP 503](https://www.python.org/dev/peps/pep-0503/#normalized-names)。 # Python 兼容性 CodeArtifact 不支持 PyPI `XML-RPC` 或`JSON` APIs。 CodeArtifact 支持 PyPI `Legacy` APIs，但 `simple` API 除外。虽然 CodeArtifact 不支持 `/simple/` API 端点，但它支持`/simple//`终端节点。 有关更多信息，请参阅 Python 打包管理机构 GitHub存储库中的以下内容。 + [XML-RPC API](https://github.com/pypi/warehouse/blob/main/docs/dev/api-reference/xml-rpc.rst) + [JSON API](https://github.com/pypi/warehouse/blob/main/docs/dev/api-reference/json.rst) + [Legacy API](https://github.com/pypi/warehouse/blob/main/docs/dev/api-reference/legacy.rst) ## pip 命令支持 以下各节总结了 CodeArtifact 存储库支持的 pip 命令以及不支持的特定命令。 **Topics** + [与存储库进行交互的受支持命令](#supported-pip-commands-that-interact-with-a-repository) + [支持的客户端命令](#supported-pip-client-side-commands) ### 与存储库进行交互的受支持命令 此部分列出了 `pip` 命令，其中 `pip` 客户端向其配置的注册表发出一个或多个请求。这些命令已经过验证，在针对 CodeArtifact 存储库调用时可以正常运行。 **** | 命令 | 说明 | | --- | --- | | [install](https://pip.pypa.io/en/stable/reference/pip_install/) | 安装程序包。 | | [download](https://pip.pypa.io/en/stable/reference/pip_download/) | 下载程序包。 | CodeArtifact 不实现`pip search`。如果您配置`pip`了 CodeArtifact 存储库，则运行`pip search`将搜索并显示来自 [PyP](https://pypi.org/) I 的包。 ### 支持的客户端命令 这些命令不需要与存储库进行任何直接交互，因此 CodeArtifact 无需执行任何操作即可支持它们。 **** | 命令 | 说明 | | --- | --- | | [uninstall](https://pip.pypa.io/en/stable/reference/pip_uninstall/) | 卸载程序包。 | | [freeze](https://pip.pypa.io/en/stable/reference/pip_freeze/) | 按要求格式输出已安装的程序包。 | | [list](https://pip.pypa.io/en/stable/reference/pip_list/) | 列出已安装程序包。 | | [show](https://pip.pypa.io/en/stable/reference/pip_show/) | 显示有关已安装程序包的信息。 | | [check](https://pip.pypa.io/en/stable/reference/pip_check/) | 验证已安装的程序包是否具有兼容的依赖项。 | | [config](https://pip.pypa.io/en/stable/reference/pip_config/) | 管理本地和全局配置。 | | [wheel](https://pip.pypa.io/en/stable/reference/pip_wheel/) | 根据您的要求构建 wheel。 | | [hash](https://pip.pypa.io/en/stable/reference/pip_hash/) | 计算程序包存档的哈希值。 | | [completion](https://pip.pypa.io/en/stable/user_guide/#command-completion) | 协助完成命令。 | | [debug](https://pip.pypa.io/en/stable/reference/pip_debug/) | 显示对调试有用的信息。 | | help | 显示命令的帮助。 | # 从上游和外部连接请求 Python 程序包 从 [pypi.org](https://pypi.org/) 导入 Python 程序包版本时，CodeArtifact 会导入该程序包版本中的所有资产。虽然大多数 Python 程序包都只包含少量资产，但有些程序包包含 100 多个资产，通常用于支持多种硬件架构和 Python 解释器。 对于现有程序包版本，将新资产发布到 pypi.org 是一种常见的做法。例如，在发布新版本的 Python 时，一些项目会发布新资产。使用 `pip install` 从 CodeArtifact 安装 Python 程序包时，保留在 CodeArtifact 存储库中的程序包版本会更新，以反映来自 pypi.org 的最新资产集。 同样，如果上游 CodeArtifact 存储库中的某个程序包版本有新的可用资产，而这些资产不存在于当前 CodeArtifact 存储库中，则它们将在运行 `pip install` 时保留在当前存储库中。 ## 已撤销的程序包版本 pypi.org 中的某些程序包版本标记为*已撤销*，这会向程序包安装程序（例如 pip）表明，除非该版本是唯一与版本说明符匹配的版本（使用 `==` 或 `===`），否则不应安装该版本。有关更多信息，请参阅 [PEP\$1592](https://peps.python.org/pep-0592/)。 如果 CodeArtifact 中的程序包版本最初是从外部连接提取到 [pypi.org](https://pypi.org/)，那么当您从 CodeArtifact 存储库安装程序包版本时，CodeArtifact 会确保从 pypi.org 提取已更新的程序包版本撤销元数据。 ### 如何知道某个程序包版本是否已撤销 要检查某个程序包版本是否已在 CodeArtifact 中撤销，您可以尝试使用 `pip install packageName===packageVersion` 来安装。如果程序包版本已撤销，您会收到一条与以下内容类似的警告消息： ``` WARNING: The candidate selected for download or install is a yanked version ``` 要查看程序包版本是否在 [pypi.org](https://pypi.org/) 中撤销，您可以访问该程序包版本的 pypi.org 列表，网址为 `https://pypi.org/project/packageName/packageVersion/`。 ### 对私有程序包设置撤销状态 CodeArtifact 不支持为直接发布到 CodeArtifact 存储库的程序包设置撤销元数据。 ## 为什么 CodeArtifact 未提取程序包版本的最新撤销元数据或资产？ 通常，CodeArtifact 会确保在从 CodeArtifact 存储库提取 Python 程序包版本时，撤销元数据是最新的，在 [pypi.org](https://pypi.org/) 上具有最新值。此外，程序包版本中的资产列表还会根据 pypi.org 和任何上游 CodeArtifact 存储库中的最新设置进行更新。无论您是第一次安装程序包版本且 CodeArtifact 将其从 pypi.org 导入到您的 CodeArtifact 存储库，还是之前已安装该程序包，都是如此。但在某些情况下，程序包管理器客户端（例如 pip）不会从 pypi.org 或上游存储库提取最新的撤销元数据。相反，CodeArtifact 将返回已存储在存储库中的数据。本节说明了发生这种情况的三种方式： **上游配置：**如果使用 [disassociate-external-connection](external-connection.md#removing-an-external-connection) 从存储库或其上游移除与 pypi.org 的外部连接，则不再从 pypi.org 刷新撤销元数据。同样，如果您移除上游存储库，则已移除的存储库中和已移除存储库上游的资产将不再可供当前存储库使用。如果您使用 CodeArtifact [程序包来源控制](package-origin-controls.md)来阻止提取特定程序包的新版本，则情况也是如此，设置 `upstream=BLOCK` 会阻止刷新撤销元数据。 **程序包版本状态：**如果您将程序包版本的状态设置为除 `Published` 或 `Unlisted` 之外的任何其它状态，则不会刷新程序包版本的撤销元数据和资产。同样，如果您正在提取特定的程序包版本（例如 `torch 2.0.1`），而上游存储库中存在相同的程序包版本，但状态不是 `Published` 或 `Unlisted`，这也将阻止撤销元数据和资产从上游存储库传播到当前存储库。这是因为其它程序包版本状态表明这些版本不打算再在任何存储库中使用。 **直接发布：**如果您将特定的程序包版本直接发布到 CodeArtifact 存储库中，这将阻止从其上游存储库和 pypi.org 刷新程序包版本的撤销元数据和资产。例如，假设您使用 Web 浏览器从程序包版本 `torch 2.0.1` 下载资产（例如 `torch-2.0.1-cp311-none-macosx_11_0_arm64.whl`），然后使用 twine 以名称 `torch 2.0.1` 将其发布到您的 CodeArtifact 存储库。CodeArtifact 跟踪到程序包版本是通过直接发布到存储库，而不是通过与 pypi.org 或上游存储库的外部连接来进入域。在这种情况下，CodeArtifact 不会使撤销元数据与上游存储库或 pypi.org 保持同步。如果您将 `torch 2.0.1` 发布到上游存储库，情况也是如此，因为存在程序包版本，所以会阻止将撤销元数据和资产传播到上游图更下方的存储库。