hardend environment override finding

- match non-normalized suffixes
- show close matches on miss for typos

Author: RonnyPfannschmidt

src/setuptools_scm/_overrides.py

@@ -2,9 +2,12 @@
 
 import dataclasses
 import os
-import re
 
+from difflib import get_close_matches
 from typing import Any
+from typing import Mapping
+
+from packaging.utils import canonicalize_name
 
 from . import _config
 from . import _log
@@ -19,18 +22,139 @@
 PRETEND_METADATA_KEY_NAMED = PRETEND_METADATA_KEY + "_FOR_{name}"
 
 
+def _search_env_vars_with_prefix(
+    prefix: str, dist_name: str, env: Mapping[str, str]
+) -> list[tuple[str, str]]:
+    """Search environment variables with a given prefix for potential dist name matches.
+
+    Args:
+        prefix: The environment variable prefix (e.g., "SETUPTOOLS_SCM_PRETEND_VERSION_FOR_")
+        dist_name: The original dist name to match against
+        env: Environment dictionary to search in
+
+    Returns:
+        List of (env_var_name, env_var_value) tuples for potential matches
+    """
+    # Get the canonical name for comparison
+    canonical_dist_name = canonicalize_name(dist_name)
+
+    matches = []
+    for env_var, value in env.items():
+        if env_var.startswith(prefix):
+            suffix = env_var[len(prefix) :]
+            # Normalize the suffix and compare to canonical dist name
+            try:
+                normalized_suffix = canonicalize_name(suffix.lower().replace("_", "-"))
+                if normalized_suffix == canonical_dist_name:
+                    matches.append((env_var, value))
+            except Exception:
+                # If normalization fails for any reason, skip this env var
+                continue
+
+    return matches
+
+
+def _find_close_env_var_matches(
+    prefix: str, expected_suffix: str, env: Mapping[str, str], threshold: float = 0.6
+) -> list[str]:
+    """Find environment variables with similar suffixes that might be typos.
+
+    Args:
+        prefix: The environment variable prefix
+        expected_suffix: The expected suffix (canonicalized dist name in env var format)
+        env: Environment dictionary to search in
+        threshold: Similarity threshold for matches (0.0 to 1.0)
+
+    Returns:
+        List of environment variable names that are close matches
+    """
+    candidates = []
+    for env_var in env:
+        if env_var.startswith(prefix):
+            suffix = env_var[len(prefix) :]
+            candidates.append(suffix)
+
+    # Use difflib to find close matches
+    close_matches = get_close_matches(
+        expected_suffix, candidates, n=3, cutoff=threshold
+    )
+
+    return [f"{prefix}{match}" for match in close_matches if match != expected_suffix]
+
+
 def read_named_env(
-    *, tool: str = "SETUPTOOLS_SCM", name: str, dist_name: str | None
+    *,
+    tool: str = "SETUPTOOLS_SCM",
+    name: str,
+    dist_name: str | None,
+    env: Mapping[str, str] = os.environ,
 ) -> str | None:
-    """ """
+    """Read a named environment variable, with fallback search for dist-specific variants.
+
+    This function first tries the standard normalized environment variable name.
+    If that's not found and a dist_name is provided, it searches for alternative
+    normalizations and warns about potential issues.
+
+    Args:
+        tool: The tool prefix (default: "SETUPTOOLS_SCM")
+        name: The environment variable name component
+        dist_name: The distribution name for dist-specific variables
+        env: Environment dictionary to search in (defaults to os.environ)
+
+    Returns:
+        The environment variable value if found, None otherwise
+    """
+
+    # First try the generic version
+    generic_val = env.get(f"{tool}_{name}")
+
     if dist_name is not None:
-        # Normalize the dist name as per PEP 503.
-        normalized_dist_name = re.sub(r"[-_.]+", "-", dist_name)
-        env_var_dist_name = normalized_dist_name.replace("-", "_").upper()
-        val = os.environ.get(f"{tool}_{name}_FOR_{env_var_dist_name}")
+        # Normalize the dist name using packaging.utils.canonicalize_name
+        canonical_dist_name = canonicalize_name(dist_name)
+        env_var_dist_name = canonical_dist_name.replace("-", "_").upper()
+        expected_env_var = f"{tool}_{name}_FOR_{env_var_dist_name}"
+
+        # Try the standard normalized name first
+        val = env.get(expected_env_var)
         if val is not None:
             return val
-    return os.environ.get(f"{tool}_{name}")
+
+        # If not found, search for alternative normalizations
+        prefix = f"{tool}_{name}_FOR_"
+        alternative_matches = _search_env_vars_with_prefix(prefix, dist_name, env)
+
+        if alternative_matches:
+            # Found alternative matches - use the first one but warn
+            env_var, value = alternative_matches[0]
+            log.warning(
+                "Found environment variable '%s' for dist name '%s', "
+                "but expected '%s'. Consider using the standard normalized name.",
+                env_var,
+                dist_name,
+                expected_env_var,
+            )
+            if len(alternative_matches) > 1:
+                other_vars = [var for var, _ in alternative_matches[1:]]
+                log.warning(
+                    "Multiple alternative environment variables found: %s. Using '%s'.",
+                    other_vars,
+                    env_var,
+                )
+            return value
+
+        # No exact or alternative matches found - look for potential typos
+        close_matches = _find_close_env_var_matches(prefix, env_var_dist_name, env)
+        if close_matches:
+            log.warning(
+                "Environment variable '%s' not found for dist name '%s' "
+                "(canonicalized as '%s'). Did you mean one of these? %s",
+                expected_env_var,
+                dist_name,
+                canonical_dist_name,
+                close_matches,
+            )
+
+    return generic_val
 
 
 def _read_pretended_metadata_for(