Merge pull request #617 from RonnyPfannschmidt/refactor/setuptools-compat-module

Refactor setuptools compatibility and add plugin distribution tests

Author: RonnyPfannschmidt

docs/conf.py

@@ -67,7 +67,7 @@
     # Don't want to expose this yet (see #428).
     ("py:class", "pluggy._tracing.TagTracerSub"),
     # Compat hack, don't want to expose it.
-    ("py:class", "pluggy._manager.DistFacade"),
+    ("py:class", "pluggy._compat.DistFacade"),
     # `types.ModuleType` turns into `module` but then fails to resolve...
     ("py:class", "module"),
     # Just a TypeVar.

src/pluggy/_compat.py

@@ -0,0 +1,44 @@
+"""
+Compatibility layer for legacy setuptools/pkg_resources API.
+
+This module provides backward compatibility wrappers around modern
+importlib.metadata, allowing gradual migration away from setuptools.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+from typing import Any
+
+
+class DistFacade:
+    """Facade providing pkg_resources.Distribution-like interface.
+
+    This class wraps importlib.metadata.Distribution to provide a
+    compatibility layer for code expecting the legacy pkg_resources API.
+    The primary difference is the ``project_name`` attribute which
+    pkg_resources provided but importlib.metadata.Distribution does not.
+    """
+
+    __slots__ = ("_dist",)
+
+    def __init__(self, dist: importlib.metadata.Distribution) -> None:
+        self._dist = dist
+
+    @property
+    def project_name(self) -> str:
+        """Get the project name (for pkg_resources compatibility).
+
+        This is equivalent to dist.metadata["name"] but matches the
+        pkg_resources.Distribution.project_name attribute.
+        """
+        name: str = self.metadata["name"]
+        return name
+
+    def __getattr__(self, attr: str) -> Any:
+        """Delegate all other attributes to the wrapped Distribution."""
+        return getattr(self._dist, attr)
+
+    def __dir__(self) -> list[str]:
+        """List available attributes including facade additions."""
+        return sorted(dir(self._dist) + ["_dist", "project_name"])

src/pluggy/_manager.py

@@ -29,9 +29,10 @@
 
 
 if TYPE_CHECKING:
-    # importtlib.metadata import is slow, defer it.
     import importlib.metadata
 
+    from ._compat import DistFacade
+
 
 _BeforeTrace: TypeAlias = Callable[[str, Sequence[HookImpl], Mapping[str, Any]], None]
 _AfterTrace: TypeAlias = Callable[
@@ -62,24 +63,6 @@ def __init__(self, plugin: _Plugin, message: str) -> None:
         self.plugin = plugin
 
 
-class DistFacade:
-    """Emulate a pkg_resources Distribution"""
-
-    def __init__(self, dist: importlib.metadata.Distribution) -> None:
-        self._dist = dist
-
-    @property
-    def project_name(self) -> str:
-        name: str = self.metadata["name"]
-        return name
-
-    def __getattr__(self, attr: str, default: Any | None = None) -> Any:
-        return getattr(self._dist, attr, default)
-
-    def __dir__(self) -> list[str]:
-        return sorted(dir(self._dist) + ["_dist", "project_name"])
-
-
 class PluginManager:
     """Core class which manages registration of plugin objects and 1:N hook
     calling.
@@ -101,7 +84,9 @@ def __init__(self, project_name: str) -> None:
         #: The project name.
         self.project_name: Final = project_name
         self._name2plugin: Final[dict[str, _Plugin]] = {}
-        self._plugin_distinfo: Final[list[tuple[_Plugin, DistFacade]]] = []
+        self._plugin_distinfo: Final[
+            list[tuple[_Plugin, importlib.metadata.Distribution]]
+        ] = []
         #: The "hook relay", used to call a hook on all registered plugins.
         #: See :ref:`calling`.
         self.hook: Final = HookRelay()
@@ -418,13 +403,32 @@ def load_setuptools_entrypoints(self, group: str, name: str | None = None) -> in
                     continue
                 plugin = ep.load()
                 self.register(plugin, name=ep.name)
-                self._plugin_distinfo.append((plugin, DistFacade(dist)))
+                self._plugin_distinfo.append((plugin, dist))
                 count += 1
         return count
 
     def list_plugin_distinfo(self) -> list[tuple[_Plugin, DistFacade]]:
         """Return a list of (plugin, distinfo) pairs for all
-        setuptools-registered plugins."""
+        setuptools-registered plugins.
+
+        .. note::
+            The distinfo objects are wrapped with :class:`~pluggy._compat.DistFacade`
+            for backward compatibility with the legacy pkg_resources API.
+            Prefer :meth:`list_plugin_distributions` for raw
+            :class:`importlib.metadata.Distribution` objects.
+        """
+        from ._compat import DistFacade
+
+        return [(plugin, DistFacade(dist)) for plugin, dist in self._plugin_distinfo]
+
+    def list_plugin_distributions(
+        self,
+    ) -> list[tuple[_Plugin, importlib.metadata.Distribution]]:
+        """Return a list of (plugin, distribution) pairs for all plugins
+        loaded via entry points.
+
+        .. versionadded:: 1.7
+        """
         return list(self._plugin_distinfo)
 
     def list_name_plugin(self) -> list[tuple[str, _Plugin]]:

testing/test_details.py

@@ -197,14 +197,39 @@ def myhook(self):
 
 
 def test_dist_facade_list_attributes() -> None:
-    from pluggy._manager import DistFacade
+    from pluggy._compat import DistFacade
 
     fc = DistFacade(distribution("pluggy"))
     res = dir(fc)
     assert res == sorted(res)
     assert set(res) - set(dir(fc._dist)) == {"_dist", "project_name"}
 
 
+def test_dist_facade_project_name_and_delegation() -> None:
+    from pluggy._compat import DistFacade
+
+    dist = distribution("pluggy")
+    fc = DistFacade(dist)
+    assert fc.project_name == dist.metadata["name"]
+    assert fc.version == dist.version
+    assert fc._dist is dist
+    with pytest.raises(AttributeError):
+        _ = fc.definitely_missing_attribute
+
+
+def test_dist_facade_identity_equality_and_hash() -> None:
+    from pluggy._compat import DistFacade
+
+    dist = distribution("pluggy")
+    fc1 = DistFacade(dist)
+    fc2 = DistFacade(dist)
+    assert fc1 == fc1
+    assert fc1 is not fc2
+    assert fc1 != fc2
+    assert hash(fc1) == hash(fc1)
+    assert {fc1: "ok"}[fc1] == "ok"
+
+
 def test_hookimpl_disallow_invalid_combination() -> None:
     decorator = hookspec(historic=True, firstresult=True)
     with pytest.raises(ValueError, match="cannot have a historic firstresult hook"):

testing/test_pluginmanager.py

@@ -4,6 +4,7 @@
 
 import importlib.metadata
 from typing import Any
+from typing import cast
 
 import pytest
 
@@ -583,7 +584,9 @@ class NoHooks:
         pm.add_hookspecs(NoHooks)
 
 
-def test_load_setuptools_instantiation(monkeypatch, pm: PluginManager) -> None:
+def test_load_setuptools_instantiation(
+    monkeypatch: pytest.MonkeyPatch, pm: PluginManager
+) -> None:
     class EntryPoint:
         name = "myname"
         group = "hello"
@@ -598,7 +601,8 @@ class PseudoPlugin:
     class Distribution:
         entry_points = (EntryPoint(),)
 
-    dist = Distribution()
+    # Cast mock Distribution to satisfy mypy type checking
+    dist = cast(importlib.metadata.Distribution, Distribution())
 
     def my_distributions():
         return (dist,)
@@ -614,10 +618,13 @@ def my_distributions():
     assert len(ret) == 1
     assert len(ret[0]) == 2
     assert ret[0][0] == plugin
-    assert ret[0][1]._dist == dist  # type: ignore[comparison-overlap]
-    num = pm.load_setuptools_entrypoints("hello")  # type:ignore[unreachable]
+    assert ret[0][1]._dist == dist
+    num = pm.load_setuptools_entrypoints("hello")
     assert num == 0  # no plugin loaded by this call
 
+    ret_distributions = pm.list_plugin_distributions()
+    assert ret_distributions == [(plugin, dist)]
+
 
 def test_add_tracefuncs(he_pm: PluginManager) -> None:
     out: list[Any] = []