单一来源项目版本

Single-sourcing the Project Version

Page Status:

Complete

Last Reviewed:

2024-10-07

许多 Python 分发包 发布单个 Python 导入包，并希望该导入包的运行时 __version__ 属性报告与 importlib.metadata.version() 所报告的分发包版本号相同（如 在运行时访问版本信息 所述）。

此外，通常希望这些版本信息来自版本控制系统的 标签 （例如 v1.2.3），而不是手动更新源代码中的版本号。

一些项目可能选择容忍这种数据条目重复，并依赖自动化测试确保这些不同的版本值不会发生偏离。

另一种选择是，项目选择的构建系统可能提供一种方式来定义版本号的唯一“真相源”。

一般来说，选项如下：

  1. 如果代码在版本控制系统（VCS）中，例如 Git，那么可以从 VCS 提取版本号。

  2. 版本号可以硬编码到 pyproject.toml 文件中——然后构建系统可以将其复制到可能需要版本号的其他位置。

  3. 版本号可以硬编码到源代码中——可以放在一个专门的文件中，例如 _version.txt`（该文件必须作为项目源代码分发包的一部分进行打包），或者作为某个模块中的属性，例如 :file:`__init__.py。构建系统随后可以在构建时从运行时位置提取版本号。

请查阅构建系统的文档以了解它们推荐的方式。

当目标是确保分发包及其关联的导入包共享相同的版本号时，建议项目包括一个自动化测试用例，确保 import_name.__version__ 和 importlib.metadata.version("dist-name") 报告相同的版本值（注意：对于许多项目， import_name 和 dist-name 将是相同的名称）。

Many Python distribution packages publish a single Python import package where it is desired that the runtime __version__ attribute on the import package report the same version specifier as importlib.metadata.version() reports for the distribution package (as described in 在运行时访问版本信息).

It is also frequently desired that this version information be derived from a version control system tag (such as v1.2.3) rather than being manually updated in the source code.

Some projects may choose to simply live with the data entry duplication, and rely on automated testing to ensure the different values do not diverge.

Alternatively, a project's chosen build system may offer a way to define a single source of truth for the version number.

In general, the options are:

  1. If the code is in a version control system (VCS), such as Git, then the version can be extracted from the VCS.

  2. The version can be hard-coded into the pyproject.toml file -- and the build system can copy it into other locations it may be required.

  3. The version string can be hard-coded into the source code -- either in a special purpose file, such as _version.txt (which must then be shipped as part of the project's source distribution package), or as an attribute in a particular module, such as __init__.py. The build system can then extract it from the runtime location at build time.

Consult your build system's documentation for their recommended method.

When the intention is that a distribution package and its associated import package share the same version, it is recommended that the project include an automated test case that ensures import_name.__version__ and importlib.metadata.version("dist-name") report the same value (note: for many projects, import_name and dist-name will be the same name).

构建系统版本处理

Build System Version Handling

以下是一些用于处理版本字符串的构建系统文档的链接。

The following are links to some build system's documentation for handling version strings.