使用极狐GitLab 管理 python 包

软件包库中的 PyPI 包 (BASIC ALL)

在项目的软件包库中发布 PyPI 包。然后在需要将它们用作依赖项时安装它们。

软件包库适用于：

• pip
• twine

使用极狐GitLab 软件包库进行身份验证

在您发布到极狐GitLab 软件包仓库之前，您必须进行认证。

要如此，您可以使用：

• 一个具有 api 范围的个人访问令牌。
• 一个具有 read_package_registry 或/和 write_package_registry 范围的部署令牌。
• 一个 CI 作业令牌。

请勿使用此处文档记录的方法以外的其他身份验证方法。 未记录的身份验证方法可能会在将来删除。

TWINE_USERNAME 和 TWINE_PASSWORD 环境变量用于使用极狐GitLab 令牌进行身份验证。

使用个人访问令牌进行认证

要使用个人访问令牌进行身份验证，请更新 TWINE_USERNAME 和 TWINE_PASSWORD 环境变量：

image: python:latest

run:
  variables:
    TWINE_USERNAME: <your_personal_access_token_name>
    TWINE_PASSWORD: <your_personal_access_token>
  script:
    - pip install build twine
    - python -m build
    - python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*

使用部署令牌进行认证

要使用部署令牌进行身份验证，请更新 TWINE_USERNAME 和 TWINE_PASSWORD 环境变量：

image: python:latest

run:
  variables:
    TWINE_USERNAME: <deploy token username>
    TWINE_PASSWORD: <deploy token>
  script:
    - pip install build twine
    - python -m build
    - python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*

使用 CI 作业令牌进行认证

要使用 CI 作业令牌进行身份验证，请更新 TWINE_USERNAME 和 TWINE_PASSWORD 环境变量：

image: python:latest

run:
  variables:
    TWINE_USERNAME: gitlab-ci-token
    TWINE_PASSWORD: $CI_JOB_TOKEN
  script:
    - pip install build twine
    - python -m build
    - python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*

进行身份验证以访问某个群组内的软件包

遵循上述的令牌类型指南，但使用群组 URL 代替项目 URL：

https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/pypi

[ ]()## [ ]()发布 PyPI 软件包

先决条件：

• 您必须使用软件包库进行身份验证。
• 您的版本字符串必须有效。
• 允许的最大包大小为 5 GB。
• description 字段的最大长度为 4000 字符。更长的 description 字符串会被截断。
• 不能多次上传同一版本的包。如果您尝试，您会收到错误 400 Bad Request。
• 使用您的 项目 ID 发布 PyPI 包。
• 如果您的项目在一个群组中，则发布到您的项目库的 PyPI 包也可以在群组级库中使用（请参阅从群组级别安装）。

然后，您就可以使用 twine 发布 PyPI 包。

使用 twine 发布 PyPI 包

定义您的仓库源，编辑 ~/.pypirc 文件并添加：

[distutils]
index-servers =
    gitlab

[gitlab]
repository = https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi

要发布 PyPI 包，请运行类似的命令:

python3 -m twine upload --repository gitlab dist/*

如下消息预示着包已成功发布：

Uploading distributions to https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi
Uploading mypypipackage-0.0.1-py3-none-any.whl
100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.58k/4.58k [00:00<00:00, 10.9kB/s]
Uploading mypypipackage-0.0.1.tar.gz
100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.24k/4.24k [00:00<00:00, 11.0kB/s]

要查看已发布的软件包，前往您项目的 软件包与镜像库 页面。

如果您没有使用 .pypirc 文件来定义仓库源，则可以使用内联身份验证发布到仓库：

TWINE_PASSWORD=<personal_access_token or deploy_token or $CI_JOB_TOKEN> TWINE_USERNAME=<username or deploy_token_username or gitlab-ci-token> python3 -m twine upload --repository-url https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi dist/*

如果您没有遵循此页面上的步骤，请确保您的包已正确构建，并且您使用 setuptools 创建了一个 PyPI 包.

然后，您就可以使用如下的命令来上传您的软件包：

python -m twine upload --repository <source_name> dist/<package_file>

• <package_file> 是您的软件包文件名，以 .tar.gz 或 .whl 结尾。
• <source_name> 是设置期间使用的源名称。

[ ]()### [ ]()发布具有相同名称或版本的软件包

如果具有相同名称和版本的软件包已经存在，则您无法发布软件包。您必须先删除现有的软件包。如果您尝试多次发布同一个软件包，则会发生 400 Bad Request 错误。

安装 PyPI 软件包

当在软件包仓库中找不到 PyPI 软件包时，请求转发到 pypi.org。

管理员可以在持续集成设置中禁用此行为。

WARNING: 当您使用 --index-url 选项时，不要指定默认端口，例如 80 以 http 开头的 URL，或 443 以 https 开头的 URL。

[ ]()### [ ]()从项目进行安装

要安装最新版本的软件包，使用以下命令:

pip install --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple --no-deps <package_name>

• <package_name> 是软件包名称。
• <personal_access_token_name> 是具有 read_api 范围的个人访问令牌名称。
• <personal_access_token> 是具有 read_api 范围的个人访问令牌。
• <project_id> 是项目的 URL 编码路径（例如：group%2Fproject），或项目 ID（例如：42）。

在这些命令中，您可以使用 --extra-index-url 代替 --index-url。如果您遵循指南，并想要安装 MyPyPiPackage 软件包，您可以运行:

pip install mypypipackage --no-deps --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple

如下信息显示软件包已成功安装：

Looking in indexes: https://<personal_access_token_name>:****@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple
Collecting mypypipackage
  Downloading https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/files/d53334205552a355fee8ca35a164512ef7334f33d309e60240d57073ee4386e6/mypypipackage-0.0.1-py3-none-any.whl (1.6 kB)
Installing collected packages: mypypipackage
Successfully installed mypypipackage-0.0.1

安全性影响

当安全 PyPI 时，使用 --extra-index-url 或 --index-url 时，安全性影响很大，值得深入了解。如果您在使用：

• --index-url：此选项会替换具有指定 URL 的 PyPI 索引。它是更安全的，因为它仅检查指定索引中的包。在您想确保仅从信任的私人源安装包时使用此选项。
• --extra-index-url：此选项会将附加索引添加到默认的 PyPI 索引。它是不安全的，因为它会检查默认的 PyPI 索引和附加索引中的包，因此会导致依赖混淆攻击。

从群组安装

要从群组安装最新版本的软件包，使用以下命令:

pip install --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/groups/<group_id>/-/packages/pypi/simple --no-deps <package_name>

在此命令中：

• <package_name> 是软件包名称。
• <personal_access_token_name> 是具有 read_api 范围的个人访问令牌名称。
• <personal_access_token> 是具有 read_api 范围的个人访问令牌。
• <group_id> 是群组 ID。

在这些命令中，您可以使用 --extra-index-url 代替 --index-url。然而，使用 --extra-index-url 会使您受到依赖混淆攻击的影响，因为它会在检查自定义仓库之前检查 PyPi 仓库中的包。 --extra-index-url 添加了提供的 URL 作为额外的仓库，客户端将检查它是否存在包。 --index-url 告诉客户端仅在提供的 URL 中检查包。

如果您遵循指南，并且想要安装 MyPyPiPackage 软件包，您可以运行:

pip install mypypipackage --no-deps --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/pypi/simple

软件包名称

极狐GitLab 查找使用 PEP-503 标准化名称的软件包。-、_ 和 . 都被视为相同，并且重复的字符会被删除。

针对 my.package 的 pip install 请求会查找匹配任何三个字符的包，例如 my-package、my_package 和 my....package。

使用 requirements.txt

如果您想 pip 能够访问您的公共仓库，请将 --extra-index-url 参数与您的仓库 URL 一起添加到您的 requirements.txt 文件中。

--extra-index-url https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple
package-name==1.0.0

如果这是私有仓库，您可以使用以下方式进行身份验证：

• 使用您的 requirements.txt 文件：

--extra-index-url https://__token__:<your_personal_token>@gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple
package-name==1.0.0

• 使用 ~/.netrc 文件：

machine gitlab.example.com
login __token__
password <your_personal_token>

版本化 PyPI 软件包

正确的版本化对高效管理 PyPI 软件包是非常重要的。遵循这些最佳实践以确保您的软件包能够正确版本化。

使用语义化版本号（SemVer）

为您的软件包采用语义化版本号（SemVer）。版本号应使用格式 MAJOR.MINOR.PATCH:

• 为不兼容的 API 变更，增加 MAJOR 版本号。
• 为向后兼容的新功能，增加 MINOR 版本号。
• 为向后兼容的 bug 修复，增加 PATCH 版本号。

比如，1.0.0、1.1.0、1.1.1。

从 0.1.0 开始

对于新项目，从 0.1.0 开始。这表示初始开发阶段，API 还未稳定。

使用有效的版本设置

确保您的版本字符串符合 PyPI 标准。极狐GitLab 使用特定的正则表达式来验证版本字符串:

\A(?:
    v?
    (?:([0-9]+)!)?                                                 (?# epoch)
    ([0-9]+(?:\.[0-9]+)*)                                          (?# release segment)
    ([-_\.]?((a|b|c|rc|alpha|beta|pre|preview))[-_\.]?([0-9]+)?)?  (?# pre-release)
    ((?:-([0-9]+))|(?:[-_\.]?(post|rev|r)[-_\.]?([0-9]+)?))?       (?# post release)
    ([-_\.]?(dev)[-_\.]?([0-9]+)?)?                                (?# dev release)
    (?:\+([a-z0-9]+(?:[-_\.][a-z0-9]+)*))?                         (?# local version)
)\z}xi

故障排查

为了改善性能，pip 命令会缓存与软件包相关的文件。Pip 不自行删除数据。缓存会随着新软件包的安装而增长。如果您遇到问题，请使用此命令清除缓存:

pip cache purge

多个 index-url 或 extra-index-url 参数

您可以定义多个 index-url 和 extra-index-url 参数。

如果您使用令牌认证多次使用了相同的域名名称（例如：gitlab.example.com），pip 可能无法找到您的软件包。这个问题是由在命令执行期间 pip 注册和存储令牌导致。

为解决此问题，你可以使用一个群组部署令牌，该令牌来自所有作为 index-url 和 extra-index-url 值所指向目标的项目或群组的共同父群组，且其权限范围为 read_package_registry。

要解决此问题，您可以

支持的 CLI 命令

极狐GitLab PyPI 仓库支持如下 CLI 命令：

• twine upload: 将软件包上传到仓库。
• pip install: 从仓库安装 PyPI 软件包。