refactor: improve GlobalOverrides API and fix time parameter handling

- Make tool parameter required in GlobalOverrides.from_env() (no default)
- Change env parameter to default directly to os.environ (simplifies code)
- Add UserWarning when auto-creating GlobalOverrides for backwards compatibility
- Update meta() to pass time parameter through to ScmVersion constructor
- Add _ScmVersionKwargs TypedDict for proper typing of constructor arguments
- Fix test_functions.py to pass explicit time to avoid import-time context creation

This prevents unnecessary auto-creation of GlobalOverrides context during module
import and provides better type safety for the meta() function.

Author: RonnyPfannschmidt

setuptools-scm/testing_scm/test_functions.py

@@ -8,6 +8,8 @@
 import shutil
 import subprocess
 
+from datetime import datetime
+from datetime import timezone
 from pathlib import Path
 
 import pytest
@@ -21,8 +23,15 @@
 
 c = Configuration()
 
+# Use explicit time to avoid triggering auto-creation of GlobalOverrides at import time
 VERSIONS = {
-    "exact": meta("1.1", distance=0, dirty=False, config=c),
+    "exact": meta(
+        "1.1",
+        distance=0,
+        dirty=False,
+        config=c,
+        time=datetime(2009, 2, 13, 23, 31, 30, tzinfo=timezone.utc),
+    ),
 }
 
 

vcs-versioning/src/vcs_versioning/_version_schemes.py

@@ -333,6 +333,18 @@ def _parse_tag(
         return tag
 
 
+class _ScmVersionKwargs(TypedDict, total=False):
+    """TypedDict for ScmVersion constructor keyword arguments."""
+
+    distance: int
+    node: str | None
+    dirty: bool
+    preformatted: bool
+    branch: str | None
+    node_date: date | None
+    time: datetime
+
+
 def meta(
     tag: str | _Version,
     *,
@@ -357,18 +369,20 @@ def meta(
 
     log.info("version %s -> %s", tag, parsed_version)
     assert parsed_version is not None, f"Can't parse version {tag}"
-    scm_version = ScmVersion(
-        parsed_version,
-        distance=distance,
-        node=node,
-        dirty=dirty,
-        preformatted=preformatted,
-        branch=branch,
-        config=config,
-        node_date=node_date,
-    )
+
+    # Pass time explicitly to avoid triggering default_factory if provided
+    kwargs: _ScmVersionKwargs = {
+        "distance": distance,
+        "node": node,
+        "dirty": dirty,
+        "preformatted": preformatted,
+        "branch": branch,
+        "node_date": node_date,
+    }
     if time is not None:
-        scm_version = dataclasses.replace(scm_version, time=time)
+        kwargs["time"] = time
+
+    scm_version = ScmVersion(parsed_version, config=config, **kwargs)
     return scm_version
 
 

vcs-versioning/src/vcs_versioning/overrides.py

@@ -19,6 +19,7 @@
 
 import logging
 import os
+import warnings
 from collections.abc import Mapping, MutableMapping
 from contextvars import ContextVar
 from dataclasses import dataclass
@@ -66,8 +67,8 @@ class GlobalOverrides:
     @classmethod
     def from_env(
         cls,
-        tool: str = "SETUPTOOLS_SCM",
-        env: Mapping[str, str] | None = None,
+        tool: str,
+        env: Mapping[str, str] = os.environ,
     ) -> GlobalOverrides:
         """Read all global overrides from environment variables.
 
@@ -80,8 +81,6 @@ def from_env(
         Returns:
             GlobalOverrides instance ready to use as context manager
         """
-        if env is None:
-            env = os.environ
 
         # Helper to read with fallback to VCS_VERSIONING prefix
         def read_with_fallback(name: str) -> str | None:
@@ -281,6 +280,9 @@ def set_var(key: str, value: str) -> None:
     "vcs_versioning_overrides", default=None
 )
 
+# Flag to track if we've already warned about auto-creating context
+_auto_create_warning_issued = False
+
 
 # Accessor functions for getting current override values
 
@@ -289,14 +291,25 @@ def get_active_overrides() -> GlobalOverrides:
     """Get the currently active GlobalOverrides instance.
 
     If no context is active, creates one from the current environment
-    using SETUPTOOLS_SCM prefix.
+    using SETUPTOOLS_SCM prefix for legacy compatibility.
 
     Returns:
         GlobalOverrides instance
     """
+    global _auto_create_warning_issued
+
     overrides = _active_overrides.get()
     if overrides is None:
-        # Auto-create context from environment
+        # Auto-create context from environment for backwards compatibility
+        if not _auto_create_warning_issued:
+            warnings.warn(
+                "No GlobalOverrides context is active. "
+                "Auto-creating one with SETUPTOOLS_SCM prefix for backwards compatibility. "
+                "Consider using 'with GlobalOverrides.from_env(\"YOUR_TOOL\"):' explicitly.",
+                UserWarning,
+                stacklevel=2,
+            )
+            _auto_create_warning_issued = True
         overrides = GlobalOverrides.from_env("SETUPTOOLS_SCM")
     return overrides