CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-setuptools-scm

The blessed package to manage your versions by SCM tags

—

Pending
Overview
Eval results
Files

cli.mddocs/

CLI Interface

setuptools-scm provides a comprehensive command-line interface for version retrieval, debugging, and integration with build systems and CI/CD pipelines.

Capabilities

Main CLI Function

Entry point for the command-line interface with full argument parsing and execution.

def main(args: list[str] | None = None) -> int:
    """
    Main CLI entry point for setuptools-scm.
    
    Parameters:
    - args: Command line arguments (uses sys.argv if None)
    
    Returns:
    Exit code (0 for success, non-zero for error)
    """

Command Line Usage

Basic Version Retrieval

# Get version from current directory
python -m setuptools_scm

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

# Get version using specific config file
python -m setuptools_scm --config /path/to/pyproject.toml

Version Formatting Options

# Strip development version suffix
python -m setuptools_scm --strip-dev

# Use custom format string
python -m setuptools_scm --format "{tag}.{distance}"

# Output only the version (no extra information)
python -m setuptools_scm --quiet

Configuration and Debugging

# Show detailed configuration information
python -m setuptools_scm --query all

# Show only specific query information
python -m setuptools_scm --query version
python -m setuptools_scm --query distance  
python -m setuptools_scm --query dirty
python -m setuptools_scm --query branch

# Force writing version files
python -m setuptools_scm --force-write-version-files

# Show help
python -m setuptools_scm --help

# List package files (subcommand)
python -m setuptools_scm ls

CLI Options

Core Options

  • --root PATH - Repository root directory (default: current directory)
  • --config PATH - Path to pyproject.toml config file (auto-detected if not specified)
  • --strip-dev - Remove development version suffix (.dev, etc.)
  • --quiet - Suppress extra output, show only version

Output Formatting

  • --format FORMAT - Custom format string for version output
  • --json - Output version information as JSON

Debugging and Information

  • --query FIELD - Query specific information (version, distance, dirty, branch, tag, all)
  • --force-write-version-files - Force writing of version files even if version unchanged
  • --verbose - Enable verbose output for debugging

Configuration Override

  • --version-scheme SCHEME - Override version scheme from config
  • --local-scheme SCHEME - Override local scheme from config
  • --fallback-version VERSION - Fallback version if SCM detection fails

Subcommands

  • ls - List information about the package (e.g., included files)

Usage Examples

Development Workflow

# Check current version during development
python -m setuptools_scm
# Output: 1.2.3.dev4+g1234567.d20231201

# Get clean version for release preparation
python -m setuptools_scm --strip-dev
# Output: 1.2.3

# Check if repository is dirty
python -m setuptools_scm --query dirty
# Output: True or False

# Get distance from last tag
python -m setuptools_scm --query distance
# Output: 4

CI/CD Integration

# In GitHub Actions, GitLab CI, etc.
VERSION=$(python -m setuptools_scm --strip-dev)
echo "Building version: $VERSION"

# Get version with custom format for Docker tags
DOCKER_TAG=$(python -m setuptools_scm --format "v{tag}-{distance}")
echo "Docker tag: $DOCKER_TAG"

# Check if this is an exact release
python -m setuptools_scm --query distance
if [ $? -eq 0 ]; then
    echo "This is a release build"
else
    echo "This is a development build"
fi

Build System Integration

# Generate version file before build
python -m setuptools_scm --force-write-version-files

# Use in setup.py or build scripts
VERSION=$(python -m setuptools_scm)
python setup.py sdist --version="$VERSION"

# Integration with other tools
python -m setuptools_scm --json > version.json
cat version.json | jq '.version'

Debugging Configuration Issues

# Show all configuration and version information
python -m setuptools_scm --query all

# Test with different config file
python -m setuptools_scm --config alternative-pyproject.toml

# Override schemes for testing
python -m setuptools_scm --version-scheme only-version --local-scheme no-local-version

# Verbose output for troubleshooting
python -m setuptools_scm --verbose

JSON Output Format

When using --json flag, the output includes detailed version information:

{
  "version": "1.2.3.dev4+g1234567.d20231201",
  "tag": "1.2.3",
  "distance": 4,
  "dirty": false,
  "node": "1234567",
  "branch": "main",
  "node_date": "2023-12-01"
}

Configuration File Integration

The CLI automatically detects and uses configuration from pyproject.toml:

[tool.setuptools_scm]
version_scheme = "guess-next-dev"
local_scheme = "node-and-date"
tag_regex = "^(?P<version>[vV]?\\d+(?:\\.\\d+){0,2}[^\\+]*)(?:\\+.*)?$"
fallback_version = "0.0.0"
write_to = "src/mypackage/_version.py"

The CLI respects all configuration options and can override them with command-line flags.

Error Handling

The CLI provides clear error messages for common issues:

# No SCM repository found
python -m setuptools_scm --root /tmp
# ERROR: no version found

# Invalid configuration
python -m setuptools_scm --config invalid.toml  
# ERROR: could not use invalid.toml, using default configuration

# Git not available
python -m setuptools_scm
# Warning: command git not found while parsing the scm, using fallbacks

Integration with Build Tools

setuptools

# setuptools-scm integrates automatically, but CLI can verify
python -m setuptools_scm --query version > VERSION
python setup.py --version

Build

python -m build --sdist --wheel
# setuptools-scm automatically provides version

pip

# During development install
pip install -e .
# Version determined by setuptools-scm

# Check installed version matches SCM
pip show mypackage | grep Version
python -m setuptools_scm

Advanced Usage

Custom Format Strings

# Custom version format with multiple components
python -m setuptools_scm --format "v{tag}-build{distance}-{node}"
# Output: v1.2.3-build4-1234567

# Date-based formats
python -m setuptools_scm --format "{tag}.{node_date:%Y%m%d}"
# Output: 1.2.3.20231201

# Conditional formatting based on dirty state
python -m setuptools_scm --format "{tag}{'.dirty' if dirty else ''}"

Scripting and Automation

#!/bin/bash
set -e

# Automated release script using setuptools-scm CLI
CURRENT_VERSION=$(python -m setuptools_scm --strip-dev)
DISTANCE=$(python -m setuptools_scm --query distance)

if [ "$DISTANCE" -eq 0 ]; then
    echo "Creating release for version $CURRENT_VERSION"
    # Perform release tasks
else
    echo "Not on a tagged commit, distance: $DISTANCE"
    exit 1
fi

Install with Tessl CLI

npx tessl i tessl/pypi-setuptools-scm

docs

cli.md

core-api.md

index.md

integration.md

version-schemes.md

tile.json