tessl/pypi-dunamai

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

—

Pending

Overview

Eval results

Files

Version Creation and Parsing

Name: tessl/pypi-dunamai
Author: tessl

Core functionality for creating Version objects from components or parsing existing version strings into structured objects.

Capabilities

Version Object Creation

Create a Version object with complete version information including base version, pre-release stage, distance from tags, and VCS metadata.

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[dt.datetime] = None,
        concerns: Optional[Set[Concern]] = None,
        vcs: Vcs = Vcs.Any
    ) -> None

Parameters:

base: Release segment like "1.2.3"
stage: Pre-release stage as (stage_name, revision) tuple (e.g., ("rc", 1))
distance: Number of commits since the last tag
commit: Commit hash/identifier
dirty: True if working directory has uncommitted changes
tagged_metadata: Metadata from the tag itself
epoch: PEP 440 epoch number
branch: Current branch name
timestamp: Commit timestamp as datetime object
concerns: Set of version concerns/warnings
vcs: Source version control system

Usage Examples:

from dunamai import Version, Vcs
import datetime as dt

# Basic version
version = Version("1.2.3")

# Pre-release version
version = Version("1.2.3", stage=("rc", 1))

# Development version with VCS info
version = Version(
    "1.2.3",
    stage=("dev", None),
    distance=7,
    commit="g29045e8",
    dirty=True,
    branch="feature/new-api",
    vcs=Vcs.Git
)

# Version with epoch and metadata
version = Version(
    "2.0.0",
    epoch=1,
    tagged_metadata="linux",
    timestamp=dt.datetime.now()
)

Version String Parsing

Parse existing version strings into Version objects using pattern matching and heuristics.

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

Parameters:

version: Version string to parse (e.g., "v1.2.3-rc1+g29045e8.dirty")
pattern: Regular expression pattern or preset Pattern enum for parsing

Returns: Version object with parsed components

Usage Examples:

from dunamai import Version, Pattern

# Parse with default pattern (supports 'v' prefix)
version = Version.parse("v1.2.3-rc1.post7.dev0+g29045e8")
print(version.base)      # "1.2.3"
print(version.stage)     # "rc"
print(version.revision)  # 1
print(version.distance)  # 7
print(version.commit)    # "g29045e8"

# Parse without 'v' prefix
version = Version.parse("1.2.3-alpha.2", Pattern.DefaultUnprefixed)

# Parse with custom pattern
custom_pattern = r"^(?P<base>\d+\.\d+\.\d+)(-(?P<stage>\w+)\.(?P<revision>\d+))?$"
version = Version.parse("1.2.3-beta.5", custom_pattern)

Version Properties

Access individual components of a Version object.

Properties:

base: str - Release segment
stage: Optional[str] - Pre-release stage name
revision: Optional[int] - Pre-release revision number
distance: int - Commits since last tag
commit: Optional[str] - Commit identifier
dirty: Optional[bool] - Uncommitted changes flag
tagged_metadata: Optional[str] - Tag metadata
epoch: Optional[int] - PEP 440 epoch
branch: Optional[str] - Branch name
timestamp: Optional[datetime] - Commit timestamp
concerns: Optional[Set[Concern]] - Version concerns
vcs: Vcs - Source VCS

Usage Examples:

from dunamai import Version

version = Version("1.2.3", stage=("rc", 1), distance=5, commit="g29045e8")

print(f"Base version: {version.base}")           # "1.2.3"
print(f"Pre-release: {version.stage}")           # "rc"
print(f"Revision: {version.revision}")           # 1
print(f"Distance: {version.distance}")           # 5
print(f"Commit: {version.commit}")               # "g29045e8"

# Check if this is a development version
is_dev = version.distance > 0
print(f"Development version: {is_dev}")          # True

Version Comparison

Compare Version objects using standard comparison operators.

def __eq__(self, other: Any) -> bool
def __lt__(self, other: Any) -> bool

Usage Examples:

from dunamai import Version

v1 = Version("1.2.3")
v2 = Version("1.2.4") 
v3 = Version("1.2.3", stage=("rc", 1))

print(v1 < v2)    # True
print(v1 == v3)   # False (different stage)
print(v3 < v1)    # True (pre-release < release)

# Sort versions
versions = [
    Version("1.2.3"),
    Version("1.2.3", stage=("rc", 1)),
    Version("1.2.4")
]
sorted_versions = sorted(versions)

Version String Representation

Convert Version objects to string representations.

def __str__(self) -> str
def __repr__(self) -> str

Usage Examples:

from dunamai import Version

version = Version("1.2.3", stage=("rc", 1), distance=5)

print(str(version))    # Uses serialize() - "1.2.3rc1.post5.dev0"
print(repr(version))   # Detailed representation showing all attributes

Install with Tessl CLI