Dunamai: Dynamic Version Generation

1.26.1 · active · verified Mon Apr 06

Dunamai is a Python 3.5+ library and command-line tool for producing dynamic, standards-compliant version strings, derived from tags in your version control system (Git, Mercurial, Darcs, Subversion, Bazaar, Fossil, Pijul). It facilitates uniquely identifying nightly or per-commit builds in continuous integration and simplifying releases by creating a tag. It supports various version styles like PEP 440 and Semantic Versioning, or custom formats. Dunamai, currently at version 1.26.1, maintains an active development and release cadence.

Warnings

breaking The `Version.__lt__` comparison logic was fixed in v1.23.1. Prior to this, `Version.__lt__` incorrectly checked if *all* fields were less, rather than using proper field precedence for version ordering. This could lead to incorrect comparisons between `Version` instances.
Fix: Upgrade to `dunamai` v1.23.1 or newer to ensure correct version comparison behavior.
gotcha Dunamai requires access to the full version history to accurately find tags and compute distance. CI systems often perform shallow clones by default, which can prevent Dunamai from determining the correct version.
Fix: Ensure your CI environment performs a full clone. For GitHub Actions, use `actions/checkout@v3` with `fetch-depth: 0`. For GitLab, set `GIT_DEPTH` to `0`.
gotcha Setting the `GIT_TRACE` environment variable can cause `Version.from_git` to fail due to unexpected output from Git commands.
Fix: Upgrade to `dunamai` v1.23.2 or newer, which includes a fix for this issue. Alternatively, ensure `GIT_TRACE` is not set when running `dunamai`.
gotcha The `highest_tag` argument, intended to select the numerically highest version tag, was ignored in `Version.from_any_vcs()` and related functions.
Fix: Upgrade to `dunamai` v1.26.1 or newer to correctly utilize the `highest_tag` functionality.
gotcha Using lightweight Git tags (instead of annotated tags) or having an initial commit that is both tagged and empty can lead to unreliable tag detection and sorting, as Git does not store creation times for lightweight tags and has reporting issues with empty, tagged initial commits.
Fix: Prefer annotated tags (`git tag -a`) over lightweight tags. Avoid tagging the initial empty commit (created with `--allow-empty`).

Install

pip install dunamai Install stable version

Imports

Version
```
from dunamai import Version
```
Style
```
from dunamai import Style
```
Pattern
```
from dunamai import Pattern
```
Used for predefined version tag patterns.

Quickstart

This example demonstrates how to retrieve and serialize a dynamic version string from any detected VCS. It includes options for fallback versions and strict mode, which are crucial for robust integration in varied environments like CI/CD pipelines. The output can be formatted according to different versioning styles.

import os
from dunamai import Version

# In a Git repository with tag v0.1.0 and some commits after it
try:
    version = Version.from_any_vcs(
        # Optional: Specify a fallback version if no VCS is found or no tags match.
        # Defaults to '0.0.0' if not strict, or raises an error if strict.
        fallback=os.environ.get("DUNAMAI_FALLBACK_VERSION", "0.0.0"),
        # Optional: Set strict=True to raise an error if a version cannot be determined.
        # Default is False, which may use fallback.
        strict=bool(os.environ.get("DUNAMAI_STRICT", "").lower() == "true"),
    )
    # Prints a PEP 440 compliant version like "0.1.0.post7.dev0+g29045e8"
    print(f"Current version: {version.serialize()}")
    # Or a Semantic Versioning compliant string like "0.1.0-post.7"
    print(f"Semantic version: {version.serialize(style='semver', metadata=False)}")
except RuntimeError as e:
    print(f"Could not determine version: {e}")
    # Handle cases where version cannot be determined (e.g., not in a VCS repo)

view raw JSON →