版本控制者

• 就像火箭手一样，但对于版本！
• https://github.com/python-versioneer/python-versioneer
• 布莱恩·华纳
• 许可证：公共领域（无许可证）
• 兼容：Python 3.7、3.8、3.9、3.10 和 pypy3
• 
• 

这是一个用于管理基于 setuptools 的 python 项目中记录的版本号的工具。目标是从发布过程中删除繁琐且容易出错的“更新嵌入式版本字符串”步骤。制作一个新版本应该像在你的版本控制系统中记录一个新标签一样容易，也许还可以制作新的 tarball。

快速安装

Versioneer 提供了两种安装方式。“经典”供应商模式将版本控制者的副本安装到您​​的存储库中。实验性的构建时依赖模式旨在让您跳过此步骤并简化升级过程。

供应商模式

• pip install versioneer到你的 $PATH 中的某个地方
• 向您的[versioneer] setup.cfg中添加一个[tool.versioneer]部分（请参阅安装）pyproject.toml or a section to your
• 在您的源代码树中运行versioneer install --vendor，提交结果
• 验证版本信息python setup.py version

构建时依赖模式

• pip install versioneer到你的 $PATH 中的某个地方
• 向您的[versioneer] setup.cfg中添加一个[tool.versioneer]部分（请参阅安装）pyproject.toml or a section to your
• 添加versioneer到表 的requires键中： build-systempyproject.toml

  [build-system]
  requires = ["setuptools", "versioneer"]
  build-backend = "setuptools.build_meta"
  

• 在您的源代码树中运行versioneer install --no-vendor，提交结果
• 验证版本信息python setup.py version

版本标识符

源树来自不同的地方：

• 版本控制系统检查（主要由开发人员使用）
• 由构建自动化生成的夜间 tarball
• 快照压缩包，由基于 Web 的 VCS 浏览器生成，例如 github 的“来自标签的压缩包”功能
• 由“setup.py sdist”生成的发布 tarball，通过 PyPI 分发

在每个源代码树中，版本标识符（字符串或数字，此工具与格式无关）可以来自多个位置：

• 询问 VCS 工具本身，例如“git describe”（用于结帐），它知道最近的“标签”和绝对修订 ID
• 解压 tarball 的目录的名称
• 扩展的 VCS 关键字（$Id$ 等）
• 由_version.py一些较早的构建步骤创建的

对于已发布的软件，版本标识符与 VCS 标签密切相关。一些项目使用的标签名称不仅仅包含版本字符串（例如“myproject-1.2”而不是“1.2”），在这种情况下，工具需要去除标签前缀以提取版本标识符。对于未发布的软件（在标签之间），版本标识符应该提供足够的信息来帮助开发人员重新创建同一棵树，同时也让他们大致了解这棵树的年龄（1.2 版之后，1.3 版之前）。许多 VCS 系统可以报告捕获此内容的描述，例如git describe --tags --dirty --always报告“0.7-1-g574ab98-dirty”之类的内容，以指示结帐是超过 0.7 标签的一个修订版，具有唯一的修订版 ID“574ab98”，并且是“肮脏的”

版本标识符有多种用途：

• 允许模块自我识别其版本：myproject.__version__
• 为“setup.py sdist”压缩包选择名称和前缀

操作理论

Versioneer 通过将一个特殊_version.py文件添加到您的源代码树中来工作，您__init__.py可以在其中导入它。这_version.py知道如何在导入时动态地向 VCS 工具询问版本信息。

_version.py还包含$Revision$标记，并且安装过程标记_version.py以在git archive命令期间用标记名称重写此标记。因此，生成的 tarball 将包含足够的信息来获得正确的版本。

为了setup.py也允许计算版本，将 aversioneer.py添加到源树的顶层，旁边setup.py是setup.cfg 配置它的 。这会覆盖几个 distutils/setuptools 命令以在调用时计算版本，并更改setup.py build​​并setup.py sdist替换_version.py为仅包含生成的版本数据的小型静态文件。

安装

有关详细的安装说明，请参阅INSTALL.md。

版本字符串风味

_version使用 Versioneer 的代码可以在运行时通过从主__init__.py文件导入并运行该 get_versions()函数来了解其版本字符串。从“外部”（例如 in setup.py），您可以导入顶层versioneer.py并运行get_versions().

这两个函数都返回具有不同版本信息的字典：

• ['version']：压缩版本字符串，使用选定的样式呈现。这是项目版本字符串最常用的值。默认的 "pep440" 样式会生成类似0.11, 0.11+2.g1076c97或的字符串0.11+2.g1076c97.dirty。有关替代样式，请参阅下面的“样式”部分。

• ['full-revisionid']: 详细的修订标识符。对于 Git，这是完整的 SHA1 提交 ID，例如“1076c978a8d3cfc70f408fe5974aa6c092c949ac”。

• ['date']：最近一次提交的日期和时间HEAD。对于 Git，它是 ISO 8601 格式的提交日期。如果日期不可用，这将为 None。

• ['dirty']：一个布尔值，如果树有未提交的更改，则为 True。请注意，这仅在 VCS 结帐中运行时才准确，否则可能为 False 或 None

• ['error']：如果无法计算版本字符串，则将其设置为描述问题的字符串，否则将为无。如果设置了此项，则在 setup.py 中抛出异常可能很有用，以避免例如创建带有“未知”版本字符串的 tarball。

有些变体比其他变体更有用。包含full-revisionid在错误报告中应该允许开发人员重建正在测试的确切代码（或指示应该与开发人员共享的本地更改的存在）。version适合在“关于”框或 CLI --version输出中显示：它可以很容易地与发行说明和各种发行版中修复的错误列表进行比较。

安装程序将以下文本添加到您__init__.py以放置基本版本YOURPROJECT.__version__：

from ._version import get_versions
__version__ = get_versions()['version']
del get_versions

风格

setup.cfgstyle=配置控制如何将 VCS 信息呈现为版本字符串。

默认样式“pep440”生成一个符合 PEP440 的字符串，等于实际版本的无前缀标签名称，并包含一个额外的“本地版本”部分，其中包含更多关于中间版本的详细信息。对于 Git，这是 TAG[+DISTANCE.gHEX[.dirty]] ，使用来自git describe --tags --dirty --always. 例如“0.11+2.g1076c97.dirty”表示该树类似于“1076c97”提交但有未提交的更改（“.dirty”），并且此提交是“0.11”之外的两个修订版（“+2”） “ 标签。对于已发布的软件（完全等于已知标签），标识符将仅包含剥离的标签，例如“0.11”。

其他样式可供选择。有关说明，请参见Versioneer 源代码树中的details.md。

调试

Versioneer 试图避免致命错误：如果出现问题，它往往会返回“0+unknown”的版本。要调查问题，请运行setup.py version，它将以详细模式运行版本查找代码，并显示完整的内容get_versions()（包括error字符串，这可能有助于识别出了什么问题）。

已知限制

已知某些情况会导致 Versioneer 出现问题。这详细说明了最重要的那些。更多可以在 Github 问题页面上找到。

子项目

Versioneer对setup.py不在根目录中的源代码树的支持有限（例如setup.py，.git/不是同级）。可能不在根目录中的两个常见原因是：setup.py

• 包含多个子项目的源代码树，例如 Buildbot，其中包含“主”和“从”子项目，每个子项目都有自己的setup.py、 setup.cfg和tox.ini。像这样的项目会产生多个 PyPI 发行版（并上传多个可独立安装的 tarball）。
• 源代码树的主要目的是包含一个 C 库，但它也在子目录中提供与 Python（可能还有其他语言）的绑定。

Versioneer 将.git在父目录中查找，并且大多数操作应该得到正确的版本字符串。但是pip，并且setuptools存在经常导致pip install .子项目目录无法找到正确版本字符串的错误和实现细节（因此它通常默认为0+unknown）。

pip install --editable .应该可以正常工作。setup.py install也可能工作。

已知 Pip-8.1.1 存在此问题，但希望它会在以后的版本中得到修复。

Bug #38正在跟踪这个问题。PR #61中的讨论 更详细地描述了 Versioneer 方面的问题。 pip PR#3176和 pip PR#3615包含改进 pip 以使 Versioneer 正常工作的工作。

Versioneer-0.16 和更早的版本只查找 ..git旁边的目录 setup.cfg，因此这些版本完全不支持子项目。

使用 setuptools <= 18.5 进行可编辑安装

setup.py develop并pip install --editable .允许您将项目安装到 virtualenv 一次，然后继续编辑源代码（和测试），而无需在每次更改后重新安装。

“入口点脚本” ( setup(entry_points={"console_scripts": ..})) 是一种指定可执行脚本的便捷方式，该脚本应与 python 包一起安装。

使用现代设置工具时，这些都按预期工作。但是，在使用 setuptools-18.5 或更早版本时，某些操作 pkg_resources.DistributionNotFound在运行入口点脚本时会导致错误，必须通过重新安装包来解决。当安装使用一个版本时会发生这种情况，然后在签出不同版本时重新生成 egg_info 数据。许多 setup.py 命令会导致 egg_info 被重建（包括sdist、wheel和安装到不同的 virtualenv 中），所以这可能令人惊讶。

错误 #83描述了这一问题，但升级到较新版本的 setuptools 应该可以解决它。

更新版本控制

要将您的项目升级到新版本的 Versioneer，请执行以下操作：

• 安装新的 Versioneer（pip install -U versioneer或等效）
• 编辑setup.cfg并pyproject.toml在必要时包括发行说明中指示的任何新配置设置。有关详细信息，请参阅升级。
• 在源代码树中重新运行versioneer install --[no-]vendor，以替换 SRC/_version.py
• 提交任何更改的文件

未来发展方向

该工具旨在使其轻松扩展到其他版本控制系统：所有 VCS 特定组件都位于单独的目录中，例如 src/git/ 。顶层versioneer.py脚本是通过运行 make-versioneer.py 从这些组件中组装而成的。将来，make-versioneer.py 将采用 VCS 名称作为参数，并将构造一个 versioneer.py特定于给定 VCS 的版本。它还可能采用当前在安装期间通过编辑 setup.py 手动提供的配置参数。或者，它可能会走向另一个方向，包括来自所有受支持的 VCS 系统的代码，从而减少中间脚本的数量。

类似项目

• setuptools_scm - 非供应商的构建时依赖项
• minver - versioneer 的轻量级重新实现
• versioningit - 基于 PEP 518 的 setuptools 插件

执照

为了使 Versioneer 更易于嵌入，它的所有代码都专用于公共领域。_version.py它创建的也属于公共领域。具体来说，两者都是根据知识共享“公共领域奉献”许可 (CC0-1.0) 发布的，如 https://creativecommons.org/publicdomain/zero/1.0/中所述。