Version Detection

def _get_version(config: _Config, name: Optional[str] = None) -> Tuple[str, Version]:
    """
    Get version from VCS or override sources based on configuration.
    
    Parameters:
    - config: Configuration object containing VCS and formatting settings
    - name: Optional project name for override lookup
    
    Returns:
    Tuple[str, Version]: (formatted_version_string, dunamai_version_object)
    
    Raises:
    - ValueError: Invalid VCS type or style configuration
    - RuntimeError: VCS operation failures or shallow repository issues
    """

def _get_version_from_dunamai(
    vcs: Vcs, 
    pattern: Union[str, Pattern], 
    config: _Config, 
    *, 
    strict: Optional[bool] = None
) -> Version:
    """
    Extract version from VCS using Dunamai with configuration options.
    
    Parameters:
    - vcs: Version control system type from Dunamai
    - pattern: Tag pattern (string regex or Dunamai Pattern object)
    - config: Configuration containing VCS-specific options
    - strict: Override strict mode for version validation
    
    Returns:
    Version: Dunamai Version object with extracted version information
    """

def _get_version_from_file(config: _Config) -> Optional[str]:
    """
    Read version from a file specified in configuration.
    
    Parameters:
    - config: Configuration containing from-file settings
    
    Returns:
    Optional[str]: Version string from file or None if not configured
    
    Raises:
    - RuntimeError: Unable to find pyproject.toml for relative path resolution
    - ValueError: File doesn't match specified pattern
    """

def _get_override_version(name: Optional[str], env: Optional[Mapping] = None) -> Optional[str]:
    """
    Get version override from environment variables.
    
    Parameters:
    - name: Package name for specific override lookup
    - env: Environment variables mapping (defaults to os.environ)
    
    Returns:
    Optional[str]: Override version string or None if not set
    """

def _render_jinja(
    version: Version, 
    template: str, 
    config: _Config, 
    extra: Optional[Mapping] = None
) -> str:
    """
    Render Jinja2 template with version context and configuration imports.
    
    Parameters:
    - version: Dunamai Version object with VCS information
    - template: Jinja2 template string
    - config: Configuration including format-jinja-imports
    - extra: Additional template variables
    
    Returns:
    str: Rendered version string from template
    """

# Basic version components
base: str              # Base version (e.g., "1.2.3")
stage: Optional[str]   # Pre-release stage (e.g., "alpha", "beta", "rc")
revision: Optional[int] # Pre-release revision number
distance: int          # Commits since last tag
commit: str           # Commit hash (short or full based on config)
dirty: bool           # Whether working directory has uncommitted changes

# Branch and metadata
branch: Optional[str]           # Current branch name
branch_escaped: Optional[str]   # Branch name with non-alphanumeric chars removed
tagged_metadata: Optional[str]  # Tagged metadata from version pattern
timestamp: Optional[str]        # Commit timestamp as YYYYmmddHHMMSS UTC

# Semantic version components
major: int            # First part of base version
minor: int            # Second part of base version  
patch: int            # Third part of base version

# Additional context
version: Version      # Full Dunamai Version object
env: dict            # Environment variables dictionary

# Dunamai serialization functions
bump_version(version: str, index: int = -1) -> str
serialize_pep440(base: str, stage: str = None, revision: int = None, **kwargs) -> str
serialize_semver(base: str, stage: str = None, revision: int = None, **kwargs) -> str
serialize_pvp(base: str, stage: str = None, revision: int = None, **kwargs) -> str

from poetry_dynamic_versioning import _get_version, _get_config_from_path

# Get configuration and version
config = _get_config_from_path()
version_str, version_obj = _get_version(config)

print(f"Version: {version_str}")
print(f"Base: {version_obj.base}")
print(f"Distance: {version_obj.distance}")
print(f"Commit: {version_obj.commit}")

import os
from poetry_dynamic_versioning import _get_override_version

# Set environment override
os.environ["POETRY_DYNAMIC_VERSIONING_OVERRIDE"] = "my-package=1.0.0,other-pkg=2.0.0"

# Check for override
override = _get_override_version("my-package")
if override:
    print(f"Using override version: {override}")

from dunamai import Version
from poetry_dynamic_versioning import _render_jinja

# Create version object
version = Version("1.2.3", distance=5, commit="abc123", dirty=True)

# Custom template
template = """
{%- if distance == 0 -%}
{{ base }}
{%- else -%}
{{ base }}.dev{{ distance }}+{{ commit }}{% if dirty %}.dirty{% endif %}
{%- endif -%}
"""

config = {
    "format-jinja-imports": [],
    "bump": False
}

result = _render_jinja(version, template, config)
print(f"Formatted version: {result}")  # "1.2.3.dev5+abc123.dirty"

from poetry_dynamic_versioning import _get_version_from_file

# Configuration for reading from VERSION file
config = {
    "from-file": {
        "source": "VERSION",
        "pattern": r"v(\d+\.\d+\.\d+)"  # Extract version from "v1.2.3" format
    }
}

version = _get_version_from_file(config)
if version:
    print(f"Version from file: {version}")

from dunamai import Vcs, Pattern
from poetry_dynamic_versioning import _get_version_from_dunamai

# Custom configuration for Git with specific pattern
config = {
    "latest-tag": False,
    "tag-dir": "tags",
    "tag-branch": None,
    "full-commit": True,
    "strict": True,
    "pattern-prefix": "release-",
    "ignore-untracked": True,
    "commit-length": 8
}

# Use custom pattern for release tags
pattern = r"release-(?P<base>\d+\.\d+\.\d+)"
version = _get_version_from_dunamai(Vcs.Git, pattern, config)

print(f"Version from Git: {version.serialize()}")