Python Academy · 课时

版本管理与元数据

Q: 「版本管理与元数据」这节课中我会学到什么？

管理软件包元数据 你通过在浏览器中直接运行的动手代码来练习 Python Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

管理软件包元数据

版本管理与元数据 是 CoddyKit 上的免费 Python Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Python Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Python Academy 课程共包含 4 节课。

为什么元数据很重要

元数据包含包中除代码以外的所有信息：版本、描述、许可证、作者和链接。PyPI 使用它来展示您的项目，pip 使用它来解析依赖项。

良好的元数据能让您的包更值得信赖，也更易于安装。

语义化版本控制

约定格式是 MAJOR.MINOR.PATCH：

MAJOR 不兼容的变更
MINOR 向后兼容的新功能
PATCH 向后兼容的错误修复

用户依靠这一约定来判断升级是否安全。

version = '2.4.1'
major, minor, patch = version.split('.')
print('Major', major, 'Minor', minor, 'Patch', patch)
print('Bug fix -> bump patch to', major + '.' + minor + '.' + str(int(patch) + 1))

选择下一个版本

决定版本 bump 遵循明确的规则：您是否破坏了接口、添加了功能，还是只是修复了错误？将规则编码下来可以使发布保持一致。

def bump(version, kind):
    major, minor, patch = (int(x) for x in version.split('.'))
    if kind == 'major':
        return str(major + 1) + '.0.0'
    if kind == 'minor':
        return str(major) + '.' + str(minor + 1) + '.0'
    return str(major) + '.' + str(minor) + '.' + str(patch + 1)

print(bump('1.2.3', 'minor'))
print(bump('1.2.3', 'major'))

预发布版本与开发版本

Python 允许使用后缀：1.0.0a1（阿尔法版）、1.0.0b2（贝塔版）、1.0.0rc1（候选发布版）和 1.0.0.dev3。pip 会将这些版本视为早于最终版 1.0.0，因此测试人员可以主动选择使用它们，而不会影响普通用户。

单一事实来源

将版本保存在且只保存在一个位置。您可以在 pyproject.toml 中静态声明版本，也可以将其标记为 dynamic，然后通过 setuptools-scm 等工具从代码（或标签）中读取。两份副本最终必然会逐渐不一致。

描述和 README

简短的 description 会显示在搜索结果中。详细描述来自您的 readme（通常是 README.md），并会呈现为 PyPI 项目页面。使用 readme = 'README.md' 指向它。

清晰的 README 是最好的宣传材料。

许可证

popular = ['MIT', 'Apache-2.0', 'BSD-3-Clause', 'GPL-3.0-only']
for lic in popular:
    print('SPDX:', lic)

分类器

classifiers 是来自 PyPI 列表的标准化标签，例如 'Programming Language :: Python :: 3.11' 或 'Development Status :: 4 - Beta'。它们为 PyPI 的筛选功能提供支持，并表明项目的成熟度和支持的版本。

项目网址

在 [project.urls] 下添加主页、文档、源代码和更新日志等链接。这些链接会显示在 PyPI 的侧边栏中，帮助用户找到您的代码仓库和文档。

urls = {
    'Homepage': 'https://example.com',
    'Source': 'https://github.com/me/mytool',
    'Issues': 'https://github.com/me/mytool/issues',
}
for label, link in urls.items():
    print(label.ljust(10), link)

用于发现的关键词

keywords 字段是一个简短术语列表，可帮助用户在搜索中找到您的包。请选择人们实际会输入的词语，例如 ['cli', 'automation', 'excel']，而不要使用泛泛的填充词。

关键词与分类器结合后，可以提高项目的可发现性。

更新日志

维护一份 CHANGELOG，记录每个版本发生的变化。用户会在升级前阅读它，以了解新功能和不兼容变更。在 [project.urls] 下添加链接后，用户就能从 PyPI 页面一键访问它。

优秀的更新日志能让版本号变成一段用户可以追踪的故事。

快速检查

测试一下您对版本管理的掌握情况。

回顾

您已经掌握了软件包元数据的管理：

语义化版本控制 MAJOR.MINOR.PATCH，以及预发布后缀
将版本保存在单一事实来源中
提供 description、README 长描述和 license
添加 classifiers 和 [project.urls]，让 PyPI 更好地展示您的项目

常见问题解答

「版本管理与元数据」课时是免费的吗？

是的 — 「版本管理与元数据」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Python Academy 课程的其余内容，请升级到 CoddyKit PRO。 Python Academy 课程共包含 4 节课。

「版本管理与元数据」这节课中我会学到什么？

管理软件包元数据你通过在浏览器中直接运行的动手代码来练习 Python Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Python Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Python Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「版本管理与元数据」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Python Academy 课中编写并运行代码吗？

能。每节 Python Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Python Academy