turn the version inference config into a protocol and simplify the setuptools integration points

- test fixes : make clean distribution objects

Author: RonnyPfannschmidt

src/setuptools_scm/_integration/setuptools.py

@@ -3,18 +3,13 @@
 import logging
 import warnings
 
-from pathlib import Path
 from typing import Any
 from typing import Callable
 
 import setuptools
 
-from .. import _config
 from .pyproject_reading import read_pyproject
 from .setup_cfg import _dist_name_from_legacy
-from .version_inference import VersionInferenceConfig
-from .version_inference import VersionInferenceError
-from .version_inference import VersionInferenceException
 from .version_inference import get_version_inference_config
 
 log = logging.getLogger(__name__)
@@ -39,22 +34,6 @@ def _warn_on_old_setuptools(_version: str = setuptools.__version__) -> None:
         )
 
 
-def _assign_version(
-    dist: setuptools.Distribution, config: _config.Configuration
-) -> None:
-    from .._get_version_impl import _get_version
-    from .._get_version_impl import _version_missing
-
-    # todo: build time plugin
-    maybe_version = _get_version(config, force_write_version_files=True)
-
-    if maybe_version is None:
-        _version_missing(config)
-    else:
-        assert dist.metadata.version is None
-        dist.metadata.version = maybe_version
-
-
 _warn_on_old_setuptools()
 
 
@@ -80,6 +59,10 @@ def version_keyword(
     keyword: str,
     value: bool | dict[str, Any] | Callable[[], dict[str, Any]],
 ) -> None:
+    """apply version infernce when setup(use_scm_version=...) is used
+    this takes priority over the finalize_options based version
+    """
+
     _log_hookstart("version_keyword", dist)
 
     # Parse overrides (integration point responsibility)
@@ -95,14 +78,11 @@ def version_keyword(
 
     # Get pyproject data
     try:
-        pyproject_data = read_pyproject(
-            Path("pyproject.toml"), missing_section_ok=True, missing_file_ok=True
-        )
+        pyproject_data = read_pyproject(missing_section_ok=True, missing_file_ok=True)
     except (LookupError, ValueError) as e:
         log.debug("Configuration issue in pyproject.toml: %s", e)
         return
 
-    # Get decision
     result = get_version_inference_config(
         dist_name=dist_name,
         current_version=dist.metadata.version,
@@ -111,72 +91,33 @@ def version_keyword(
         was_set_by_infer=was_set_by_infer,
     )
 
-    # Handle result
-    if result is None:
-        return  # Don't infer
-    elif isinstance(result, VersionInferenceError):
-        if result.should_warn:
-            warnings.warn(result.message)
-        return
-    elif isinstance(result, VersionInferenceException):
-        raise result.exception
-    elif isinstance(result, VersionInferenceConfig):
-        # Clear version if it was set by infer_version
-        if was_set_by_infer:
-            dist._setuptools_scm_version_set_by_infer = False  # type: ignore[attr-defined]
-            dist.metadata.version = None
-
-        # Proceed with inference
-        config = _config.Configuration.from_file(
-            dist_name=result.dist_name,
-            pyproject_data=result.pyproject_data,
-            missing_file_ok=True,
-            missing_section_ok=True,
-            **overrides,
-        )
-        _assign_version(dist, config)
+    result.apply(dist)
 
 
 def infer_version(dist: setuptools.Distribution) -> None:
+    """apply version inference from the finalize_options hook
+    this is the default for pyproject.toml based projects that don't use the use_scm_version keyword
+
+    if the version keyword is used, it will override the version from this hook
+    as user might have passed custom code version schemes
+    """
+
     _log_hookstart("infer_version", dist)
 
     dist_name = _dist_name_from_legacy(dist)
 
-    # Get pyproject data (integration point responsibility)
     try:
-        pyproject_data = read_pyproject(Path("pyproject.toml"), missing_section_ok=True)
+        pyproject_data = read_pyproject(missing_section_ok=True)
     except FileNotFoundError:
         log.debug("pyproject.toml not found, skipping infer_version")
         return
     except (LookupError, ValueError) as e:
         log.debug("Configuration issue in pyproject.toml: %s", e)
         return
 
-    # Get decision
     result = get_version_inference_config(
         dist_name=dist_name,
         current_version=dist.metadata.version,
         pyproject_data=pyproject_data,
     )
-
-    # Handle result
-    if result is None:
-        return  # Don't infer
-    elif isinstance(result, VersionInferenceError):
-        if result.should_warn:
-            log.warning(result.message)
-        return
-    elif isinstance(result, VersionInferenceException):
-        raise result.exception
-    elif isinstance(result, VersionInferenceConfig):
-        # Proceed with inference
-        try:
-            config = _config.Configuration.from_file(
-                dist_name=result.dist_name, pyproject_data=result.pyproject_data
-            )
-        except LookupError as e:
-            log.info(e, exc_info=True)
-        else:
-            _assign_version(dist, config)
-            # Mark that this version was set by infer_version
-            dist._setuptools_scm_version_set_by_infer = True  # type: ignore[attr-defined]
+    result.apply(dist)

src/setuptools_scm/_integration/version_inference.py

@@ -19,7 +19,40 @@ class VersionInferenceConfig:
 
     dist_name: str | None
     pyproject_data: PyProjectData | None
-    overrides: dict[str, Any]
+    overrides: dict[str, Any] | None
+
+    def apply(self, dist: Any) -> None:
+        """Apply version inference to the distribution."""
+        from .. import _config as _config_module
+        from .._get_version_impl import _get_version
+        from .._get_version_impl import _version_missing
+
+        # Clear version if it was set by infer_version (overrides is None means infer_version context)
+        # OR if we have overrides (version_keyword context) and the version was set by infer_version
+        was_set_by_infer = getattr(dist, "_setuptools_scm_version_set_by_infer", False)
+        if was_set_by_infer and (self.overrides is None or self.overrides):
+            dist._setuptools_scm_version_set_by_infer = False
+            dist.metadata.version = None
+
+        config = _config_module.Configuration.from_file(
+            dist_name=self.dist_name,
+            pyproject_data=self.pyproject_data,
+            missing_file_ok=True,
+            missing_section_ok=True,
+            **(self.overrides or {}),
+        )
+
+        # Get and assign version
+        maybe_version = _get_version(config, force_write_version_files=True)
+        if maybe_version is None:
+            _version_missing(config)
+        else:
+            assert dist.metadata.version is None
+            dist.metadata.version = maybe_version
+
+        # Mark that this version was set by infer_version if overrides is None (infer_version context)
+        if self.overrides is None:
+            dist._setuptools_scm_version_set_by_infer = True
 
 
 @dataclass
@@ -29,19 +62,37 @@ class VersionInferenceError:
     message: str
     should_warn: bool = False
 
+    def apply(self, dist: Any) -> None:
+        """Apply error handling to the distribution."""
+        import warnings
+
+        if self.should_warn:
+            warnings.warn(self.message)
+
 
 @dataclass
 class VersionInferenceException:
     """Exception that should be raised."""
 
     exception: Exception
 
+    def apply(self, dist: Any) -> None:
+        """Apply exception handling to the distribution."""
+        raise self.exception
+
+
+class VersionInferenceNoOp:
+    """No operation result - silent skip."""
+
+    def apply(self, dist: Any) -> None:
+        """Apply no-op to the distribution."""
+
 
 VersionInferenceResult = Union[
     VersionInferenceConfig,  # Proceed with inference
     VersionInferenceError,  # Show error/warning
     VersionInferenceException,  # Raise exception
-    None,  # Don't infer (silent)
+    VersionInferenceNoOp,  # Don't infer (silent)
 ]
 
 
@@ -71,16 +122,26 @@ def get_version_inference_config(
     # Handle version already set
     if current_version is not None:
         if was_set_by_infer:
-            if overrides is not None:
-                # Clear version and proceed with overrides
+            if overrides is not None and overrides:
+                # Clear version and proceed with actual overrides (non-empty dict)
                 return VersionInferenceConfig(
                     dist_name=dist_name,
                     pyproject_data=pyproject_data,
                     overrides=overrides,
                 )
             else:
-                # Keep existing version from infer_version
-                return None
+                # Keep existing version from infer_version (no overrides or empty overrides)
+                # But allow re-inferring if this is another infer_version call
+                if overrides is None:
+                    # This is another infer_version call, allow it to proceed
+                    return VersionInferenceConfig(
+                        dist_name=dist_name,
+                        pyproject_data=pyproject_data,
+                        overrides=overrides,
+                    )
+                else:
+                    # This is version_keyword with empty overrides, keep existing version
+                    return VersionInferenceNoOp()
         else:
             # Version set by something else
             return VersionInferenceError(
@@ -89,7 +150,7 @@ def get_version_inference_config(
 
     # Handle setuptools-scm package
     if dist_name == "setuptools-scm":
-        return None
+        return VersionInferenceNoOp()
 
     # Handle missing configuration
     if not pyproject_data.is_required and not pyproject_data.section_present:
@@ -100,19 +161,19 @@ def get_version_inference_config(
                 pyproject_data=pyproject_data,
                 overrides=overrides,
             )
-        return None
+        return VersionInferenceNoOp()
 
     # Handle missing project section when required
     if (
         pyproject_data.is_required
         and not pyproject_data.section_present
         and not pyproject_data.project_present
     ):
-        return None
+        return VersionInferenceNoOp()
 
     # All conditions met - proceed with inference
     return VersionInferenceConfig(
         dist_name=dist_name,
         pyproject_data=pyproject_data,
-        overrides=overrides or {},
+        overrides=overrides,
     )

testing/test_integration.py

@@ -656,12 +656,12 @@ def test_setuptools_version_keyword_ensures_regex(
     wd.commit_testfile("test")
     wd("git tag 1.0")
     monkeypatch.chdir(wd.cwd)
-    import setuptools
 
     from setuptools_scm._integration.setuptools import version_keyword
 
-    dist = setuptools.Distribution({"name": "test"})
+    dist = create_clean_distribution("test")
     version_keyword(dist, "use_scm_version", {"tag_regex": "(1.0)"})
+    assert dist.metadata.version == "1.0"
 
 
 @pytest.mark.parametrize(
@@ -917,6 +917,27 @@ def test_improved_error_message_mentions_both_config_options(
     assert "requires" in error_msg
 
 
+# Helper function for creating and managing distribution objects
+def create_clean_distribution(name: str) -> setuptools.Distribution:
+    """Create a clean distribution object without any setuptools_scm effects.
+
+    This function creates a new setuptools Distribution and ensures it's completely
+    clean from any previous setuptools_scm version inference effects, including:
+    - Clearing any existing version
+    - Removing the _setuptools_scm_version_set_by_infer flag
+    """
+    import setuptools
+
+    dist = setuptools.Distribution({"name": name})
+
+    # Clean all setuptools_scm effects
+    dist.metadata.version = None
+    if hasattr(dist, "_setuptools_scm_version_set_by_infer"):
+        delattr(dist, "_setuptools_scm_version_set_by_infer")
+
+    return dist
+
+
 # Helper functions for testing integration point ordering
 def integration_infer_version(dist: setuptools.Distribution) -> str:
     """Helper to call infer_version and return the result."""
@@ -1053,12 +1074,10 @@ def test_infer_version_with_build_requires_no_tool_section(
 """
     wd.write("pyproject.toml", pyproject_content)
 
-    import setuptools
-
     from setuptools_scm._integration.setuptools import infer_version
 
-    # Create distribution
-    dist = setuptools.Distribution({"name": "test-package-infer-version"})
+    # Create clean distribution
+    dist = create_clean_distribution("test-package-infer-version")
 
     # Call infer_version - this should work because setuptools_scm is in build-system.requires
     infer_version(dist)
@@ -1095,12 +1114,10 @@ def test_infer_version_with_build_requires_dash_variant_no_tool_section(
 """
     wd.write("pyproject.toml", pyproject_content)
 
-    import setuptools
-
     from setuptools_scm._integration.setuptools import infer_version
 
-    # Create distribution
-    dist = setuptools.Distribution({"name": "test-package-infer-version-dash"})
+    # Create clean distribution
+    dist = create_clean_distribution("test-package-infer-version-dash")
 
     # Call infer_version - this should work because setuptools-scm is in build-system.requires
     infer_version(dist)
@@ -1137,12 +1154,10 @@ def test_infer_version_without_build_requires_no_tool_section_silently_returns(
 """
     wd.write("pyproject.toml", pyproject_content)
 
-    import setuptools
-
     from setuptools_scm._integration.setuptools import infer_version
 
-    # Create distribution
-    dist = setuptools.Distribution({"name": "test-package-no-scm"})
+    # Create clean distribution
+    dist = create_clean_distribution("test-package-no-scm")
 
     infer_version(dist)
     assert dist.metadata.version is None
@@ -1297,12 +1312,10 @@ def test_infer_version_logs_debug_when_missing_dynamic_version(
 """
     wd.write("pyproject.toml", pyproject_content)
 
-    import setuptools
-
     from setuptools_scm._integration.setuptools import infer_version
 
-    # Create distribution
-    dist = setuptools.Distribution({"name": "test-package-missing-dynamic"})
+    # Create clean distribution
+    dist = create_clean_distribution("test-package-missing-dynamic")
 
     # This should not raise an error, but should log debug info about the configuration issue
     infer_version(dist)