本页介绍了如何添加、查看和删除 Python 软件包和软件包版本。
准备工作
-
您需要使用 Google Cloud CLI 354.0.0 或更高版本才能运行 Python 代码库的命令。您可以使用以下命令检查版本：
gcloud version 如果目标代码库不存在，请创建新的 Python 软件包代码库。
验证是否已安装 Python 3。如需了解安装说明，请参阅Google Cloud 关于设置 Python 的教程。
（可选）为 gcloud 命令配置默认值。
如果您使用 gcloud 凭据搭配密钥串身份验证，请使用您的用户账号或服务账号登录 Google Cloud CLI。
所需的角色
如需获得管理软件包所需的权限，请让管理员向您授予代码库的以下 IAM 角色：
-
查看软件包或软件包中的文件：
Artifact Registry Reader (
roles/artifactregistry.reader) -
下载或安装软件包：Artifact Registry Reader (
roles/artifactregistry.reader) -
将软件包添加到代码库：
Artifact Registry Writer (
roles/artifactregistry.writer) -
删除软件包：
Artifact Registry Repository Administrator (
roles/artifactregistry.repoAdmin)
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
添加软件包
代码库模式：标准
构建 Python 项目时，分发文件会保存在项目的 dist 子目录中。然后，您可以使用 Twine 将软件包上传到标准代码库。
我们建议您在打包时遵循以下最佳实践：
- 为私有软件包使用唯一名称，使其与 pypi.org 上的软件包名称不匹配，尤其是在您的 pip 配置包含多个软件包索引的情况下。
- 请使用 PEP 440 中的版本标识符规范为软件包版本号。默认情况下，pip 仅安装稳定版本。它使用版本标识符规范来区分稳定版和预发布版，并解析要安装的版本的所有要求。
如需添加软件包，请执行以下操作：
安装 Twine。
pip install twine切换到您的 Python 项目目录。
将项目
dist子目录中的分发文件上传到代码库。运行以下命令：twine upload dist/*您可以使用
--repository-url标志指定特定代码库。twine upload --repository-url https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/ dist/*
查看软件包和版本
代码库模式：标准、远程
如需使用 Google Cloud 控制台或 gcloud 查看软件包和软件包版本，请执行以下操作：
控制台
在 Google Cloud 控制台中打开制品库页面。
在代码库列表中，点击相应代码库。
软件包页面列出代码库中的软件包。
点击一个软件包以查看它的版本。
gcloud
如需列出代码库中的软件包，请运行以下命令：
gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]
替换以下内容：
如需查看软件包的版本，请运行以下命令：
gcloud artifacts versions list --package=PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION]
替换以下内容：
对于远程仓库，返回的列表应包含所有直接和传递依赖项。
列出文件
代码库模式：标准、远程
您可以列出代码库中的文件、指定软件包的所有版本中的文件，或软件包的特定版本中的文件。
对于以下所有命令，您都可以通过向命令添加 --limit 标志来设置要返回的文件数量上限。
如需在配置默认值时列出默认项目、代码库和位置中的所有文件，请运行以下命令：
gcloud artifacts files list
如需列出指定项目、代码库和位置中的文件，请运行以下命令：
gcloud artifacts files list \
--project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION
如需列出特定软件包的所有版本的文件，请执行以下操作：
gcloud artifacts files list \
--project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION \
--package=PACKAGE
如需列出特定软件包版本的文件，请运行以下命令：
gcloud artifacts files list \
--project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION \
--package=PACKAGE \
--version=VERSION
替换以下值：
LOCATION：代码库的单区域或多区域位置。PROJECT：您的 Google Cloud 项目 ID。 如果您的项目 ID 包含英文冒号 (:)，请参阅网域级项目。REPOSITORY：存储了映像的代码库的名称。PACKAGE：软件包的名称。VERSION：软件包的版本。
示例
请考虑以下软件包信息：
- 项目：
my-project - 代码库：
my-repo - 代码库位置：
us-west1 - 文件包：
my-app
以下命令会列出默认项目中位置 us-west1 的代码库 my-repo 中的所有文件：
gcloud artifacts files list \
--location=us-west1 \
--repository=my-repo
1.0 中的文件。
gcloud artifacts files list \
--project=my-project \
--location=us-west1 \
--repository=my-repo \
--package=my-app \
--version=1.0
安装软件包
代码库模式：标准、远程、虚拟
使用 pip 命令安装软件包。
如需安装软件包的最新稳定版，请运行以下命令：
pip install PACKAGE
对于标准代码库，您可以直接从代码库下载软件包。
对于远程代码库，您可以下载软件包及其依赖项的缓存副本。如果不存在缓存的副本，远程代码库会从上游源代码下载该软件包并将其缓存，然后再将其提供给您。您可以查看代码库中的软件包列表，验证远程代码库是否从上游源代码检索了软件包。
对于虚拟代码库，Artifact Registry 会搜索上游代码库以查找请求的软件包。
- 如果缓存副本不存在，上游远程仓库将下载并缓存请求的软件包。虚拟代码库仅提供请求的软件包，不会存储这些软件包。
- 如果您请求的版本在多个上游代码库中都有，Artifact Registry 会根据为虚拟代码库配置的优先级设置选择要使用的上游代码库。
例如，假设某个虚拟代码库的上游代码库具有以下优先级设置：
main-repo：优先级设置为100secondary-repo1：优先级设置为80。secondary-repo2：优先级设置为80。test-repo：优先级设置为20。
main-repo 具有最高优先级值，因此虚拟仓库始终会先搜索它。
secondary-repo1 和 secondary-repo2 的优先级均设为 80。如果请求的软件包未在 main-repo 中找到，Artifact Registry 接下来会搜索这些代码库。由于它们具有相同的优先级值，因此如果这两个仓库中都提供该版本，Artifact Registry 可以选择从任一仓库中提供该软件包。
test-repo 具有最低优先级值，如果其他上游代码库都没有存储工件，则会提供存储的工件。
其他信息
默认情况下，pip 会安装软件包的稳定版本，并忽略预发布版本。PEP 440 定义了 Python 版本标识符规范，供 pip 用户解析版本号，包括预发布版本。
如需在 pip 搜索要安装的软件包时包含预发布版本，请将 --pre 标志添加到您的命令中。
pip install --pre PACKAGE
如需指定所需的版本或版本范围，请添加要求说明符。您可以直接在命令中添加版本要求，也可以使用要求文件。
例如，以下命令指定 my-package 的最低版本是开发版本 1.0.dev0。
pip install --pre my-package>=1.0.dev0
稳定版被视为比预发布版更高级，因此如果版本 1.0 位于代码库中，pip 会选择版本 1.0，而不是预发布版本。
如果您未指定代码库，则 pip.conf 中的 pip 配置将决定 pip 搜索软件包的方式。
- 如果您使用
index-url设置配置了 Artifact Registry 代码库，并且未配置任何其他软件包索引，则 pip 只会在您的 Artifact Registry 代码库中搜索软件包。 - 如果您使用的是虚拟代码库，当多个上游代码库都包含所请求的软件包版本时，Artifact Registry 会使用上游政策中配置的优先级来选择软件包。如果包含该软件包的两个仓库具有相同的优先级，Artifact Registry 会从任一仓库中提供该软件包。
- 如果您使用
extra-index-url设置配置了 pip，或者配置了多个软件包索引，pip 会搜索 pypi.org 和任何其他配置的软件包索引，并选择最新版本的软件包。
您可以在要求文件中替换 index-url 或 extra-index-url 设置。您还可以在 pip 命令中使用这些设置的标志。例如，以下命令会使用 Artifact Registry 制品库替换 index-url。
pip install --index-url https://us-east1-python.pkg.dev/my-project/python-repo/simple/ my-package
如需详细了解如何安装软件包，请参阅 Python 打包文档。
删除软件包和版本
代码库模式：标准、远程
您可以删除软件包及其所有版本，也可以删除特定版本。
- 删除文件包后，您无法撤消此操作。
- 对于远程代码库，系统只会删除软件包的缓存副本。上游来源不受影响。如果您删除了缓存的软件包，那么当代码库下次收到针对同一软件包版本的请求时，Artifact Registry 会再次下载并缓存该软件包。
在删除软件包或软件包版本之前，请确认您已在其中告知或解决任何重要依赖项。
如需删除软件包，请按如下所述操作：
控制台
在 Google Cloud 控制台中打开制品库页面。
在代码库列表中，点击相应代码库。
软件包页面列出代码库中的软件包。
选择要删除的软件包。
点击删除。
在确认对话框中，点击删除。
gcloud
运行以下命令：
gcloud artifacts packages delete PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION] [--async]
替换以下内容：
PACKAGE是代码库中的软件包名称。REPOSITORY是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。-
LOCATION是代码库的单区域或多区域位置。 使用此标志可查看特定位置中的代码库。如果您配置了默认位置，则可以省略此标志以使用默认值。
--async 标志会导致命令立即返回，而无需等待正在进行的操作完成。
如需删除软件包的版本，请按如下所述操作：
控制台
在 Google Cloud 控制台中打开制品库页面。
在代码库列表中，点击相应代码库。
软件包页面列出代码库中的软件包。
点击一个软件包以查看它的版本。
选择您要删除的版本。
点击删除。
在确认对话框中，点击删除。
gcloud
运行以下命令：
gcloud artifacts versions delete VERSION \
--package=PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION] \
[--async]
替换以下内容：
VERSION是要删除的版本的名称。PACKAGE是代码库中的软件包名称。REPOSITORY是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。-
LOCATION是代码库的单区域或多区域位置。 使用此标志可查看特定位置中的代码库。如果您配置了默认位置，则可以省略此标志以使用默认值。
--async 标志会导致命令立即返回，而无需等待正在进行的操作完成。