dun
dunamai
pypi i dunamai
dun

dunamai

Dynamic versioning library and CLI

by Matthew Kennerly

1.12.0 (see all)License:MIT
pypi i dunamai
Readme

Dunamai

Version License: MIT

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. This facilitates uniquely identifying nightly or per-commit builds in continuous integration and releasing new versions of your software simply by creating a tag.

Dunamai is also available as a GitHub Action.

Features

Usage

Installation

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

Library

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"

The serialize() method gives you an opinionated, PEP 440-compliant default that ensures that versions for untagged commits are compatible with Pip's --pre flag. The individual parts of the version are also available for you to use and inspect as you please:

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"

Tips

By default, the "v" prefix on the tag is required, unless you specify a custom tag pattern. You can either write a regular expression:

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

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

...or use a named preset:

$ dunamai from any --pattern default-unprefixed
from dunamai import Version, Pattern

version = Version.from_any_vcs(pattern=Pattern.DefaultUnprefixed)

Comparison to Versioneer

Versioneer is another great library for dynamic versions, but there are some design decisions that prompted the creation of Dunamai as an alternative:

  • Versioneer requires a setup.py file to exist, or else versioneer install will fail, rendering it incompatible with non-setuptools-based projects such as those using Poetry or Flit. Dunamai can be used regardless of the project's build system.
  • Versioneer has a CLI that generates Python code which needs to be committed into your repository, whereas Dunamai is just a normal importable library with an optional CLI to help statically include your version string.
  • Versioneer produces the version as an opaque string, whereas Dunamai provides a Version class with discrete parts that can then be inspected and serialized separately.
  • Versioneer provides customizability through a config file, whereas Dunamai aims to offer customizability through its library API and CLI for both scripting support and use in other libraries.

Integration

  • Setting a __version__ statically:

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

    Or dynamically (but Dunamai becomes a runtime dependency):

    # your_library/__init__.py
    import dunamai as _dunamai
    __version__ = _dunamai.get_version("your-library", third_choice=_dunamai.Version.from_any_vcs).serialize()
    
  • setup.py (no install-time dependency on Dunamai as long as you use wheels):

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

    Or you could use a static inclusion approach as in the prior example.

  • Poetry:

    $ poetry version $(dunamai from any)
    

    Or you can use the poetry-dynamic-versioning plugin.

Other notes

  • When using Git, the initial commit must not be both tagged and empty (i.e., created with --allow-empty). This is related to a reporting issue in Git. For more info, click here.

Development

This project is managed using Poetry. Development requires Python 3.6+ because of Black.

  • If you want to take advantage of the default VSCode integration, then first configure Poetry to make its virtual environment in the repository:
    poetry config virtualenvs.in-project true
    
  • After cloning the repository, activate the tooling:
    poetry install
    poetry run pre-commit install
    
  • Run unit tests:
    poetry run pytest --cov
    poetry run tox
    

GitHub Stars

158

LAST COMMIT

5mos ago

MAINTAINERS

1

CONTRIBUTORS

12

OPEN ISSUES

0

OPEN PRs

0
VersionTagPublished
1.12.0
3mos ago
1.11.1
4mos ago
1.11.0
5mos ago
1.10.0
5mos ago
No alternatives found
No tutorials found
Add a tutorial