version ¶

Unified version detection and management system.

This module provides a clean, DRY approach to version handling across all environments: - Development (git describe) - Docker containers (VERSION file) - Production releases (environment variables) - Package metadata (fallback)

The system follows a clear priority order and provides consistent behavior.

Classes:

VersionError –

Raised when version detection fails in an unexpected way.
VersionManager –

Centralized version detection and management.

Functions:

get_version –

Get the current version.
is_semantic_version –

Check if a version is valid semantic version.
compare_versions –

Compare two semantic versions.
get_version_info –

Get detailed version information.
get_build_info –

Get build information.
bump_version –

Bump a semantic version.
satisfies_constraint –

Check if a version satisfies a semver constraint.
generate_build_metadata –

Generate build metadata string from git SHA and build date.

Classes¶

VersionError ¶

Bases: Exception

Raised when version detection fails in an unexpected way.

VersionManager ¶

Python

VersionManager(root_path: Path | None = None)

Centralized version detection and management.

This class provides a single source of truth for version information across all environments and use cases.

Initialize the version manager.

Parameters:

root_path (Path, default: None ) –

Root path of the project. If None, will be auto-detected.

Methods:

get_version –

Get the current version using the established priority order.
is_semantic_version –

Check if a version string is a valid semantic version.
compare_versions –

Compare two semantic version strings.
get_version_info –

Get detailed information about a semantic version.
get_build_info –

Get build information for the current version.
bump_version –

Bump a semantic version.
satisfies_constraint –

Check if a version satisfies a semver constraint.
generate_build_metadata –

Generate build metadata string from git SHA and build date.

Functions¶

_detect_root_path ¶

Python

_detect_root_path() -> Path

Detect the project root path.

Returns:

Path –

The project root path.

get_version ¶

Python

get_version(force_refresh: bool = False) -> str

Get the current version using the established priority order.

Priority order: 1. TUX_VERSION environment variable 2. VERSION file in project root 3. Git describe (if git is available) 4. "dev" as final fallback

Parameters:

force_refresh (bool, default: False ) –

If True, bypass cache and detect version fresh.

Returns:

str –

The detected version string.

_detect_version ¶

Python

_detect_version() -> str

Detect version using the priority order.

Returns:

str –

The detected version string.

_from_environment ¶

Python

_from_environment() -> str | None

Get version from TUX_VERSION environment variable.

Returns:

str or None –

The version from environment, or None if not set.

_from_version_file ¶

Python

_from_version_file() -> str | None

Get version from VERSION file in project root.

Returns:

str or None –

The version from VERSION file, or None if not found.

_from_git ¶

Python

_from_git() -> str | None

Get version from git describe.

Returns:

str or None –

The version from git describe, or None if git is unavailable.

_normalize_version ¶

Python

_normalize_version(version: str) -> str

Normalize a version string using semver if available.

Parameters:

version (str) –

The version string to normalize.

Returns:

str –

The normalized version string.

is_semantic_version ¶

Python

is_semantic_version(version: str | None = None) -> bool

Check if a version string is a valid semantic version.

Parameters:

version (str, default: None ) –

The version to check. If None, uses the current detected version.

Returns:

bool –

True if the version is valid semver, False otherwise.

compare_versions ¶

Python

compare_versions(version1: str, version2: str) -> int

Compare two semantic version strings.

Parameters:

version1 (str) –

First version to compare.
version2 (str) –

Second version to compare.

Returns:

int –

-1 if version1 < version2, 0 if equal, 1 if version1 > version2.

Raises:

ValueError –

If either version is not a valid semantic version.

get_version_info ¶

Python

get_version_info(version: str | None = None) -> dict[str, str | int | None]

Get detailed information about a semantic version.

Parameters:

version (str, default: None ) –

The version to analyze. If None, uses the current detected version.

Returns:

dict –

Dictionary containing version components and metadata.

get_build_info ¶

Python

get_build_info() -> dict[str, str]

Get build information for the current version.

Returns:

dict –

Dictionary containing build metadata.

bump_version ¶

Python

bump_version(version: str, bump_type: str) -> str

Bump a semantic version.

Parameters:

version (str) –

The version to bump.
bump_type (str) –

Type of bump: 'major', 'minor', 'patch'.

Returns:

str –

The bumped version string.

Raises:

ValueError –

If version is not semantic or bump_type is invalid.

satisfies_constraint ¶

Python

satisfies_constraint(version: str, constraint: str) -> bool

Check if a version satisfies a semver constraint.

Parameters:

version (str) –

Version to check.
constraint (str) –

Semver constraint (e.g., ">=1.0.0", "^1.2.0").

Returns:

bool –

True if version satisfies the constraint.

Raises:

ValueError –

If constraint syntax is invalid.

generate_build_metadata ¶

Python

generate_build_metadata(
    git_sha: str | None = None, build_date: str | None = None
) -> str

Generate build metadata string from git SHA and build date.

Parameters:

git_sha (str, default: None ) –

Git SHA (short form). If None, attempts to detect from git.
build_date (str, default: None ) –

Build date in YYYYMMDD format. If None, uses current date.

Returns:

str –

Build metadata string (e.g., "sha.abcdef.20231029").

_get_git_sha ¶

Python

_get_git_sha() -> str

Get the current git SHA.

Returns:

str –

The git SHA, or "unknown" if not available.

Functions¶

get_version ¶

Python

get_version() -> str

Get the current version.

Returns:

str –

The current version string.

is_semantic_version ¶

Python

is_semantic_version(version: str | None = None) -> bool

Check if a version is valid semantic version.

Parameters:

version (str, default: None ) –

Version to check. If None, uses current version.

Returns:

bool –

True if valid semver, False otherwise.

compare_versions ¶

Python

compare_versions(version1: str, version2: str) -> int

Compare two semantic versions.

Parameters:

version1 (str) –

First version.
version2 (str) –

Second version.

Returns:

int –

Comparison result (-1, 0, 1).

get_version_info ¶

Python

get_version_info(version: str | None = None) -> dict[str, str | int | None]

Get detailed version information.

Parameters:

version (str, default: None ) –

Version to analyze. If None, uses current version.

Returns:

dict –

Version information dictionary.

get_build_info ¶

Python

get_build_info() -> dict[str, str]

Get build information.

Returns:

dict –

Build information dictionary.

bump_version ¶

Python

bump_version(version: str, bump_type: str) -> str

Bump a semantic version.

Parameters:

version (str) –

The version to bump.
bump_type (str) –

Type of bump: 'major', 'minor', 'patch'.

Returns:

str –

The bumped version string.

satisfies_constraint ¶

Python

satisfies_constraint(version: str, constraint: str) -> bool

Check if a version satisfies a semver constraint.

Parameters:

version (str) –

Version to check.
constraint (str) –

Semver constraint (e.g., ">=1.0.0", "^1.2.0").

Returns:

bool –

True if version satisfies the constraint.

generate_build_metadata ¶

Python

generate_build_metadata(
    git_sha: str | None = None, build_date: str | None = None
) -> str

Generate build metadata string from git SHA and build date.

Parameters:

git_sha (str, default: None ) –

Git SHA (short form). If None, attempts to detect from git.
build_date (str, default: None ) –

Build date in YYYYMMDD format. If None, uses current date.

Returns:

str –

Build metadata string (e.g., "sha.abcdef.20231029").