管理 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. 如果您使用密钥环身份验证 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是 单区域或多区域 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 定义了 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 搜索软件包的方式。

  • 如果您为 Artifact Registry 代码库配置了 index-url 设置，且未配置其他软件包索引，则仅搜索 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 时，Artifact Registry 会再次下载并缓存 代码库会收到针对同一软件包版本的请求。

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

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

控制台

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

    打开“代码库”页面

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

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

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

  4. 点击删除。

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

gcloud

运行以下命令：

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

地点

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

后续步骤