管理 Python 软件包

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

准备工作

  1. 安装并initialize Google Cloud CLI。

    如需运行 Python 代码库命令，您需要使用 Google Cloud CLI 354.0.0 或更高版本。您可以使用以下命令检查版本：

    gcloud version

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

  3. 验证是否已安装 Python 3。如需了解安装说明，请参阅 Google Cloud 设置 Python 教程。

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

  5. 如果您将密钥环身份验证与 gcloud 凭据结合使用，请使用您的用户帐号或服务帐号登录 Google Cloud CLI。

所需的角色

如需获取管理软件包所需的权限，请让管理员授予您针对代码库的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

添加软件包

代码库模式：标准

当您构建 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 查看软件包和软件包版本，请执行以下操作：

控制台

  1. 打开 Google Cloud 控制台中的制品库页面。

    打开“代码库”页面

  2. 在代码库列表中，点击相应代码库。

    软件包页面列出代码库中的软件包。

  3. 点击一个软件包以查看它的版本。

gcloud

如需列出代码库中的软件包，请运行以下命令：

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

地点

  • REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
  • LOCATION 是单区域或多区域位置。使用此标志可查看特定位置的代码库。如果您配置了默认位置，可以省略此标志，以便使用默认位置。

如需查看软件包的版本，请运行以下命令：

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

其中

  • PACKAGE 是软件包的 ID 或软件包的完全限定标识符。
  • REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
  • 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

以下命令用于列出代码库 my-repo 中位于默认项目位置 us-west1 中的所有文件：

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：优先级已设为 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 定义了 pip 用户用于解析版本号（包括预发布版本）的 Python 版本标识符规范。

如需在 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 命令中为这些设置使用标志。例如，此命令会将 index-url 替换为 Artifact Registry 代码库。

pip install --index-url https://us-east1-python.pkg.dev/my-project/python-repo/simple/ my-package

如需详细了解如何安装软件包，请参阅 Python 打包文档。

删除软件包和版本

代码库模式：标准、远程

您可以删除软件包及其所有版本，也可以删除特定版本。

  • 软件包一经删除便无法撤消。
  • 对于远程仓库，只有软件包的缓存副本会被删除。上游来源不受影响。如果您删除缓存的软件包，Artifact Registry 会在下次收到针对相同软件包版本的请求时下载并再次缓存该软件包。

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

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

控制台

  1. 打开 Google Cloud 控制台中的制品库页面。

    打开“代码库”页面

  2. 在代码库列表中，点击相应代码库。

    软件包页面列出代码库中的软件包。

  3. 选择要删除的软件包。

  4. 点击删除。

  5. 在确认对话框中，点击删除。

gcloud

运行以下命令：

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

地点

  • PACKAGE 是代码库中的软件包名称。
  • REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
  • LOCATION 是单区域或多区域位置。使用此标志可查看特定位置的代码库。如果您配置了默认位置，可以省略此标志，以便使用默认位置。
  • --async 会立即返回结果，而无需等待正在进行的操作完成。

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

控制台

  1. 打开 Google Cloud 控制台中的制品库页面。

    打开“代码库”页面

  2. 在代码库列表中，点击相应代码库。

    软件包页面列出代码库中的软件包。

  3. 点击一个软件包以查看它的版本。

  4. 选择您要删除的版本。

  5. 点击删除。

  6. 在确认对话框中，点击删除。

gcloud

运行以下命令：

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

地点

  • PACKAGE 是代码库中的软件包名称。
  • REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
  • LOCATION 是单区域或多区域位置。使用此标志可查看特定位置的代码库。如果您配置了默认位置，可以省略此标志，以便使用默认位置。
  • --async 会立即返回结果，而无需等待正在进行的操作完成。

后续步骤