fix #1059: add scm version overrides via env vars

Author: RonnyPfannschmidt

CHANGELOG.md

@@ -7,7 +7,7 @@
 - add `setuptools-scm` console_scripts entry point to make the CLI directly executable
 - make Mercurial command configurable by environment variable `SETUPTOOLS_SCM_HG_COMMAND`
 - fix #1099 use file modification times for dirty working directory timestamps instead of current time
-
+- fix #1059: add `SETUPTOOLS_SCM_PRETEND_METADATA` environment variable to override individual ScmVersion fields
 ### Changed
 
 - add `pip` to test optional dependencies for improved uv venv compatibility

docs/overrides.md

@@ -10,6 +10,67 @@ as the override source for the version number unparsed string.
 to be specific about the package this applies for, one can use `SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${NORMALIZED_DIST_NAME}`
 where the dist name normalization follows adapted PEP 503 semantics.
 
+## pretend metadata
+
+setuptools-scm provides a mechanism to override individual version metadata fields at build time.
+
+The environment variable `SETUPTOOLS_SCM_PRETEND_METADATA` accepts a TOML inline table
+with field overrides for the ScmVersion object.
+
+To be specific about the package this applies for, one can use `SETUPTOOLS_SCM_PRETEND_METADATA_FOR_${NORMALIZED_DIST_NAME}`
+where the dist name normalization follows adapted PEP 503 semantics.
+
+### Supported fields
+
+The following ScmVersion fields can be overridden:
+
+- `distance` (int): Number of commits since the tag
+- `node` (str): The commit hash/node identifier
+- `dirty` (bool): Whether the working directory has uncommitted changes
+- `branch` (str): The branch name
+- `node_date` (date): The date of the commit (TOML date format: `2024-01-15`)
+- `time` (datetime): The version timestamp (TOML datetime format)
+- `preformatted` (bool): Whether the version string is preformatted
+- `tag`: The version tag (can be string or version object)
+
+### Examples
+
+Override commit hash and distance:
+```bash
+export SETUPTOOLS_SCM_PRETEND_METADATA='{node="g1337beef", distance=4}'
+```
+
+Override multiple fields with proper TOML types:
+```bash
+export SETUPTOOLS_SCM_PRETEND_METADATA='{node="gabcdef12", distance=7, dirty=true, node_date=2024-01-15}'
+```
+
+Use with a specific package:
+```bash
+export SETUPTOOLS_SCM_PRETEND_METADATA_FOR_MY_PACKAGE='{node="g1234567", distance=2}'
+```
+
+### Use case: CI/CD environments
+
+This is particularly useful for solving issues where version file templates need access to
+commit metadata that may not be available in certain build environments:
+
+```toml
+[tool.setuptools_scm]
+version_file = "src/mypackage/_version.py"
+version_file_template = '''
+version = "{version}"
+commit_hash = "{scm_version.node}"
+commit_count = {scm_version.distance}
+'''
+```
+
+With pretend metadata, you can ensure the template gets the correct values:
+```bash
+export SETUPTOOLS_SCM_PRETEND_VERSION="1.2.3.dev4+g1337beef"
+export SETUPTOOLS_SCM_PRETEND_METADATA='{node="g1337beef", distance=4}'
+```
+
 ## config overrides
 
 setuptools-scm parses the environment variable `SETUPTOOLS_SCM_OVERRIDES_FOR_${NORMALIZED_DIST_NAME}`

src/setuptools_scm/_get_version_impl.py

@@ -56,12 +56,18 @@ def parse_fallback_version(config: Configuration) -> ScmVersion | None:
 
 
 def parse_version(config: Configuration) -> ScmVersion | None:
-    return (
+    # First try to get a version from the normal flow
+    scm_version = (
         _read_pretended_version_for(config)
         or parse_scm_version(config)
         or parse_fallback_version(config)
     )
 
+    # Apply any metadata overrides to the version we found
+    from ._overrides import _apply_metadata_overrides
+
+    return _apply_metadata_overrides(scm_version, config)
+
 
 def write_version_files(
     config: Configuration, version: str, scm_version: ScmVersion

src/setuptools_scm/_overrides.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import dataclasses
 import os
 import re
 
@@ -14,6 +15,8 @@
 
 PRETEND_KEY = "SETUPTOOLS_SCM_PRETEND_VERSION"
 PRETEND_KEY_NAMED = PRETEND_KEY + "_FOR_{name}"
+PRETEND_METADATA_KEY = "SETUPTOOLS_SCM_PRETEND_METADATA"
+PRETEND_METADATA_KEY_NAMED = PRETEND_METADATA_KEY + "_FOR_{name}"
 
 
 def read_named_env(
@@ -30,6 +33,124 @@ def read_named_env(
     return os.environ.get(f"{tool}_{name}")
 
 
+def _read_pretended_metadata_for(
+    config: _config.Configuration,
+) -> dict[str, Any] | None:
+    """read overridden metadata from the environment
+
+    tries ``SETUPTOOLS_SCM_PRETEND_METADATA``
+    and ``SETUPTOOLS_SCM_PRETEND_METADATA_FOR_$UPPERCASE_DIST_NAME``
+
+    Returns a dictionary with metadata field overrides like:
+    {"node": "g1337beef", "distance": 4}
+    """
+    log.debug("dist name: %s", config.dist_name)
+
+    pretended = read_named_env(name="PRETEND_METADATA", dist_name=config.dist_name)
+
+    if pretended:
+        try:
+            metadata_overrides = load_toml_or_inline_map(pretended)
+            # Validate that only known ScmVersion fields are provided
+            valid_fields = {
+                "tag",
+                "distance",
+                "node",
+                "dirty",
+                "preformatted",
+                "branch",
+                "node_date",
+                "time",
+            }
+            invalid_fields = set(metadata_overrides.keys()) - valid_fields
+            if invalid_fields:
+                log.warning(
+                    "Invalid metadata fields in pretend metadata: %s. "
+                    "Valid fields are: %s",
+                    invalid_fields,
+                    valid_fields,
+                )
+                # Remove invalid fields but continue processing
+                for field in invalid_fields:
+                    metadata_overrides.pop(field)
+
+            return metadata_overrides or None
+        except Exception as e:
+            log.error("Failed to parse pretend metadata: %s", e)
+            return None
+    else:
+        return None
+
+
+def _apply_metadata_overrides(
+    scm_version: version.ScmVersion | None,
+    config: _config.Configuration,
+) -> version.ScmVersion | None:
+    """Apply metadata overrides to a ScmVersion object.
+
+    This function reads pretend metadata from environment variables and applies
+    the overrides to the given ScmVersion. TOML type coercion is used so values
+    should be provided in their correct types (int, bool, datetime, etc.).
+
+    Args:
+        scm_version: The ScmVersion to apply overrides to, or None
+        config: Configuration object
+
+    Returns:
+        Modified ScmVersion with overrides applied, or None
+    """
+    metadata_overrides = _read_pretended_metadata_for(config)
+
+    if not metadata_overrides:
+        return scm_version
+
+    if scm_version is None:
+        log.warning(
+            "PRETEND_METADATA specified but no base version found. "
+            "Metadata overrides cannot be applied without a base version."
+        )
+        return None
+
+    log.info("Applying metadata overrides: %s", metadata_overrides)
+
+    # Define type checks and field mappings
+    from datetime import date
+    from datetime import datetime
+
+    field_specs: dict[str, tuple[type | tuple[type, type], str]] = {
+        "distance": (int, "int"),
+        "dirty": (bool, "bool"),
+        "preformatted": (bool, "bool"),
+        "node_date": (date, "date"),
+        "time": (datetime, "datetime"),
+        "node": ((str, type(None)), "str or None"),
+        "branch": ((str, type(None)), "str or None"),
+        # tag is special - can be multiple types, handled separately
+    }
+
+    # Apply each override individually using dataclasses.replace for type safety
+    result = scm_version
+
+    for field, value in metadata_overrides.items():
+        if field in field_specs:
+            expected_type, type_name = field_specs[field]
+            assert isinstance(value, expected_type), (
+                f"{field} must be {type_name}, got {type(value).__name__}: {value!r}"
+            )
+            result = dataclasses.replace(result, **{field: value})
+        elif field == "tag":
+            # tag can be Version, NonNormalizedVersion, or str - we'll let the assignment handle validation
+            result = dataclasses.replace(result, tag=value)
+        else:
+            # This shouldn't happen due to validation in _read_pretended_metadata_for
+            log.warning("Unknown field '%s' in metadata overrides", field)
+
+    # Ensure config is preserved (should not be overridden)
+    assert result.config is config, "Config must be preserved during metadata overrides"
+
+    return result
+
+
 def _read_pretended_version_for(
     config: _config.Configuration,
 ) -> version.ScmVersion | None: