Python包README与元数据规范详解

本文深入解析了Python包发布到PyPI前必须严格遵循的README与元数据规范，直击开发者常踩的“No description”、twine校验通过却上传失败、分类器误配导致搜索不可见等高频痛点；从README.md的命名大小写、位置、首段纯文本摘要写法，到pyproject.toml中name、version、description、readme、requires-python等硬性字段的格式与取值细节，再到classifiers如何精准标注语言版本、许可证和系统兼容性，最后手把手教你解压验证.whl内真实METADATA内容——每一条都是PyPI实际解析逻辑的真实映射，帮你避开90%的上传失败和用户信任流失。

README.md 该写什么、怎么组织才不被 PyPI 忽略

PyPI 不会渲染 README 中的任意 HTML 或复杂嵌套结构，只认标准 Markdown 语法，且对首段摘要极度敏感。如果上传后项目页显示“No description”，大概率是 README.md 缺失、路径不对，或首段没用纯文本写清功能。

必须满足的三点：

• README.md 文件名严格大小写匹配，不能是 readme.md 或 README.MD
• 文件需放在项目根目录（和 pyproject.toml 同级），不是 src/ 下
• 首段建议控制在 1–3 行纯文字，避免以标题、图片、引用块开头 —— PyPI 提取摘要时会跳过这些

推荐开头写法示例：

my_package: A lightweight utility for parsing ISO 8601 timestamps with timezone-aware validation.

后面再接安装命令、基本用法、API 示例。别把 LICENSE 全文粘进去，放个链接就行。

pyproject.toml 中 [project] 表必须填哪些字段才能通过 twine check

twine check 是上传前必跑的校验工具，它不报错 ≠ PyPI 接收成功，但报错一定拦你。核心元数据字段缺失或格式错误会直接拒绝上传。

以下字段为硬性要求（pyproject.toml 的 [project] 表内）：

• name：必须全小写、仅含 ASCII 字母/数字/下划线/连字符；不能和 PyPI 上已有包重名
• version：必须符合 PEP 440 格式，如 "0.1.0"、"1.2.3a1"；不能是 "dev" 或 "latest"
• description：纯文本单行摘要，长度建议 ≤ 200 字符；若留空，twine check 不报错但 PyPI 页面无描述
• readme：值必须是字符串 "README.md"（或 "README.rst"），不能带路径如 "docs/README.md"
• requires-python：明确声明支持的 Python 版本范围，如 ">=3.8"；漏写会导致用户安装失败却无法提示

常见翻车点：authors 写成列表但没用字典格式，例如写成 authors = ["Alice"] 会触发 twine check 警告；正确写法是 authors = [{ name = "Alice", email = "alice@example.com" }]。

Metadata 规范里 classifiers 怎么选才不影响搜索和兼容性判断

PyPI 搜索、IDE 自动补全、CI 环境识别 Python 版本，都依赖 classifiers 字段。它不是装饰项，而是机器可读的关键标签。

必须包含且准确填写的分类器：

• "Programming Language :: Python :: 3"：所有 Python 3 包都得有，缺了会被标记为“Python 2 only”
• "Programming Language :: Python :: 3.X"（X 替换为你实际支持的最低版本，如 3.8）：否则 CI 可能误判环境兼容性
• "License :: OSI Approved :: MIT License"（或其他对应许可证）：不写或写错会导致 PyPI 不显示许可证图标，影响用户信任
• "Operating System :: OS Independent"：如果你没用 C 扩展或系统调用，就写这个；写了 Microsoft :: Windows 却在 Linux 下能跑，反而误导用户

别乱加 "Topic :: Software Development :: Libraries" 这类泛分类 —— 它不参与任何自动逻辑，纯属占位，还可能稀释真实标签权重。

如何验证 .whl 文件里的 METADATA 是否真按规范生成

构建出 .whl 后，别只信 twine check。PyPI 实际读取的是包内 METADATA 文件（位于 my_package-0.1.0.dist-info/ 下），而这个文件由构建后端自动生成，有时会因配置疏漏漏掉字段。

手动验证步骤：

• 用 unzip -l my_package-0.1.0-py3-none-any.whl | grep METADATA 确认文件存在
• 用 unzip -p my_package-0.1.0-py3-none-any.whl my_package-0.1.0.dist-info/METADATA | head -n 15 查看前几行
• 检查是否含 Name:、Version:、Summary:、Requires-Python: 等关键头字段；Summary: 值应和 pyproject.toml 里 description 一致

注意：Summary: 是从 description 字段拷贝的，不是从 README 首段提取的 —— 很多人以为改了 README 就能更新摘要，其实不会。

以上就是《Python包README与元数据规范详解》的详细内容，更多关于的资料请关注golang学习网公众号！