or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcore-api.mdindex.mdintegration.mdversion-schemes.md
tile.json

tessl/pypi-setuptools-scm

The blessed package to manage your versions by SCM tags

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/setuptools-scm@8.3.x

To install, run

npx @tessl/cli install tessl/pypi-setuptools-scm@8.3.0

index.mddocs/

setuptools-scm

A comprehensive Python library that automatically extracts package versions from Git or Mercurial metadata instead of requiring manual version declarations. setuptools-scm eliminates the need to maintain version numbers in source code by reading them directly from version control system tags and commits, while also providing files to setuptools for inclusion in source distributions.

Package Information

  • Package Name: setuptools-scm
  • Language: Python
  • Installation: pip install setuptools-scm
  • Requirements: Python 3.8+, setuptools 61+

Core Imports

import setuptools_scm

Standard imports for version retrieval:

from setuptools_scm import get_version, Configuration, ScmVersion

Basic Usage

from setuptools_scm import get_version

# Get version from current directory
version = get_version()
print(version)  # e.g., "1.2.3" or "1.2.3.dev4+g1234567"

# Get version from specific directory
version = get_version(root="/path/to/repo")

# Get version with custom schemes
version = get_version(
    version_scheme="guess-next-dev",
    local_scheme="node-and-date"
)

# Configuration-based approach
from setuptools_scm import Configuration

config = Configuration(
    root=".",
    version_scheme="guess-next-dev",
    local_scheme="node-and-date",
    fallback_version="0.0.0"
)
version = setuptools_scm._get_version(config)

pyproject.toml Integration

[build-system]
requires = ["setuptools>=64", "setuptools-scm>=8"]
build-backend = "setuptools.build_meta"

[project]
dynamic = ["version"]

[tool.setuptools_scm]
# Optional configuration
version_file = "src/mypackage/_version.py"

CLI Usage

# Get version from current directory
python -m setuptools_scm

# Get version from specific directory
python -m setuptools_scm --root /path/to/repo

# Get version without dev suffix
python -m setuptools_scm --strip-dev

Architecture

setuptools-scm uses a plugin-based architecture with three main layers:

  • Configuration Layer: Manages settings, file paths, and version schemes
  • SCM Parser Layer: Extracts version information from Git, Mercurial, or fallback sources
  • Version Scheme Layer: Transforms raw SCM data into formatted version strings using configurable schemes
  • Integration Layer: Provides hooks for setuptools, build systems, and file generation

The library supports customization through entry points, allowing users to define custom version schemes, local schemes, and SCM parsers while maintaining compatibility with modern Python packaging standards (PEP 518/621).

Capabilities

Core Version Retrieval

Primary functions for extracting and formatting version information from SCM repositories, with support for custom schemes and extensive configuration options.

def get_version(
    root: PathT = ".",
    version_scheme: VERSION_SCHEME = "guess-next-dev",
    local_scheme: VERSION_SCHEME = "node-and-date",
    write_to: PathT | None = None,
    write_to_template: str | None = None,
    version_file: PathT | None = None,
    version_file_template: str | None = None,
    relative_to: PathT | None = None,
    tag_regex: str | Pattern[str] = DEFAULT_TAG_REGEX,
    parentdir_prefix_version: str | None = None,
    fallback_version: str | None = None,
    fallback_root: PathT = ".",
    parse: Any | None = None,
    git_describe_command: CMD_TYPE | None = None,
    dist_name: str | None = None,
    version_cls: Any | None = None,
    normalize: bool = True,
    search_parent_directories: bool = False
) -> str

def _get_version(
    config: Configuration,
    force_write_version_files: bool | None = None
) -> str | None

class Configuration:
    relative_to: PathT | None = None
    root: PathT = "."
    version_scheme: VERSION_SCHEME = "guess-next-dev"
    local_scheme: VERSION_SCHEME = "node-and-date"
    tag_regex: Pattern[str] = DEFAULT_TAG_REGEX
    parentdir_prefix_version: str | None = None
    fallback_version: str | None = None
    fallback_root: PathT = "."
    write_to: PathT | None = None
    write_to_template: str | None = None
    version_file: PathT | None = None
    version_file_template: str | None = None
    parse: Any | None = None
    git_describe_command: CMD_TYPE | None = None
    dist_name: str | None = None
    version_cls: type = Version
    search_parent_directories: bool = False
    
    @classmethod
    def from_file(
        cls, 
        name: PathT = "pyproject.toml", 
        dist_name: str | None = None, 
        **kwargs
    ) -> "Configuration"
    
    @classmethod
    def from_data(cls, relative_to: PathT, data: dict[str, Any]) -> "Configuration"

class ScmVersion:
    tag: Version | NonNormalizedVersion | str
    config: Configuration
    distance: int = 0
    node: str | None = None
    dirty: bool = False
    preformatted: bool = False
    branch: str | None = None
    node_date: date | None = None
    
    @property
    def exact(self) -> bool
    
    def format_with(self, fmt: str, **kw: object) -> str
    def format_choice(self, clean_format: str, dirty_format: str, **kw: object) -> str

Core API

Version Schemes and Local Schemes

Configurable strategies for transforming SCM metadata into version strings, supporting semantic versioning, calendar versioning, and custom patterns.

# Version schemes (via entry points)
def guess_next_dev_version(version: ScmVersion) -> str
def no_guess_dev_version(version: ScmVersion) -> str  
def only_version(version: ScmVersion) -> str
def postrelease_version(version: ScmVersion) -> str
def simplified_semver_version(version: ScmVersion) -> str
def calver_by_date(version: ScmVersion) -> str

# Local schemes (via entry points)  
def get_local_node_and_date(version: ScmVersion) -> str
def get_local_node_and_timestamp(version: ScmVersion) -> str
def get_local_dirty_tag(version: ScmVersion) -> str
def get_no_local_node(version: ScmVersion) -> str

Version and Local Schemes

Command Line Interface

Complete CLI tool for version retrieval, debugging, and integration with build systems and CI/CD pipelines.

def main(args: list[str] | None = None) -> int

Command line options include --root, --config, --strip-dev, --format, --query, and more.

CLI Interface

Build System Integration

Seamless integration with setuptools, modern build systems, and packaging tools through entry points and configuration.

def find_files(path: str = "") -> list[str]
def dump_version(
    root: str,
    version: str, 
    write_to: str,
    template: str | None = None,
    scm_version: ScmVersion | None = None
) -> None

Entry points for setuptools hooks, file finders, and SCM parsers enable automatic version inference and file inclusion.

Integration

Types

from re import Pattern
from datetime import date, datetime
from typing import Any, Callable, Sequence
from os import PathLike

# Type Aliases
PathT = PathLike[str] | str
CMD_TYPE = Sequence[PathT] | str
VERSION_SCHEME = str | Callable[["ScmVersion"], str]

class Version:
    """Standard packaging Version class"""
    
class NonNormalizedVersion(Version):
    """A non-normalizing version handler that preserves original version strings"""
    def __init__(self, version: str) -> None
    def __str__(self) -> str
    def __repr__(self) -> str

# Constants
DEFAULT_VERSION_SCHEME: str = "guess-next-dev"
DEFAULT_LOCAL_SCHEME: str = "node-and-date"
DEFAULT_TAG_REGEX: Pattern[str]  # Regex for parsing version tags