Data Models

@dataclass
class VCSDescription:
    """A description of the state of a version control repository."""
    
    tag: str
    """
    The name of the most recent tag in the repository (possibly after
    applying any match or exclusion rules based on user parameters) from
    which the current repository state is descended.
    """
    
    state: str  
    """
    The relationship of the repository's current state to the tag. If the
    repository state is exactly the tagged state, this field equals "exact";
    otherwise, it will be a string used as a key in the format subtable.
    Recommended values are "distance", "dirty", and "distance-dirty".
    """
    
    branch: Optional[str]
    """
    The name of the repository's current branch, or None if it cannot be
    determined or does not apply.
    """
    
    fields: dict[str, Any]
    """
    A dict of additional information about the repository state to make
    available to the format method. Custom vcs methods are advised to
    adhere closely to the set of fields used by the built-in methods.
    """

@dataclass
class Report:
    """
    A report of the intermediate & final values calculated during a
    versioningit run.
    """
    
    version: str
    """The final version."""
    
    description: Optional[VCSDescription]
    """
    A description of the state of the version control repository; None if
    the "vcs" step failed.
    """
    
    base_version: Optional[str]
    """
    A version string extracted from the VCS tag; None if the "tag2version"
    step or a previous step failed.
    """
    
    next_version: Optional[str]
    """
    A "next version" calculated by the "next-version" step; None if the
    step or a previous one failed.
    """
    
    template_fields: dict[str, Any]
    """
    A dict of fields for use in templating by the "write" and "onbuild"
    steps.
    """
    
    using_default_version: bool
    """
    True iff an error occurred during version calculation, causing a
    default-version setting to be used.
    """

@dataclass
class FallbackReport:
    """
    A report of the version extracted from a PKG-INFO file in an sdist.
    """
    
    version: str
    """The version."""

from versioningit import Versioningit

vgit = Versioningit.from_project_dir()
description = vgit.do_vcs()

print(f"Most recent tag: {description.tag}")
print(f"Repository state: {description.state}")
print(f"Current branch: {description.branch}")
print(f"Additional fields: {description.fields}")

# Check repository state
if description.state == "exact":
    print("Repository is at exact tag")
elif description.state == "distance":
    print(f"Repository is {description.fields.get('distance', '?')} commits ahead")
elif description.state == "dirty":
    print("Repository has uncommitted changes")
elif description.state == "distance-dirty":
    print("Repository has commits ahead and uncommitted changes")

from versioningit import Versioningit, Report, FallbackReport

vgit = Versioningit.from_project_dir()
report = vgit.run()

if isinstance(report, FallbackReport):
    print(f"Version from PKG-INFO: {report.version}")
elif isinstance(report, Report):
    print(f"Final version: {report.version}")
    
    if report.using_default_version:
        print("Used default version due to error")
    
    if report.description:
        print(f"VCS tag: {report.description.tag}")
        print(f"VCS state: {report.description.state}")
    
    if report.base_version:
        print(f"Base version from tag: {report.base_version}")
    
    if report.next_version:
        print(f"Calculated next version: {report.next_version}")
    
    print("Template fields available:")
    for key, value in report.template_fields.items():
        print(f"  {key}: {value}")

from versioningit import Versioningit

vgit = Versioningit.from_project_dir()
report = vgit.run()

# Template fields are used for file writing and onbuild
fields = report.template_fields

# Common fields available
print(f"Version: {fields.get('version')}")
print(f"Base version: {fields.get('base_version')}")
print(f"Next version: {fields.get('next_version')}")
print(f"Branch: {fields.get('branch')}")
print(f"Version tuple: {fields.get('version_tuple')}")
print(f"Normalized version: {fields.get('normalized_version')}")

# VCS-specific fields (when available)
print(f"VCS type: {fields.get('vcs')}")
print(f"Revision: {fields.get('rev')}")
print(f"Distance: {fields.get('distance')}")
print(f"Build date: {fields.get('build_date')}")

from versioningit import Versioningit

# Configure with default version for error handling
config = {"default-version": "0.0.0.dev0"}
vgit = Versioningit.from_project_dir(config=config)

report = vgit.run()

if report.using_default_version:
    print(f"Used default version: {report.version}")
    
    # Check what failed
    if report.description is None:
        print("VCS step failed")
    elif report.base_version is None:
        print("Tag2version step failed")
    elif report.next_version is None:
        print("Next-version step failed")
else:
    print(f"Successfully calculated version: {report.version}")