本页面介绍了如何添加、查看和删除 Python 软件包和软件包版本。
准备工作
安装并initialize Google Cloud CLI。
运行 Python 代码库的命令需要 Google Cloud CLI 354.0.0 或更高版本。您可以使用以下命令检查版本:
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]
地点
- REPOSITORY 是代码库的名称。如果您配置了默认代码库,则可以省略此标志以使用默认值。
- 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
:优先级设置为“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 搜索软件包的方式。
- 如果您为 Artifact Registry 代码库配置了
index-url
设置,并且未配置其他软件包索引,则 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 会在代码库下次收到相同软件包版本的请求时再次下载并缓存该软件包。
在删除软件包或软件包版本之前,请确认您已在其中告知或解决任何重要依赖项。
如需删除软件包,请按如下所述操作:
控制台
打开 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]
地点