buildstamp 0.3.0

Build-time version metadata injection for Python packages.

buildstamp

Build-time version metadata injection for Python packages. Every artifact is stamped with its version, quality tier, commit SHA, and build date — with no metadata drift between source and installed packages, and no git required at runtime.

---

How it works

Environment	Version source
Git checkout / editable install	Live: git rev-parse + VERSION file
Installed artifact (no .git)	Baked: _version.json written at build time

The quality tier (dev / rc / stable) is controlled by the RELEASE_TYPE environment variable at build time, so no tag ceremony is needed and no branch names leak into artifacts.

---

Quick start

1. Add a thin backend shim — _build_backend.py at your project root:

from buildstamp.backend import *  # noqa: F401, F403

2. Configure pyproject.toml:

[project]
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {file = "VERSION"}

[tool.setuptools.package-data]
your_package = ["_version.json"]

[build-system]
requires = ["setuptools>=64.0", "wheel", "buildstamp"]
build-backend = "_build_backend"
backend-path = ["."]

3. Add _version.json to .gitignore:

your_package/_version.json

4. Use in your_package/__init__.py:

from buildstamp import load_metadata

_meta          = load_metadata(__file__)
__version__    = _meta.version
__quality__    = _meta.quality
__commit__     = _meta.commit
__build_date__ = _meta.build_date

5. Create a VERSION file at the project root:

1.0.0

---

BuildMetadata fields

Field	Type	Dev (checkout)	Artifact
version	str	"1.0.0+g701e4ca"	"1.0.0"
quality	str	"dev"	RELEASE_TYPE value
commit	str	short SHA	short SHA baked at build time
build_date	datetime | None	None	UTC datetime

---

Releasing artifacts

# stable release
RELEASE_TYPE=stable uv build

# release candidate
RELEASE_TYPE=rc uv build

If RELEASE_TYPE is unset, the baked quality defaults to "dev".

---

Installation

pip install buildstamp

While not yet on PyPI, install from source:

uv pip install setuptools
uv pip install -e /path/to/buildstamp
uv pip install -e . --no-build-isolation

---

Design rationale

See VERSIONING.md for the full rationale — including why this avoids git tags, dirty flags, and branch names as version sources.