refactor: use module-level TYPE_CHECKING imports for lazy annotation resolution

Replace aliased class imports (e.g. VcsEnvironment as _VcsEnvironment)
under TYPE_CHECKING with module imports, then use module.Class in
annotations. Combined with from __future__ import annotations, this
gives proper type checking without Any escape hatches or runtime imports.

Also fix missing assert statements in test_nested_from_active_contexts.

Co-authored-by: Cursor AI <ai@cursor.sh>
Co-authored-by: Anthropic Claude Opus 4 <claude@anthropic.com>

Author: 3 people

vcs-versioning/src/vcs_versioning/_environment.py

@@ -19,8 +19,7 @@
 from typing import TYPE_CHECKING, Any, Literal
 
 if TYPE_CHECKING:
-    from ._config import Configuration
-    from .overrides import EnvReader
+    from . import _config, overrides
 
 log = logging.getLogger(__name__)
 
@@ -69,7 +68,7 @@ def log_level(self) -> int:
             return logging.WARNING
         return self.debug
 
-    def make_reader(self, dist_name: str | None = None) -> EnvReader:
+    def make_reader(self, dist_name: str | None = None) -> overrides.EnvReader:
         """Create an :class:`EnvReader` configured with this env's tool names."""
         from .overrides import EnvReader
 
@@ -139,7 +138,7 @@ def from_env(
             _env=env,
         )
 
-    def build_config(self, **kwargs: Any) -> Configuration:
+    def build_config(self, **kwargs: Any) -> _config.Configuration:
         """Create a ``Configuration`` that carries this environment.
 
         All *kwargs* are forwarded to ``Configuration.from_file``.

vcs-versioning/src/vcs_versioning/overrides.py

@@ -17,11 +17,11 @@
 
 from __future__ import annotations
 
+import contextvars
 import logging
 import os
 from collections.abc import Mapping, MutableMapping
 from contextlib import ContextDecorator
-from contextvars import ContextVar
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, Literal, TypedDict, TypeVar, overload
 
@@ -39,7 +39,7 @@
 if TYPE_CHECKING:
     from pytest import MonkeyPatch
 
-    from ._environment import VcsEnvironment as _VcsEnvironment
+    from . import _environment
 
 log = logging.getLogger(__name__)
 
@@ -266,7 +266,7 @@ class GlobalOverrides:
 
     def __init__(
         self,
-        vcs_env: _VcsEnvironment,
+        vcs_env: _environment.VcsEnvironment,
         tool: str,
         dist_name: str | None = None,
         additional_loggers: tuple[logging.Logger, ...] = (),
@@ -275,7 +275,7 @@ def __init__(
         self.tool = tool
         self.dist_name = dist_name
         self.additional_loggers = additional_loggers
-        self._token: Any = None
+        self._token: contextvars.Token[GlobalOverrides | None] | None = None
 
     # ------------------------------------------------------------------
     # Backward-compatible properties delegating to vcs_env
@@ -466,8 +466,8 @@ def set_var(key: str, value: str) -> None:
 
 
 # Thread-local storage for active global overrides
-_active_overrides: ContextVar[GlobalOverrides | None] = ContextVar(
-    "vcs_versioning_overrides", default=None
+_active_overrides: contextvars.ContextVar[GlobalOverrides | None] = (
+    contextvars.ContextVar("vcs_versioning_overrides", default=None)
 )
 
 
@@ -515,7 +515,7 @@ def __init__(
     def __enter__(self) -> GlobalOverrides:
         """Enter context: create GlobalOverrides if none is active."""
         # Check if there's already an active context
-        existing = _active_overrides.get()
+        existing: GlobalOverrides | None = _active_overrides.get()
 
         if existing is not None:
             # Already have a context, just return it

vcs-versioning/testing_vcs/test_overrides_api.py

@@ -139,22 +139,23 @@ def test_nested_from_active_contexts() -> None:
 
     with GlobalOverrides.from_env("TEST", env={"TEST_DEBUG": "DEBUG"}):
         # Original: DEBUG level
-        assert _active_overrides.get() is not None
-        assert _active_overrides.get().debug == logging.DEBUG  # type: ignore[union-attr]
+        def get_active() -> GlobalOverrides:
+            res = _active_overrides.get()
+            assert res is not None
+            return res
+
+        assert get_active().debug == logging.DEBUG
 
         with GlobalOverrides.from_active(debug=logging.INFO):
             # Modified: INFO level
-            assert _active_overrides.get().debug == logging.INFO  # type: ignore[union-attr]
-
+            assert get_active().debug == logging.INFO
             with GlobalOverrides.from_active(debug=logging.WARNING):
                 # Further modified: WARNING level
-                assert _active_overrides.get().debug == logging.WARNING  # type: ignore[union-attr]
-
+                assert get_active().debug == logging.WARNING
             # Back to INFO
-            assert _active_overrides.get().debug == logging.INFO  # type: ignore[union-attr]
-
+            assert get_active().debug == logging.INFO
         # Back to DEBUG
-        assert _active_overrides.get().debug == logging.DEBUG  # type: ignore[union-attr]
+        assert get_active().debug == logging.DEBUG
 
 
 def test_export_without_source_date_epoch() -> None: