add basic documentation for overrides and split up overrides env var parsing

Author: RonnyPfannschmidt

docs/overrides.md

@@ -1 +1,16 @@
-# overrides
+# Overrides
+
+## pretend versions
+
+setuptools_scm provides a mechanism to override the version number build time.
+
+the environment variable `SETUPTOOLS_SCM_PRETEND_VERSION` is used
+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.
+
+## config overrides
+
+setuptools_scm parses the environment variable `SETUPTOOLS_SCM_OVERRIDES_FOR_${NORMALIZED_DIST_NAME}`
+as a toml inline map to override the configuration data from `pyproject.toml`.

src/setuptools_scm/_overrides.py

@@ -3,6 +3,8 @@
 import os
 import re
 from typing import Any
+from typing import cast
+from typing import TypedDict
 
 from . import _config
 from . import _log
@@ -18,6 +20,7 @@
 def read_named_env(
     *, tool: str = "SETUPTOOLS_SCM", name: str, dist_name: str | None
 ) -> str | None:
+    """ """
     if dist_name is not None:
         # Normalize the dist name as per PEP 503.
         normalized_dist_name = re.sub(r"[-_.]+", "-", dist_name)
@@ -48,13 +51,23 @@ def _read_pretended_version_for(
         return None
 
 
+class _CheatTomlData(TypedDict):
+    cheat: dict[str, Any]
+
+
+def load_toml_or_inline_map(data: str | None) -> dict[str, Any]:
+    """
+    load toml data - with a special hack if only a inline map is given
+    """
+    if not data:
+        return {}
+    elif data[0] == "{":
+        data = "cheat=" + data
+        loaded: _CheatTomlData = cast(_CheatTomlData, lazy_toml_load(data))
+        return loaded["cheat"]
+    return lazy_toml_load(data)
+
+
 def read_toml_overrides(dist_name: str | None) -> dict[str, Any]:
     data = read_named_env(name="OVERRIDES", dist_name=dist_name)
-    if data:
-        if data[0] == "{":
-            data = "cheat=" + data
-            loaded = lazy_toml_load(data)
-            return loaded["cheat"]  # type: ignore[no-any-return]
-        return lazy_toml_load(data)
-    else:
-        return {}
+    return load_toml_or_inline_map(data)