Enhance GlobalOverrides: add dist_name and env_reader property

- Add dist_name parameter to GlobalOverrides.from_env() for distribution-specific overrides
- Add env_reader property that provides pre-configured EnvReader instance
- Store EnvReader created during initialization to reuse throughout context
- __enter__ returns self enabling clean 'with ... as overrides:' pattern
- Add comprehensive tests for env_reader property with and without dist_name

Benefits:
- Convenient access to custom environment variables via overrides.env_reader
- Automatic configuration with correct tool prefix and dist_name
- Single EnvReader instance per context (efficient and consistent)
- Enables dist-specific TOML reading: overrides.env_reader.read_toml()

Tests: 44/44 passing

Author: RonnyPfannschmidt

vcs-versioning/src/vcs_versioning/overrides.py

@@ -212,11 +212,16 @@ class GlobalOverrides:
         hg_command: Command to use for Mercurial operations
         source_date_epoch: Unix timestamp for reproducible builds (None if not set)
         tool: Tool prefix used to read these overrides
+        dist_name: Optional distribution name for dist-specific env var lookups
 
     Usage:
-        with GlobalOverrides.from_env("HATCH_VCS"):
+        with GlobalOverrides.from_env("HATCH_VCS", dist_name="my-package") as overrides:
             # All modules now have access to these overrides
             # Logging is automatically configured based on HATCH_VCS_DEBUG
+
+            # Read custom environment variables
+            custom_val = overrides.env_reader.read("MY_CUSTOM_VAR")
+
             version = get_version(...)
     """
 
@@ -225,12 +230,15 @@ class GlobalOverrides:
     hg_command: str
     source_date_epoch: int | None
     tool: str
+    dist_name: str | None = None
+    _env_reader: EnvReader | None = None  # Cached reader, set by from_env
 
     @classmethod
     def from_env(
         cls,
         tool: str,
         env: Mapping[str, str] = os.environ,
+        dist_name: str | None = None,
     ) -> GlobalOverrides:
         """Read all global overrides from environment variables.
 
@@ -239,13 +247,16 @@ def from_env(
         Args:
             tool: Tool prefix (e.g., "HATCH_VCS", "SETUPTOOLS_SCM")
             env: Environment dict to read from (defaults to os.environ)
+            dist_name: Optional distribution name for dist-specific env var lookups
 
         Returns:
             GlobalOverrides instance ready to use as context manager
         """
 
-        # Use EnvReader to read all environment variables with fallback
-        reader = EnvReader(tools_names=(tool, "VCS_VERSIONING"), env=env)
+        # Create EnvReader for reading environment variables with fallback
+        reader = EnvReader(
+            tools_names=(tool, "VCS_VERSIONING"), env=env, dist_name=dist_name
+        )
 
         # Read debug flag - support multiple formats
         debug_val = reader.read("DEBUG")
@@ -306,6 +317,8 @@ def from_env(
             hg_command=hg_command,
             source_date_epoch=source_date_epoch,
             tool=tool,
+            dist_name=dist_name,
+            _env_reader=reader,
         )
 
     def __enter__(self) -> GlobalOverrides:
@@ -351,6 +364,31 @@ def source_epoch_or_utc_now(self) -> datetime:
         else:
             return datetime.now(timezone.utc)
 
+    @property
+    def env_reader(self) -> EnvReader:
+        """Get the EnvReader configured for this tool and distribution.
+
+        Returns the EnvReader that was created during initialization, configured
+        with this GlobalOverrides' tool prefix, VCS_VERSIONING as fallback, and
+        the optional dist_name for distribution-specific lookups.
+
+        Returns:
+            EnvReader instance ready to read custom environment variables
+
+        Example:
+            >>> with GlobalOverrides.from_env("HATCH_VCS", dist_name="my-package") as overrides:
+            ...     custom_val = overrides.env_reader.read("MY_CUSTOM_VAR")
+            ...     config = overrides.env_reader.read_toml("CONFIG", schema=MySchema)
+        """
+        if self._env_reader is None:
+            # Fallback for instances not created via from_env
+            return EnvReader(
+                tools_names=(self.tool, "VCS_VERSIONING"),
+                env=os.environ,
+                dist_name=self.dist_name,
+            )
+        return self._env_reader
+
     @classmethod
     def from_active(cls, **changes: Any) -> GlobalOverrides:
         """Create a new GlobalOverrides instance based on the currently active one.

vcs-versioning/testing_vcs/test_overrides_api.py

@@ -291,6 +291,51 @@ def test_export_integration_with_subprocess_pattern() -> None:
         # subprocess.run(["cmd"], env=subprocess_env)
 
 
+def test_env_reader_property() -> None:
+    """Test that GlobalOverrides provides a configured EnvReader."""
+    env = {
+        "TOOL_CUSTOM_VAR": "value1",
+        "VCS_VERSIONING_FALLBACK_VAR": "value2",
+        "TOOL_VAR_FOR_MY_PKG": "dist_specific",
+    }
+
+    # Without dist_name
+    with GlobalOverrides.from_env("TOOL", env=env) as overrides:
+        reader = overrides.env_reader
+        assert reader.read("CUSTOM_VAR") == "value1"
+        assert reader.read("FALLBACK_VAR") == "value2"  # Uses VCS_VERSIONING fallback
+        assert reader.read("NONEXISTENT") is None
+
+    # With dist_name
+    with GlobalOverrides.from_env("TOOL", env=env, dist_name="my-pkg") as overrides:
+        reader = overrides.env_reader
+        assert reader.read("VAR") == "dist_specific"  # Dist-specific takes precedence
+
+
+def test_env_reader_property_with_dist_name() -> None:
+    """Test EnvReader property with distribution-specific variables."""
+    env = {
+        "TOOL_CONFIG_FOR_MY_PACKAGE": '{local_scheme = "no-local"}',
+        "TOOL_CONFIG": '{version_scheme = "guess-next-dev"}',
+    }
+
+    from typing import TypedDict
+
+    class TestSchema(TypedDict, total=False):
+        local_scheme: str
+        version_scheme: str
+
+    with GlobalOverrides.from_env("TOOL", env=env, dist_name="my-package") as overrides:
+        # Should read dist-specific TOML
+        config = overrides.env_reader.read_toml("CONFIG", schema=TestSchema)
+        assert config == {"local_scheme": "no-local"}
+
+    # Without dist_name, gets generic
+    with GlobalOverrides.from_env("TOOL", env=env) as overrides:
+        config = overrides.env_reader.read_toml("CONFIG", schema=TestSchema)
+        assert config == {"version_scheme": "guess-next-dev"}
+
+
 class TestEnvReader:
     """Tests for the EnvReader class."""