setuptools-scmx

Project Description

setuptools-scmx is a Python package designed to extend setuptools-scm with CI-friendly versioning schemes. It provides flexible, configuration-driven version management tailored for continuous integration and delivery workflows, allowing developers to define custom versioning logic based on Git branch names and tags directly within pyproject.toml.

What it Does

This package enhances the standard setuptools-scm functionality by introducing:

• Custom Versioning Schemes: Define how your project's version is determined based on its Git state.
• Branch-Aware Versioning: Differentiate version numbers based on the current Git branch (e.g., main, develop, feature/xyz).
• Exact Tag Versions: Ensures that builds from Git tags always result in the exact tag version, without any additional suffixes.
• CI Platform Integration: Built-in support for GitHub Actions, GitLab CI, and Jenkins environment variables.
• Environment Variable Overrides: Allows specifying a version directly via an environment variable, with support for regex-based extraction.
• pyproject.toml Integration: All custom versioning logic and configurations are managed declaratively in your pyproject.toml file, leveraging pyprojectr for robust parsing.

How to Use it as a Developer

1. Installation

Add setuptools-scmx to your build-system.requires in pyproject.toml.

# pyproject.toml
[build-system]
requires = [
    "setuptools>=80",
    "setuptools-scm[toml]",
    "setuptools-scmx",
]
build-backend = "setuptools.build_meta"

[project]
name = "your-project-name"
dynamic = ["version"]

2. Configure setuptools-scm

Configure setuptools-scm to use the setuptools_scmx entry point.

# pyproject.toml
[tool.setuptools_scm]
version_scheme = "setuptools_scmx:version_scheme"
local_scheme = "no-local-version"

3. Configure setuptools-scmx

Define your rules under [tool.setuptools-scmx].

# pyproject.toml
[tool.setuptools-scmx]
scheme = "branch-scheme" # Required to enable branch-aware logic
env_scheme = "github"    # Optional: 'custom' (default), 'github', 'gitlab', 'jenkins'

[tool.setuptools-scmx.branch-scheme]
labels = [
  { name = "rc", branches = ["main", "master"] },
  { name = "dev", branches = ["develop"] },
  { name = "alpha", branches = ["feature/.*"] },
  { name = "post", branches = ["hotfix"] },
]

Supported Labels

The name field in labels supports standard PEP 440 pre-release identifiers:

• rc, beta, alpha, dev, post

CI & Environment Schemes

setuptools-scmx can automatically detect branch and build information from CI environments.

env_scheme	Source Platform	Automatic Branch Detection	Automatic Build Number
github	GitHub Actions	GITHUB_REF_NAME	GITHUB_RUN_ID
gitlab	GitLab CI	CI_COMMIT_REF_NAME	CI_JOB_ID
jenkins	Jenkins	BRANCH_NAME	BUILD_NUMBER
custom	Any	Manual via env-schemes.custom	Manual via env-schemes.custom

Advanced Environment Configuration

You can customize how versions are extracted from environment variables.

[tool.setuptools-scmx.env-schemes.custom]
version = "SCMX_VERSION_OVERRIDE"
# If true (default), extracts version using the regex below
extract_version_with_regex = true
# Default regex extracts digits and dots (e.g., "1.2.3" from "v1.2.3-beta")
version_regex = "([\\d.]+)"

Environment Variables

• SCMX_PYPROJECT_PATH: Path to the pyproject.toml file (defaults to pyproject.toml in the current directory). Useful for monorepos.
• SCMX_VERSION_OVERRIDE: Default variable used by the custom scheme to force a specific version.

Versioning Behavior Examples

Assuming the last tag is 1.0.0 and there are 5 commits since (distance=5):

• On a Tag: 1.0.0
• On main branch: 1.0.1.rc.5
• On develop branch: 1.0.1.dev.5
• On feature/xyz: 1.0.1.alpha.5
• On hotfix branch: 1.0.1.post.5
• On an unmapped branch (bugfix/123): 1.0.1+bugfix-123.5
• With SCMX_VERSION_OVERRIDE="2.0.0": 2.0.0 (overrides Git state)