dunamai

Dunamai can be used to inject version strings into various build systems and Python packages.

Static Inclusion (Recommended for CI)

Generate a _version.py file during your build process to avoid runtime dependencies:

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

Then import it in your __init__.py:

from your_library._version import __version__

Dynamic Inclusion (Runtime Dependency)

Import Dunamai directly in your __init__.py. Note that this makes Dunamai a required dependency at runtime:

import dunamai as _dunamai
__version__ = _dunamai.get_version("your-library", third_choice=_dunamai.Version.from_any_vcs).serialize()

Integration with Build Tools

• setuptools (setup.py):

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

• Poetry: Use the CLI to set the version during build, or use the poetry-dynamic-versioning plugin:

  poetry version $(dunamai from any)

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

The dunamai from command is used to generate a dynamic version based on a Version Control System (VCS). You can either let dunamai auto-detect the VCS or specify a particular one.

Supported VCS types:

• any (auto-detects)
• git
• mercurial
• darcs
• subversion
• bazaar
• fossil
• pijul

Commonly used options:

• --format FORMAT: Define a custom output format using available substitutions.
• --style {pep440,semver,pvp}: Use a preconfigured output format (defaults to pep440).
• --pattern PATTERN: Use a regular expression to match the version source. The pattern must include a base capture group.
• --bump: Increment the last part of the version base (or the revision if a stage is set).
• --dirty: Include a dirty flag if the repository has uncommitted changes.
• --path PATH: Specify a directory to inspect instead of the current working directory.

# Auto-detect VCS and generate version
dunamai from any

# Generate version specifically from Git with a custom format
dunamai from git --format "{base}-{distance}"

# Generate version from a specific path
dunamai from git --path /path/to/repo

Import Version and Style to programmatically generate and inspect version strings.

Generating Versions

• Version.from_git(): Specifically targets Git repositories.
• Version.from_any_vcs(): Automatically detects the VCS.

Serializing Versions

Use the .serialize() method to convert the version object to a string. By default, it provides a PEP 440-compliant string. You can pass arguments to customize the output:

• metadata=False: Excludes metadata.
• dirty=True: Includes a .dirty suffix if there are uncommitted changes.
• style=Style.SemVer: Uses Semantic Versioning formatting.

Inspecting Version Components

The Version object exposes discrete parts of the version for inspection:

• base: The core version (e.g., 0.1.0).
• stage: The release stage (e.g., rc).
• revision: The revision number.
• distance: Number of commits since the last tag.
• commit: The commit hash.
• dirty: Boolean indicating uncommitted changes.
• tagged_metadata: Metadata attached to the tag (e.g., linux from v0.1.0+linux).

from dunamai import Version, Style

# Generate version from Git
version = Version.from_git()
print(version.serialize())  # e.g., "0.1.0"

# Generate version from any VCS with complex state
version = Version.from_any_vcs()
print(version.serialize())                      # "0.1.0rc5.post44.dev0+g644252b"
print(version.serialize(metadata=False))          # "0.1.0rc5.post44.dev0"
print(version.serialize(dirty=True))            # "0.1.0rc5.post44.dev0+g644252b.dirty"
print(version.serialize(style=Style.SemVer))    # "0.1.0-rc.5.post.44+g6442b"

# Inspecting parts
print(version.base)             # "0.1.0"
print(version.distance)         # 44
print(version.commit)           # "g644252b"

The Dunamai CLI can automatically detect your version control system (Git, Mercurial, Darcs, Subversion, Bazaar, Fossil, or Pijul) and generate a version string based on your tags.

Basic Commands

• Auto-detect VCS: dunamai from any generates a version based on the detected VCS.
• Explicit VCS and Style: dunamai from <vcs> --style <style> allows you to specify the system and a versioning style (e.g., semver, pep440, haskell).
• Custom Formats: Use --format "<format>" to define a custom string using available substitutions.
• Bumping Versions: Use --bump to frame the version in terms of progress toward the next release rather than distance from the last one.
• Validation: Use dunamai check <version> --style <style> to validate if a specific version string conforms to a style.

# Auto-detect and generate version
$ dunamai from any
0.2.0.post7.dev0+g29045e8

# Explicit VCS and SemVer style
$ dunamai from git --no-metadata --style semver
0.2.0-post.7

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

# Bump version (progress toward next release)
$ dunamai from any --bump
0.2.1.dev7+g29045e8

# Validate a version string
$ dunamai check 0.01.0 --style semver

The Version.serialize() method allows you to output the version string in various standard formats. You can specify the format using the Style enum or a custom format string/callback.

Supported Styles (Style enum):

• Style.Pep440: Python's PEP 440 standard.
• Style.SemVer: Semantic Versioning.
• Style.Pvp: Haskell Package Versioning Policy.

Custom Formatting: If you provide a format string, you can use placeholders like {base}, {stage}, {revision}, {distance}, {commit}, {dirty}, {tagged_metadata}, {epoch}, {branch}, {branch_escaped}, {timestamp}, {major}, {minor}, and {patch}.

from dunamai import Version, Style

version = Version.parse("v1.2.3")

# Use built-in styles
pep440_str = version.serialize(style=Style.Pep440)
semver_str = version.serialize(style=Style.SemVer)

# Use a custom format string
custom_str = version.serialize(format="Release-{major}.{minor}") # e.g., "Release-1.2"