本页面介绍了如何添加、查看和删除 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 读取者 (
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]
地点
- 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
以下命令将列出 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 会再次下载并缓存 代码库会收到针对同一软件包版本的请求。
在删除软件包或软件包版本之前,请确认您已在其中告知或解决任何重要依赖项。
如需删除软件包,请按如下所述操作:
控制台
打开 Google Cloud 控制台中的制品库页面。
在代码库列表中,点击相应代码库。
软件包页面列出代码库中的软件包。
选择要删除的软件包。
点击删除。
在确认对话框中,点击删除。
gcloud
运行以下命令:
gcloud artifacts packages delete PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION] [--async]
地点
如需删除软件包的版本,请按如下所述操作:
控制台
打开 Google Cloud 控制台中的制品库页面。
在代码库列表中,点击相应代码库。
软件包页面列出代码库中的软件包。
点击一个软件包以查看它的版本。
选择您要删除的版本。
点击删除。
在确认对话框中,点击删除。
gcloud
运行以下命令:
gcloud artifacts versions delete VERSION \
--package=PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION] \
[--async]
地点