进阶 docs.pypi.org 2026-10-20 06:39:13 · 24 阅读

第23章 PyPI 项目元数据与网址验证

项目元数据

Python 包可以包含额外的元数据,以提供更多关于项目的相关信息。本文档概述了 PyPI 用于展示项目元数据及其他详细信息的具体行为。完整的元数据字段列表参见 Python 打包用户指南。

项目网址

包的所有者可以通过包 pyproject.toml 文件中的 [project.urls] 表来指定与项目相关的各种网址。

PyPI 会在项目页面上渲染这些网址,并将它们分为已验证和未验证两个子组。你还可以通过 JSON API 获取这些信息。

已验证详情

PyPI 目前支持多种验证项目网址的方式。当网址通过验证后,PyPI 会使用绿色对勾高亮显示。

警告 网址验证仅证明在验证时刻,该网址受 PyPI 包所有者的控制,并不暗示该网址具有其他安全性,或与该项目存在其他关联。

网址验证发生在上传发布文件时,之后不会重复进行。这意味着已验证网址指向的网站可能会发生变化,但网址仍会显示为已验证状态。已验证状态仅反映上传文件时对网址的控制权,而非之后的任何时间点。

以下小节说明了可以验证的不同类型网址。

自链接

PyPI 将任何指向该项目在 PyPI 上的链接视为已验证。 例如,pip 的项目页面会将以下所有链接标记为已验证:

https://pypi.org/project/pip/ https://pypi.org/p/pip/ https://pypi.python.org/project/pip https://pypi.python.org/p/pip https://python.org/pypi/pip

通过可信发布

可信发布(Trusted Publishing)允许 PyPI 证明包的发布工作流来自已验证的来源。 可验证的网址取决于所使用的可信发布者:

GitHub Actions:使用 GHA 从特定仓库上传的包,其对应的 GitHub 网址将被验证。例如,对于 pypa/pip 仓库,以下网址将被验证: https://github.com/pypa/pip https://github.com/pypa/pip/*(所有子路径) https://github.com/pypa/pip.git https://pypa.github.io/pip https://pypa.github.io/pip/*(所有子路径)

GitLab CI/CD:使用 GitLab CI/CD 从特定仓库上传的包,其对应的 GitLab 网址将被验证。例如,对于 pypa/pip 仓库,以下网址将被验证: https://gitlab.com/pypa/pip https://gitlab.com/pypa/pip/*(所有子路径) https://gitlab.com/pypa/pip.git

Google Cloud:目前没有任何 Google 专属网址被验证。 ActiveState:使用 ActiveState 上传的包,其链接到 ActiveState 中该项目的网址将被验证: https://platform.activestate.com/pypa/pip https://platform.activestate.com/pypa/pip/*(所有子路径)

图标

虽然标签或网址可以是任意的,但 PyPI 会识别下方列表中的特定项,并将默认图标更改为自定义图标。

通用网址 要显示自定义图标,条目必须匹配下列模式之一。识别模式不区分大小写。带星号(*)的项表示前缀,即以指定模式开头的任何名称都将被识别。

名称 图标 描述 别名

Homepage 项目主页

Download 下载链接

Changelog 变更日志信息 Change log, Changes, News, Whatsnew, What's new, History

Release notes 精选发布说明 Releasenotes

Documentation* 项目文档 Docs*,指向 Read the Docs 域名或以 docs. 或 documentation. 开头的网址

Bug* Bug/Issue 报告位置 Issue*, Tracker*, Report*

Funding* 赞助信息 Sponsor*, Donation*, Donate*

Security 安全策略或漏洞报告页面 Security Policy, securitypolicy

Source 源代码仓库 Source Code, Sourcecode, Repository

托管平台 条目网址必须指向以下域名之一才能显示自定义图标。也匹配自定义子域名。例如,如果列出了 domain.com,则结尾为 .domain.com 的网址也将匹配。

服务 图标 域名

Bitbucket bitbucket.org

Codeberg codeberg.org, codeberg.page

GitHub github.com, github.io

GitLab gitlab.com

Google google.com

社交媒体平台 要显示自定义图标,条目必须满足以下条件之一: 名称匹配下列不区分大小写的模式 网址指向下列列出的域名(支持自定义子域名)

平台 图标 名称 域名

Discord discord.com, discordapp.com, discord.gg

Telegram t.me, telegram.me, telegram.dog

Matrix matrix.to

Gitter gitter.im

Mastodon Mastodon Mastodon

Reddit reddit.com

Slack Slack* slack.com

Youtube youtube.com, youtu.be

Twitter twitter.com, x.com

Bluesky Bluesky bsky.app

持续集成服务 要显示自定义图标,条目网址必须指向下列列出的服务商域名之一。支持自定义子域名。

服务 域名

AppVeyor ci.appveyor.com

CircleCI circleci.com

Codecov codecov.io

Coveralls coveralls.io

Travis CI travis-ci.com, travis-ci.org

Python 生态系统 要显示自定义图标,条目网址必须指向下列列出的域名之一。

名称 图标 域名

PyPI cheeseshop.python.org, pypi.io, pypi.org, pypi.python.org

Python python.org, *.python.org

评论 (0)