or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-integration.mdbuiltin-methods.mdcore-operations.mddata-models.mdexceptions.mdindex.mdmethod-system.mdversioningit-class.md
tile.json

tessl/pypi-versioningit

Versioning It with your Version In Git - automatic package versioning based on VCS tags

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/versioningit@3.3.x

To install, run

npx @tessl/cli install tessl/pypi-versioningit@3.3.0

index.mddocs/

Versioningit

A Python packaging plugin for automatically determining package versions based on version control repository tags. Unlike other tools, it allows easy customization of version formats and provides hooks for custom methods through entry points or project-specific functions.

Package Information

  • Package Name: versioningit
  • Language: Python
  • Installation: pip install versioningit

Core Imports

import versioningit

Common usage imports:

from versioningit import get_version, get_next_version, Versioningit

For setuptools integration:

from versioningit import get_cmdclasses

Basic Usage

from versioningit import get_version, get_next_version

# Get current version from VCS tags
version = get_version()
print(f"Current version: {version}")

# Get next calculated version
next_version = get_next_version()
print(f"Next version: {next_version}")

# Use with custom configuration
config = {
    "vcs": {"method": "git"},
    "tag2version": {"method": "basic", "rmprefix": "v"},
    "format": {
        "distance": "{version}.post{distance}+{vcs}{rev}",
        "dirty": "{version}+d{build_date:%Y%m%d}"
    }
}
version = get_version(config=config)

Architecture

Versioningit follows a step-based pipeline architecture with customizable methods:

  • VCS Step: Query version control system for tag and repository state
  • Tag2Version Step: Extract version string from VCS tag
  • Next-Version Step: Calculate next version for development
  • Format Step: Apply version formatting based on repository state
  • Template-Fields Step: Generate fields for file templating
  • Write Step: Optionally write version to files
  • Onbuild Step: Insert version into build artifacts

Each step can be customized using built-in methods, entry points, or custom functions.

Capabilities

Core Version Operations

Main functions for determining and calculating versions from version control systems, with support for fallback scenarios and custom configurations.

def get_version(
    project_dir: str | Path = os.curdir,
    config: Optional[dict] = None,
    write: bool = False,
    fallback: bool = True,
) -> str: ...

def get_next_version(
    project_dir: str | Path = os.curdir, 
    config: Optional[dict] = None
) -> str: ...

def get_version_from_pkg_info(project_dir: str | Path) -> str: ...

Core Version Operations

Versioningit Class API

Object-oriented interface providing fine-grained control over the version calculation pipeline with step-by-step execution and reporting.

class Versioningit:
    @classmethod
    def from_project_dir(
        cls, project_dir: str | Path = os.curdir, config: Optional[dict] = None
    ) -> Versioningit: ...
    
    def get_version(self, write: bool = False, fallback: bool = True) -> str: ...
    def run(self, write: bool = False, fallback: bool = True) -> Report | FallbackReport: ...

Versioningit Class

Data Models and Reports

Core data structures for representing VCS state, version calculation results, and intermediate values throughout the pipeline.

@dataclass
class VCSDescription:
    tag: str
    state: str
    branch: Optional[str]
    fields: dict[str, Any]

@dataclass
class Report:
    version: str
    description: Optional[VCSDescription]
    base_version: Optional[str]
    next_version: Optional[str]
    template_fields: dict[str, Any]
    using_default_version: bool

Data Models

Build Integration

Integration with build systems including setuptools command classes and onbuild hooks for inserting version information into build artifacts.

def get_cmdclasses(
    bases: Optional[dict[str, type[Command]]] = None
) -> dict[str, type[Command]]: ...

def run_onbuild(
    *,
    build_dir: str | Path,
    is_source: bool,
    template_fields: dict[str, Any],
    project_dir: str | Path = os.curdir,
    config: Optional[dict] = None,
) -> None: ...

Build Integration

Built-in Methods

Pre-built implementations for each pipeline step including VCS querying, version formatting, file writing, and onbuild processing.

def basic_tag2version(*, tag: str, params: dict[str, Any]) -> str: ...
def basic_format(
    *,
    description: VCSDescription,
    base_version: str,
    next_version: str,
    params: dict[str, Any],
) -> str: ...
def basic_write(
    *,
    project_dir: str | Path,
    template_fields: dict[str, Any],
    params: dict[str, Any],
) -> None: ...

Built-in Methods

Method System

Framework for loading and executing custom methods via entry points, module imports, or direct callables with parameter passing.

@dataclass
class VersioningitMethod:
    method: Callable
    params: dict[str, Any]
    
    def __call__(self, **kwargs: Any) -> Any: ...

class MethodSpec(ABC):
    @abstractmethod
    def load(self, project_dir: str | Path) -> Callable: ...

Method System

Exception Handling

Comprehensive error hierarchy for handling configuration errors, VCS issues, and method validation problems.

class Error(Exception): ...
class ConfigError(Error, ValueError): ...
class MethodError(Error): ...
class NotVCSError(Error): ...
class NoTagError(Error): ...
class InvalidTagError(Error, ValueError): ...
class InvalidVersionError(Error, ValueError): ...

Exception Handling

Types

from pathlib import Path
from typing import Any, Callable, Optional

# Type aliases for common parameters
ProjectDir = str | Path
ConfigDict = Optional[dict[str, Any]]
TemplateFields = dict[str, Any]