Dunamai

Dunamai 是一个Python 3.5+库和命令行工具，用于生成动态、符合标准的版本字符串，这些字符串来自您的版本控制系统。这有助于在持续集成中唯一地标识夜间或按提交构建，并通过创建标签轻松发布您软件的新版本。

Dunamai 还可用作 GitHub操作。

功能

• 版本控制系统支持
  • Git（推荐使用2.7.0+，但版本低至1.8.2.3也能工作，功能可能有所减少）
  • Mercurial
  • Darcs
  • Subversion
  • Bazaar
  • Fossil
  • Pijul
• 版本样式
  • PEP 440
  • 语义版本控制
  • Haskell软件包版本控制策略
  • 自定义输出格式
• 可用于任何编程语言的项目。对于Python，这意味着您不需要setup.py。

使用方法

安装

pip install dunamai

CLI

# Suppose you are on commit g29045e8, 7 commits after the v0.2.0 tag.

# Auto-detect the version control system and generate a version:
$ dunamai from any
0.2.0.post7.dev0+g29045e8

# Or use an explicit VCS and style:
$ dunamai from git --no-metadata --style semver
0.2.0-post.7

# Custom formats:
$ dunamai from any --format "v{base}+{distance}.{commit}"
v0.2.0+7.g29045e8

# If you'd prefer to frame the version in terms of progress toward the next
# release rather than distance from the latest one, you can bump it:
$ dunamai from any --bump
0.2.1.dev7+g29045e8

# Validation of custom formats:
$ dunamai from any --format "v{base}" --style pep440
Version 'v0.2.0' does not conform to the PEP 440 style

# Validate your own freeform versions:
$ dunamai check 0.01.0 --style semver
Version '0.01.0' does not conform to the Semantic Versioning style

# More info:
$ dunamai --help
$ dunamai from --help
$ dunamai from git --help

库

from dunamai import Version, Style

# Let's say you're on commit g644252b, which is tagged as v0.1.0.
version = Version.from_git()
assert version.serialize() == "0.1.0"

# Let's say there was a v0.1.0rc5 tag 44 commits ago
# and you have some uncommitted changes.
version = Version.from_any_vcs()
assert version.serialize() == "0.1.0rc5.post44.dev0+g644252b"
assert version.serialize(metadata=False) == "0.1.0rc5.post44.dev0"
assert version.serialize(dirty=True) == "0.1.0rc5.post44.dev0+g644252b.dirty"
assert version.serialize(style=Style.SemVer) == "0.1.0-rc.5.post.44+g644252b"

serialize() 方法提供了一个具有偏见的、符合PEP 440默认设置的版本，确保未标记提交的版本与Pip的--pre标志兼容。版本的不同部分也供您使用和检查。

assert version.base == "0.1.0"
assert version.stage == "rc"
assert version.revision == 5
assert version.distance == 44
assert version.commit == "g644252b"
assert version.dirty is True

# Available if the latest tag includes metadata, like v0.1.0+linux:
assert version.tagged_metadata == "linux"

小贴士

默认情况下，需要标签上的“v”前缀，除非您指定自定义标签模式。您可以选择编写一个正则表达式

• 控制台

  $ dunamai from any --pattern "(?P<base>\d+\.\d+\.\d+)"
  

• Python

  from dunamai import Version
  version = Version.from_any_vcs(pattern=r"(?P<base>\d+\.\d+\.\d+)")
  

...或使用命名预设

• 控制台

  $ dunamai from any --pattern default-unprefixed
  

• Python

  from dunamai import Version, Pattern
  version = Version.from_any_vcs(pattern=Pattern.DefaultUnprefixed)
  

您也可以保留默认模式，只需指定一个前缀。例如，这将匹配类似于 some-package-v1.2.3 的标签。

• 控制台

  $ dunamai from any --pattern-prefix some-package-
  

• Python

  from dunamai import Version
  version = Version.from_any_vcs(pattern_prefix="some-package-")
  

版本控制系统存档

有时，您可能只能访问存储库的存档（例如，zip 文件）而没有完整的历史记录。Dunamai 在这些情况下仍可以检测到版本。

• 对于 Git，您可以为 Dunamai 配置 git archive 以生成包含一些元数据的文件。

  在您的存储库根目录中添加一个 .git_archival.json 文件，内容如下

  {
    "hash-full": "$Format:%H$",
    "hash-short": "$Format:%h$",
    "timestamp": "$Format:%cI$",
    "refs": "$Format:%D$",
    "describe": "$Format:%(describe:tags=true,match=v[0-9]*)$"
  }
  

  将此行添加到您的 .gitattributes 文件中。如果您还没有这个文件，请将其添加到存储库的根目录。

  .git_archival.json  export-subst
  

• 对于 Mercurial，Dunamai 会检测并使用由 hg archive 创建的 .hg_archival.txt 文件。如果存在，它还会识别 .hgtags。

自定义格式

以下是自定义格式的可用替换。如果您有一个类似 v9!0.1.2-beta.3+other 的标签，那么

• {base} = 0.1.2
• {stage} = beta
• {revision} = 3
• {distance} 是自上次提交以来的提交数
• {commit} 是提交哈希（默认为短形式，除非您使用 --full-commit）
• {dirty} 如果您有未提交的修改文件，则扩展为 "dirty" 或 "clean"。
• {tagged_metadata} = other
• {epoch} = 9
• {branch} = feature/foo
• {branch_escaped} = featurefoo
• {timestamp} 的格式为 YYYYmmddHHMMSS，为 UTC 格式。

如果您指定了替换，其值将始终包含在输出中。对于条件格式，您可以进行如下操作（Bash）

distance=$(dunamai from any --format "{distance}")
if [ "$distance" = "0" ]; then
    dunamai from any --format "v{base}"
else
    dunamai from any --format "v{base}+{distance}.{dirty}"
fi

与 Versioneer 的比较

Versioneer 是另一个用于动态版本的优秀库，但有一些设计决策促使创建 Dunamai 作为替代方案。

• Versioneer 需要存在 setup.py 文件，否则 versioneer install 将失败，使其与非 setuptools 基于的项目（如使用 Poetry 或 Flit 的项目）不兼容。Dunamai 可以在项目构建系统无关的情况下使用。
• Versioneer 有一个 CLI，它生成需要提交到您的存储库中的 Python 代码，而 Dunamai 仅仅是一个普通的可导入库，它有一个可选的 CLI，可以帮助您静态地包含版本字符串。
• Versioneer 生成的版本是一个不透明的字符串，而 Dunamai 提供了一个具有离散部分的 Version 类，然后可以单独检查和序列化这些部分。
• Versioneer 通过配置文件提供可定制性，而 Dunamai 通过其库 API 和 CLI（用于脚本支持和在其他库中使用）提供可定制性。

集成

• 静态设置 __version__

  $ echo "__version__ = '$(dunamai from any)'" > your_library/_version.py
  

  # your_library/__init__.py
  from your_library._version import __version__
  

  或动态（但 Dunamai 成为运行时依赖项）

  # your_library/__init__.py
  import dunamai as _dunamai
  __version__ = _dunamai.get_version("your-library", third_choice=_dunamai.Version.from_any_vcs).serialize()
  

• setup.py（只要您使用 wheels，则无需安装时依赖 Dunamai）

  from setuptools import setup
  from dunamai import Version
  
  setup(
      name="your-library",
      version=Version.from_any_vcs().serialize(),
  )
  

  或者您可以使用与先前列举的示例相同的静态包含方法。

• Poetry:

  $ poetry version $(dunamai from any)
  

  或者您可以使用 poetry-dynamic-versioning 插件。

其他说明

• Dunamai 需要访问完整的版本历史记录以查找标签和计算距离。如果您的 CI 系统默认进行浅克隆，请小心。

  • 对于 GitHub 工作流程，调用 actions/checkout@v3 并带有 fetch-depth: 0。
  • 对于 GitLab 管道，设置 GIT_DEPTH 变量为 0。
  • 对于 Docker 构建，将 VCS 历史记录（例如，.git 文件夹）复制到容器中。

  对于 Git，您还可以通过指定标签的远程分支来避免完全克隆（例如，--tag-branch remotes/origin/master）。

• 在使用Git时，请记住轻量级标签不会存储它们的创建时间。因此，如果一个提交有多个轻量级标签，我们无法可靠地确定哪一个应该被认为是最新的。解决方案是使用注解标签。

• 在使用Git时，初始提交**不能**同时打标签且为空（即使用--allow-empty创建）。这与Git中的一个报告问题有关。更多信息，请点击这里。