Metadata-Version: 2.4
Name: setuptools-scmx
Version: 0.1.4
Summary: CI friendly setuptools-scm hooks
Author-email: Rowland Ogwara <r.ogwara@gmail.com>
License-Expression: Apache-2.0
Project-URL: Source, https://github.com/kulgan/setuptools-scmx
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: attrs
Requires-Dist: cattrs>=26.1
Requires-Dist: packaging>=26.2
Requires-Dist: pyprojectr>=0.1
Requires-Dist: setuptools-scm[toml]

# 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`.

```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.

```toml
# 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]`.

```toml
# 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](https://peps.python.org/pep-0440/) 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.

```toml
[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)
