管理 Python 软件包

本页面介绍如何添加、查看和删除 Python 软件包和软件包版本。

准备工作

1. 安装并初始化 Google Cloud CLI。

   您必须使用 Google Cloud CLI 354.0.0 或更高版本才能运行 Python 代码库的相关命令。您可以使用以下命令查看版本：

   gcloud version
   

2. 如果目标代码库不存在，请创建新的 Python 软件包代码库。

3. 验证是否已安装 Python 3。如需查看安装说明，请参阅Google Cloud 有关设置 Python 的教程。

4. （可选）为 gcloud 命令配置默认值。

5. 如果您使用 keyring 身份验证和 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 仅安装稳定版。它使用版本标识符规范来区分稳定版和预发布版，并解析要安装的版本的任何要求。

如需添加软件包，请执行以下操作：

1. 安装 Twine。

   pip install twine
   

2. 切换到您的 Python 项目目录。

3. 将分发文件从项目 dist 子目录上传到代码库。运行以下命令：

   twine upload dist/*
   

   您可以使用 --repository-url 标志指定特定代码库。

   twine upload --repository-url https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/ dist/*
   

查看软件包和版本

代码库模式：标准、远程

如需使用 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

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：优先级设置为 100
• secondary-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 和任何其他已配置的软件包索引，并选择软件包的最新版本。

您可以替换 requirements 文件中的 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 会在下次存储库收到对同一软件包版本的请求时再次下载并缓存该软件包。

在删除软件包或软件包版本之前，请确认您已在其中告知或解决任何重要依赖项。

如需删除软件包，请按如下所述操作：

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

如需删除软件包的版本，请按如下所述操作：

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

后续步骤

• 了解如何管理 Java 软件包
• 了解如何管理 Node.js 软件包
• 了解如何管理容器映像
• 下载软件包中的单个文件