tessl/pypi-dunamai

Dynamic version generation from version control system tags supporting multiple VCS and versioning standards.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Dunamai

Name: tessl/pypi-dunamai
Author: tessl

A Python library and command-line tool for generating dynamic, standards-compliant version strings from version control system tags. Dunamai enables automated version identification for CI/CD pipelines and nightly builds by deriving version information directly from VCS tags, eliminating manual version management.

# Type imports for API documentation
import datetime
from pathlib import Path
from typing import Set, Optional, Union, Tuple, Sequence, Callable

Package Information

Package Name: dunamai
Package Type: pypi
Language: Python
Installation: pip install dunamai

Core Imports

import dunamai

Common import patterns:

from dunamai import Version, Style, Vcs

For specific functionality:

from dunamai import (
    Version, Style, Vcs,
    get_version, check_version, bump_version,
    serialize_pep440, serialize_semver, serialize_pvp
)

Basic Usage

from dunamai import Version, Style

# Auto-detect VCS and get version from current repository
version = Version.from_any_vcs()
print(version.serialize())  # e.g., "1.2.3.post7.dev0+g29045e8"

# Get version from specific VCS
version = Version.from_git()
print(version.serialize(style=Style.SemVer))  # e.g., "1.2.3-post.7+g29045e8"

# Create version manually
version = Version("1.2.3", stage=("rc", 1), distance=5, commit="g29045e8")
print(version.serialize())  # "1.2.3rc1.post5.dev0+g29045e8"

# Validate version strings
from dunamai import check_version, Style
check_version("1.2.3", Style.SemVer)  # Validates against Semantic Versioning

Architecture

Dunamai provides a comprehensive version management system with several key components:

Version Control Integration: Supports 7 VCS systems (Git, Mercurial, Darcs, Subversion, Bazaar, Fossil, Pijul)
Multiple Version Standards: PEP 440, Semantic Versioning, Haskell Package Versioning Policy
Dynamic Generation: Extracts version from VCS tags with distance and commit information
CLI Tool: Command-line interface for static version generation in any language project
Flexible Serialization: Custom format strings and built-in standard formats

Capabilities

Version Creation and Parsing

Core functionality for creating Version objects from VCS repositories or parsing existing version strings.

class Version:
    def __init__(
        self,
        base: str,
        *,
        stage: Optional[Tuple[str, Optional[int]]] = None,
        distance: int = 0,
        commit: Optional[str] = None,
        dirty: Optional[bool] = None,
        tagged_metadata: Optional[str] = None,
        epoch: Optional[int] = None,
        branch: Optional[str] = None,
        timestamp: Optional[datetime.datetime] = None,
        concerns: Optional[Set[Concern]] = None,
        vcs: Vcs = Vcs.Any
    ) -> None

@classmethod
def parse(cls, version: str, pattern: Union[str, Pattern] = Pattern.Default) -> "Version"

Version Creation and Parsing

VCS Integration

Extract version information from any supported version control system with automatic detection or explicit VCS selection.

@classmethod
def from_any_vcs(
    cls,
    pattern: Union[str, Pattern] = Pattern.Default,
    latest_tag: bool = False,
    tag_dir: str = "tags",
    tag_branch: Optional[str] = None,
    full_commit: bool = False,
    strict: bool = False,
    path: Optional[Path] = None,
    pattern_prefix: Optional[str] = None,
    ignore_untracked: bool = False,
    commit_length: Optional[int] = None,
) -> "Version"

@classmethod
def from_git(cls, **kwargs) -> "Version"

@classmethod  
def from_mercurial(cls, **kwargs) -> "Version"

VCS Integration

Version Serialization

Convert Version objects to standards-compliant version strings with extensive formatting options.

def serialize(
    self,
    metadata: Optional[bool] = None,
    dirty: bool = False,
    format: Optional[Union[str, Callable[["Version"], str]]] = None,
    style: Optional[Style] = None,
    bump: bool = False,
    tagged_metadata: bool = False,
    commit_prefix: Optional[str] = None,
    escape_with: Optional[str] = None,
) -> str

def serialize_pep440(
    base: str,
    stage: Optional[str] = None,
    revision: Optional[int] = None,
    post: Optional[int] = None,
    dev: Optional[int] = None,
    epoch: Optional[int] = None,
    metadata: Optional[Sequence[Union[str, int]]] = None,
) -> str

Version Serialization

Utility Functions

Helper functions for version manipulation, validation, and dynamic version detection.

def bump_version(base: str, index: int = -1, increment: int = 1) -> str

def check_version(version: str, style: Style = Style.Pep440) -> None

def get_version(
    name: str,
    first_choice: Optional[Callable[[], Optional[Version]]] = None,
    third_choice: Optional[Callable[[], Optional[Version]]] = None,
    fallback: Version = Version("0.0.0"),
    ignore: Optional[Sequence[Version]] = None,
    parser: Callable[[str], Version] = Version,
) -> Version

Utility Functions

Command Line Interface

Command-line tool for version generation and validation in any programming language.

# Auto-detect VCS and generate version
dunamai from any

# Use specific VCS with custom format
dunamai from git --format "v{base}+{distance}.{commit}"

# Validate version strings
dunamai check 1.2.3 --style semver

Command Line Interface

Types

class Style(Enum):
    Pep440 = "pep440"
    SemVer = "semver" 
    Pvp = "pvp"

class Vcs(Enum):
    Any = "any"
    Git = "git"
    Mercurial = "mercurial"
    Darcs = "darcs"
    Subversion = "subversion"
    Bazaar = "bazaar"
    Fossil = "fossil"
    Pijul = "pijul"

class Pattern(Enum):
    Default = "default"
    DefaultUnprefixed = "default-unprefixed"

class Concern(Enum):
    ShallowRepository = "shallow-repository"