buildstamp 0.3.0__tar.gz

buildstamp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 buildstamp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

buildstamp-0.3.0/MANIFEST.in

@@ -0,0 +1 @@
+include _build_backend.py

buildstamp-0.3.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: buildstamp
+Version: 0.3.0
+Summary: Build-time version metadata injection for Python packages.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/basvandriel/buildstamp
+Project-URL: Repository, https://github.com/basvandriel/buildstamp
+Project-URL: Issues, https://github.com/basvandriel/buildstamp/issues
+Project-URL: Changelog, https://github.com/basvandriel/buildstamp/releases
+Keywords: versioning,build,metadata,pep517,setuptools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# buildstamp
+
+[![CI](https://github.com/basvandriel/buildstamp/actions/workflows/ci.yml/badge.svg)](https://github.com/basvandriel/buildstamp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/buildstamp)](https://pypi.org/project/buildstamp/)
+[![Python](https://img.shields.io/pypi/pyversions/buildstamp)](https://pypi.org/project/buildstamp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+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:
+
+```python
+from buildstamp.backend import *  # noqa: F401, F403
+```
+
+**2. Configure `pyproject.toml`:**
+
+```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`:**
+
+```python
+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
+
+```sh
+# 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
+
+```sh
+pip install buildstamp
+```
+
+While not yet on PyPI, install from source:
+
+```sh
+uv pip install setuptools
+uv pip install -e /path/to/buildstamp
+uv pip install -e . --no-build-isolation
+```
+
+---
+
+## Design rationale
+
+See [VERSIONING.md](VERSIONING.md) for the full rationale — including why this
+avoids git tags, dirty flags, and branch names as version sources.

buildstamp-0.3.0/README.md

@@ -0,0 +1,124 @@
+# buildstamp
+
+[![CI](https://github.com/basvandriel/buildstamp/actions/workflows/ci.yml/badge.svg)](https://github.com/basvandriel/buildstamp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/buildstamp)](https://pypi.org/project/buildstamp/)
+[![Python](https://img.shields.io/pypi/pyversions/buildstamp)](https://pypi.org/project/buildstamp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+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:
+
+```python
+from buildstamp.backend import *  # noqa: F401, F403
+```
+
+**2. Configure `pyproject.toml`:**
+
+```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`:**
+
+```python
+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
+
+```sh
+# 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
+
+```sh
+pip install buildstamp
+```
+
+While not yet on PyPI, install from source:
+
+```sh
+uv pip install setuptools
+uv pip install -e /path/to/buildstamp
+uv pip install -e . --no-build-isolation
+```
+
+---
+
+## Design rationale
+
+See [VERSIONING.md](VERSIONING.md) for the full rationale — including why this
+avoids git tags, dirty flags, and branch names as version sources.

buildstamp-0.3.0/VERSION

@@ -0,0 +1 @@
+0.3.0

buildstamp-0.3.0/_build_backend.py

@@ -0,0 +1 @@
+from buildstamp.backend import *  # noqa: F401, F403

buildstamp-0.3.0/buildstamp/__init__.py

@@ -0,0 +1,11 @@
+from buildstamp._metadata import BuildMetadata, load_metadata
+
+try:
+    _meta = load_metadata(__file__)
+    __version__ = _meta.version
+except FileNotFoundError:
+    # No .git and no _version.json — we're being imported during a build step.
+    _meta = None
+    __version__ = "unknown"
+
+__all__ = ["BuildMetadata", "load_metadata", "__version__"]

buildstamp-0.3.0/buildstamp/_metadata.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class BuildMetadata:
+    version: str
+    quality: str
+    commit: str
+    build_date: datetime | None
+
+
+def _run_git(*args: str) -> str:
+    try:
+        return subprocess.check_output(["git", *args], stderr=subprocess.DEVNULL, text=True).strip()
+    except Exception:
+        return "unknown"
+
+
+def load_metadata(package_file: str | Path) -> BuildMetadata:
+    """Load version metadata for a package.
+
+    Call from your package's __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
+
+    In a git checkout (development or editable install), metadata is computed
+    live from git — always accurate, never stale. In an installed artifact
+    (no .git), it is read from _version.json baked in at build time.
+    """
+    package_dir = Path(package_file).parent
+    repo_root = package_dir.parent
+
+    if (repo_root / ".git").exists():
+        base = (repo_root / "VERSION").read_text(encoding="utf-8").strip()
+        sha = _run_git("rev-parse", "--short", "HEAD")
+        version = f"{base}+g{sha}" if sha != "unknown" else f"{base}.dev0"
+        return BuildMetadata(version=version, quality="dev", commit=sha, build_date=None)
+
+    meta = json.loads((package_dir / "_version.json").read_text(encoding="utf-8"))
+    return BuildMetadata(
+        version=meta["version"],
+        quality=meta["quality"],
+        commit=meta["commit"],
+        build_date=datetime.fromisoformat(meta["build_date"]),
+    )

buildstamp-0.3.0/buildstamp/backend.py

@@ -0,0 +1,164 @@
+"""PEP 517 build backend that injects VCS metadata at build time.
+
+Import all hooks from this module in your project's thin _build_backend.py:
+
+    from buildstamp.backend import *  # noqa: F401, F403
+
+Then in pyproject.toml:
+
+    [build-system]
+    requires = ["setuptools>=64.0", "wheel", "buildstamp"]
+    build-backend = "_build_backend"
+    backend-path = ["."]
+
+buildstamp reads [tool.buildstamp] from pyproject.toml for configuration.
+If not present, the package name is derived from [project].name.
+
+    [tool.buildstamp]
+    metadata-file = "your_package/_version.json"   # optional override
+    version-file  = "VERSION"                       # optional override (default: VERSION)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+from setuptools.build_meta import (
+    build_sdist as _build_sdist,
+)
+from setuptools.build_meta import (
+    build_wheel as _build_wheel,
+)
+from setuptools.build_meta import (
+    get_requires_for_build_editable,
+    get_requires_for_build_sdist,
+    get_requires_for_build_wheel,
+)
+from setuptools.build_meta import (
+    prepare_metadata_for_build_wheel as _prepare_wheel,
+)
+
+__all__ = [
+    "build_editable",
+    "build_sdist",
+    "build_wheel",
+    "get_requires_for_build_editable",
+    "get_requires_for_build_sdist",
+    "get_requires_for_build_wheel",
+    "prepare_metadata_for_build_editable",
+    "prepare_metadata_for_build_wheel",
+]
+
+
+def _git(*args: str) -> str:
+    try:
+        return subprocess.check_output(["git", *args], stderr=subprocess.DEVNULL, text=True).strip()
+    except Exception:
+        return "unknown"
+
+
+def _read_config() -> tuple[Path, Path]:
+    """Return (metadata_file, version_file) from pyproject.toml config."""
+    try:
+        try:
+            import tomllib
+        except ImportError:
+            import tomli as tomllib  # type: ignore[no-redef]
+
+        with open("pyproject.toml", "rb") as f:
+            config = tomllib.load(f)
+    except Exception as e:
+        raise RuntimeError(f"buildstamp: could not read pyproject.toml — {e}") from e
+
+    bs = config.get("tool", {}).get("buildstamp", {})
+    version_file = Path(bs.get("version-file", "VERSION"))
+
+    if "metadata-file" in bs:
+        return Path(bs["metadata-file"]), version_file
+
+    # Derive from [project].name: rsync-server → rsync_server/_version.json
+    try:
+        name = config["project"]["name"].replace("-", "_")
+        return Path(name) / "_version.json", version_file
+    except KeyError as exc:
+        raise RuntimeError(
+            "buildstamp: could not determine metadata file path. "
+            "Add [tool.buildstamp] metadata-file = 'your_package/_version.json' "
+            "to pyproject.toml."
+        ) from exc
+
+
+def write_version_file() -> None:
+    """Write _version.json with build-time metadata.
+
+    Called automatically by all PEP 517 hooks. Can also be called manually.
+    """
+    metadata_file, version_file = _read_config()
+    commit = _git("rev-parse", "--short", "HEAD")
+
+    # sdist → wheel: no .git dir, reuse the JSON baked in during the sdist step.
+    if commit == "unknown" and metadata_file.exists():
+        return
+
+    base = version_file.read_text(encoding="utf-8").strip()
+    raw = os.environ.get("RELEASE_TYPE", "dev").strip().lower()
+    if raw not in ("dev", "rc", "stable"):
+        raise ValueError(f"RELEASE_TYPE must be 'dev', 'rc', or 'stable' — got: {raw!r}")
+    if raw == "stable":
+        version = base
+    elif raw == "rc":
+        version = f"{base}rc1"
+    else:
+        version = f"{base}.dev0"
+
+    metadata_file.write_text(
+        json.dumps(
+            {
+                "version": version,
+                "quality": raw,
+                "commit": commit,
+                "build_date": datetime.now(timezone.utc).isoformat(),
+            },
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+
+
+# --- PEP 517 hooks -----------------------------------------------------------
+
+
+def prepare_metadata_for_build_wheel(metadata_directory, config_settings=None):
+    write_version_file()
+    return _prepare_wheel(metadata_directory, config_settings)
+
+
+def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
+    write_version_file()
+    return _build_wheel(wheel_directory, config_settings, metadata_directory)
+
+
+def build_sdist(sdist_directory, config_settings=None):
+    write_version_file()
+    return _build_sdist(sdist_directory, config_settings)
+
+
+def prepare_metadata_for_build_editable(metadata_directory, config_settings=None):
+    from setuptools.build_meta import (
+        prepare_metadata_for_build_editable as _prepare_editable,
+    )
+
+    write_version_file()
+    return _prepare_editable(metadata_directory, config_settings)
+
+
+def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
+    from setuptools.build_meta import build_editable as _build_editable
+
+    write_version_file()
+    return _build_editable(wheel_directory, config_settings, metadata_directory)

buildstamp-0.3.0/buildstamp.egg-info/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: buildstamp
+Version: 0.3.0
+Summary: Build-time version metadata injection for Python packages.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/basvandriel/buildstamp
+Project-URL: Repository, https://github.com/basvandriel/buildstamp
+Project-URL: Issues, https://github.com/basvandriel/buildstamp/issues
+Project-URL: Changelog, https://github.com/basvandriel/buildstamp/releases
+Keywords: versioning,build,metadata,pep517,setuptools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# buildstamp
+
+[![CI](https://github.com/basvandriel/buildstamp/actions/workflows/ci.yml/badge.svg)](https://github.com/basvandriel/buildstamp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/buildstamp)](https://pypi.org/project/buildstamp/)
+[![Python](https://img.shields.io/pypi/pyversions/buildstamp)](https://pypi.org/project/buildstamp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+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:
+
+```python
+from buildstamp.backend import *  # noqa: F401, F403
+```
+
+**2. Configure `pyproject.toml`:**
+
+```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`:**
+
+```python
+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
+
+```sh
+# 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
+
+```sh
+pip install buildstamp
+```
+
+While not yet on PyPI, install from source:
+
+```sh
+uv pip install setuptools
+uv pip install -e /path/to/buildstamp
+uv pip install -e . --no-build-isolation
+```
+
+---
+
+## Design rationale
+
+See [VERSIONING.md](VERSIONING.md) for the full rationale — including why this
+avoids git tags, dirty flags, and branch names as version sources.

buildstamp-0.3.0/buildstamp.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+MANIFEST.in
+README.md
+VERSION
+_build_backend.py
+pyproject.toml
+buildstamp/__init__.py
+buildstamp/_metadata.py
+buildstamp/backend.py
+buildstamp.egg-info/PKG-INFO
+buildstamp.egg-info/SOURCES.txt
+buildstamp.egg-info/dependency_links.txt
+buildstamp.egg-info/requires.txt
+buildstamp.egg-info/top_level.txt
+tests/test_metadata.py

buildstamp-0.3.0/buildstamp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

buildstamp-0.3.0/buildstamp.egg-info/requires.txt

@@ -0,0 +1,9 @@
+
+[:python_version < "3.11"]
+tomli>=2.0
+
+[dev]
+pytest>=8
+ruff>=0.9
+pyright>=1.1
+twine>=5

buildstamp-0.3.0/buildstamp.egg-info/top_level.txt

@@ -0,0 +1 @@
+buildstamp

buildstamp-0.3.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "buildstamp"
+dynamic = ["version"]
+description = "Build-time version metadata injection for Python packages."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["versioning", "build", "metadata", "pep517", "setuptools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Version Control",
+    "Typing :: Typed",
+]
+dependencies = [
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "ruff>=0.9",
+    "pyright>=1.1",
+    "twine>=5",
+]
+
+[project.urls]
+Homepage = "https://github.com/basvandriel/buildstamp"
+Repository = "https://github.com/basvandriel/buildstamp"
+Issues = "https://github.com/basvandriel/buildstamp/issues"
+Changelog = "https://github.com/basvandriel/buildstamp/releases"
+
+[build-system]
+requires = ["setuptools>=64.0"]
+build-backend = "_build_backend"
+backend-path = ["."]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["buildstamp*"]
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+strict = true
+include = ["buildstamp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "setuptools>=82.0.1",
+]

buildstamp-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

buildstamp-0.3.0/tests/test_metadata.py

@@ -0,0 +1,120 @@
+"""Tests for buildstamp._metadata."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from buildstamp._metadata import BuildMetadata, load_metadata
+
+# ---------------------------------------------------------------------------
+# BuildMetadata
+# ---------------------------------------------------------------------------
+
+
+def test_build_metadata_is_frozen() -> None:
+    meta = BuildMetadata(version="1.0.0", quality="dev", commit="abc1234", build_date=None)
+    with pytest.raises((AttributeError, TypeError)):
+        meta.version = "2.0.0"  # type: ignore[misc]
+
+
+def test_build_metadata_slots() -> None:
+    meta = BuildMetadata(version="1.0.0", quality="dev", commit="abc1234", build_date=None)
+    assert not hasattr(meta, "__dict__")
+
+
+# ---------------------------------------------------------------------------
+# load_metadata — git checkout path
+# ---------------------------------------------------------------------------
+
+
+def _make_pkg(root: Path, version: str = "1.2.3") -> Path:
+    """Create a minimal package tree under root and return the __init__.py path."""
+    pkg = root / "mypkg"
+    pkg.mkdir()
+    (pkg / "__init__.py").write_text("")
+    (root / "VERSION").write_text(f"{version}\n")
+    return pkg / "__init__.py"
+
+
+def test_load_metadata_git_checkout(tmp_path: Path) -> None:
+    (tmp_path / ".git").mkdir()
+    init = _make_pkg(tmp_path)
+
+    with patch("buildstamp._metadata._run_git", return_value="abc1234"):
+        meta = load_metadata(init)
+
+    assert meta.version == "1.2.3+gabc1234"
+    assert meta.quality == "dev"
+    assert meta.commit == "abc1234"
+    assert meta.build_date is None
+
+
+def test_load_metadata_git_unknown_sha(tmp_path: Path) -> None:
+    """When git is not available, version should fall back to .dev0."""
+    (tmp_path / ".git").mkdir()
+    init = _make_pkg(tmp_path)
+
+    with patch("buildstamp._metadata._run_git", return_value="unknown"):
+        meta = load_metadata(init)
+
+    assert meta.version == "1.2.3.dev0"
+    assert meta.commit == "unknown"
+    assert meta.build_date is None
+
+
+def test_load_metadata_git_uses_version_file(tmp_path: Path) -> None:
+    (tmp_path / ".git").mkdir()
+    init = _make_pkg(tmp_path, version="2.0.0")
+
+    with patch("buildstamp._metadata._run_git", return_value="what"):
+        meta = load_metadata(init)
+
+    assert meta.version.startswith("2.0.0+g")
+
+
+# ---------------------------------------------------------------------------
+# load_metadata — artifact / installed package path
+# ---------------------------------------------------------------------------
+
+
+def test_load_metadata_from_version_json(tmp_path: Path) -> None:
+    """Without .git, metadata is read from _version.json."""
+    pkg = tmp_path / "mypkg"
+    pkg.mkdir()
+    init = pkg / "__init__.py"
+    init.write_text("")
+
+    build_date = "2026-04-10T12:00:00+00:00"
+    (pkg / "_version.json").write_text(
+        json.dumps(
+            {
+                "version": "1.2.3",
+                "quality": "stable",
+                "commit": "abc1234",
+                "build_date": build_date,
+            }
+        )
+    )
+
+    meta = load_metadata(init)
+
+    assert meta.version == "1.2.3"
+    assert meta.quality == "stable"
+    assert meta.commit == "abc1234"
+    assert meta.build_date == datetime.fromisoformat(build_date)
+
+
+def test_load_metadata_missing_json_raises(tmp_path: Path) -> None:
+    pkg = tmp_path / "mypkg"
+    pkg.mkdir()
+    init = pkg / "__init__.py"
+    init.write_text("")
+    # no _version.json, no .git
+
+    with pytest.raises((FileNotFoundError, OSError)):
+        load_metadata(init)