用setuptools_scm来自动控制Python包的版本

手动管理Python包的版本号一段时间后，寻求自动化的手段，是自然而然的。

手动管理版本

手动管理Python包的版本，需要注意两个方面：

每次发布新包前，要更新包的版本号。

在安装后的默认模块下应该有一个变量，其值为版本号。

关于第一点，可以参考《PEP 440 — Version Identification and Dependency Specification》；

关于第二点，可以参考《PEP 396 — Module Version Numbers》。

当然，两边的版本号必须是相同的。

除了手动修改两个版本号这种愚蠢的方案以外，要保持两边的版本号一致，无外乎两种方式：

通过包的版本号来给出的值。

通过的值来设置包的版本号。

具体的做法，可以参考《Single-sourcing the package version — Python Packaging User Guide》，其中给出了6种可行方案。

其中也有陷阱，但这里不再详述。

无论如何，这些方案里的版本号总是要手动去改的。

本文着重介绍其中的第7个方案——setuptools_scm。

自动生成版本号

setuptools_scm是PYPA推荐的一个自动管理Python包版本号的工具，是setuptools的一个插件。

它会根据包括Git在内的各大VCS的tag，来自动生成一个版本号。

当前commit就在tag上，代码没有修改：

当前commit就在tag上，代码有修改：

当前commit不在tag上，代码没有修改：

当前commit不在tag上，代码有修改：

使用方式十分简单。

首先，在中指定它。

然后，设置。

当然，旧的方式也应该去掉。

如果Git库的根目录不在所在的目录，则会出错。

届时，可把替换为以下内容。

是指相对于那里，通常设为所在目录；

是指定Git库的根目录的相对位置，这里示例的表示上一级目录，可按需指定。

设置version

使用setuptools_scm方案，则版本号是在函数中自动生成的。

主模块的如果需要和它保持一致，就需要读取已安装的当前包的版本号。

以上代码就是孤常用的一个方案。

如果出现任何意外，则返回一个明显错误的版本号。

比一般方案更复杂的一点是，孤考虑到了在中调用这个文件的情况，分别对Python 2.x和3.x做出了处理。

总结

setuptools_scm是一个不错的工具，打消了孤自己写一个的念头。

当然它也有一些不如人意的细节，比如的设计。

但瑕不掩瑜，值得一试。