feat(project): add ProjectSpec hub for markers and PluginManager

Complete design step 06: ProjectSpec bundles hookspec/hookimpl markers
and plugin manager creation under a single project name, with
get_hookspec_config / get_hookimpl_config helpers. Markers and
PluginManager accept str | ProjectSpec (strings still work; markers and
manager now expose project_name as a property delegating to the spec).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: RonnyPfannschmidt

changelog/708.feature.rst

@@ -0,0 +1,6 @@
+New :class:`pluggy.ProjectSpec` hub bundles a project's
+:class:`~pluggy.HookspecMarker`, :class:`~pluggy.HookimplMarker` and
+:meth:`~pluggy.ProjectSpec.create_plugin_manager` under one project name.
+:class:`~pluggy.HookspecMarker`, :class:`~pluggy.HookimplMarker` and
+:class:`~pluggy.PluginManager` now accept either a project name string or
+a ``ProjectSpec`` instance; plain strings keep working unchanged.

docs/api_reference.rst

@@ -8,6 +8,9 @@ API Reference
 .. autoclass:: pluggy.PluginManager
     :members:
 
+.. autoclass:: pluggy.ProjectSpec
+    :members:
+
 .. autoclass:: pluggy.PluginValidationError
     :show-inheritance:
     :members:

src/pluggy/__init__.py

@@ -2,6 +2,7 @@
     "__version__",
     "PluginManager",
     "PluginValidationError",
+    "ProjectSpec",
     "HookCaller",
     "NormalHookCaller",
     "HistoricHookCaller",
@@ -35,6 +36,7 @@
 from ._hooks import WrapperImpl
 from ._manager import PluginManager
 from ._manager import PluginValidationError
+from ._project import ProjectSpec
 from ._pytest_compat import HookimplOpts
 from ._pytest_compat import HookspecOpts
 from ._result import HookCallError

src/pluggy/_decorators.py

@@ -19,6 +19,7 @@
 
 from ._config import HookimplConfiguration
 from ._config import HookspecConfiguration
+from ._project import ProjectSpec
 
 
 _F = TypeVar("_F", bound=Callable[..., object])
@@ -30,15 +31,23 @@
 class HookspecMarker:
     """Decorator for marking functions as hook specifications.
 
-    Instantiate it with a project_name to get a decorator.
+    Instantiate it with a project name or :class:`ProjectSpec` to get a
+    decorator.
     Calling :meth:`PluginManager.add_hookspecs` later will discover all marked
     functions if the :class:`PluginManager` uses the same project name.
     """
 
-    __slots__ = ("project_name",)
+    __slots__ = ("_project_spec",)
 
-    def __init__(self, project_name: str) -> None:
-        self.project_name: Final = project_name
+    def __init__(self, project_name: str | ProjectSpec) -> None:
+        self._project_spec: Final = (
+            ProjectSpec(project_name) if isinstance(project_name, str) else project_name
+        )
+
+    @property
+    def project_name(self) -> str:
+        """The project name from the associated :class:`ProjectSpec`."""
+        return self._project_spec.project_name
 
     @overload
     def __call__(
@@ -115,15 +124,23 @@ def setattr_hookspec_opts(func: _F) -> _F:
 class HookimplMarker:
     """Decorator for marking functions as hook implementations.
 
-    Instantiate it with a ``project_name`` to get a decorator.
+    Instantiate it with a project name or :class:`ProjectSpec` to get a
+    decorator.
     Calling :meth:`PluginManager.register` later will discover all marked
     functions if the :class:`PluginManager` uses the same project name.
     """
 
-    __slots__ = ("project_name",)
+    __slots__ = ("_project_spec",)
 
-    def __init__(self, project_name: str) -> None:
-        self.project_name: Final = project_name
+    def __init__(self, project_name: str | ProjectSpec) -> None:
+        self._project_spec: Final = (
+            ProjectSpec(project_name) if isinstance(project_name, str) else project_name
+        )
+
+    @property
+    def project_name(self) -> str:
+        """The project name from the associated :class:`ProjectSpec`."""
+        return self._project_spec.project_name
 
     @overload
     def __call__(

src/pluggy/_manager.py

@@ -32,6 +32,7 @@
 from ._hooks import NormalImpl
 from ._hooks import SubsetHookCaller
 from ._hooks import WrapperImpl
+from ._project import ProjectSpec
 from ._pytest_compat import HookimplOpts
 from ._pytest_compat import HookspecOpts
 from ._result import Result
@@ -86,12 +87,17 @@ class PluginManager:
     which will subsequently send debug information to the trace helper.
 
     :param project_name:
-        The short project name. Prefer snake case. Make sure it's unique!
+        The short project name (prefer snake case, make sure it's unique!),
+        or a :class:`ProjectSpec` instance.
+
+    .. versionchanged:: 1.7
+        A :class:`ProjectSpec` may be passed instead of a plain name.
     """
 
-    def __init__(self, project_name: str) -> None:
-        #: The project name.
-        self.project_name: Final = project_name
+    def __init__(self, project_name: str | ProjectSpec) -> None:
+        self._project_spec: Final = (
+            ProjectSpec(project_name) if isinstance(project_name, str) else project_name
+        )
         self._name2plugin: Final[dict[str, _Plugin]] = {}
         self._plugin_distinfo: Final[
             list[tuple[_Plugin, importlib.metadata.Distribution]]
@@ -105,6 +111,11 @@ def __init__(self, project_name: str) -> None:
         )
         self._inner_hookexec = _multicall
 
+    @property
+    def project_name(self) -> str:
+        """The project name from the associated :class:`ProjectSpec`."""
+        return self._project_spec.project_name
+
     def _hookexec(
         self,
         hook_name: str,

src/pluggy/_project.py

@@ -0,0 +1,86 @@
+"""
+Project configuration hub for pluggy projects.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Final
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from ._config import HookimplConfiguration
+    from ._config import HookspecConfiguration
+    from ._manager import PluginManager
+
+
+class ProjectSpec:
+    """Manages hook markers and plugin manager creation for a pluggy project.
+
+    This class provides a unified interface for creating and managing the
+    core components of a pluggy project: :class:`HookspecMarker`,
+    :class:`HookimplMarker`, and :class:`PluginManager`.
+
+    All components share the same ``project_name``, ensuring consistent
+    behavior across hook specifications, implementations, and plugin
+    management.
+
+    :param project_name:
+        The short project name. Prefer snake case. Make sure it's unique!
+    :param plugin_manager_cls:
+        Custom :class:`PluginManager` subclass to use (defaults to
+        :class:`PluginManager`).
+
+    .. versionadded:: 1.7
+    """
+
+    def __init__(
+        self,
+        project_name: str,
+        plugin_manager_cls: type[PluginManager] | None = None,
+    ) -> None:
+        # Local imports to avoid circular imports with the marker and
+        # manager modules.
+        from ._decorators import HookimplMarker
+        from ._decorators import HookspecMarker
+        from ._manager import PluginManager as DefaultPluginManager
+
+        #: The project name used across all components.
+        self.project_name: Final = project_name
+        self._plugin_manager_cls: Final = plugin_manager_cls or DefaultPluginManager
+
+        # Marker instances are stateless decorators, safe to share.
+        #: Hook specification marker for this project.
+        self.hookspec: Final = HookspecMarker(self)
+        #: Hook implementation marker for this project.
+        self.hookimpl: Final = HookimplMarker(self)
+
+    def create_plugin_manager(self) -> PluginManager:
+        """Create a new :class:`PluginManager` instance for this project.
+
+        Each call returns a fresh, independent instance configured with this
+        project's name.
+        """
+        return self._plugin_manager_cls(self)
+
+    def get_hookspec_config(
+        self, func: Callable[..., object]
+    ) -> HookspecConfiguration | None:
+        """Extract the hook specification configuration from a decorated
+        function, or ``None`` if it is not decorated with this project's
+        hookspec marker."""
+        attr_name = self.project_name + "_spec"
+        return getattr(func, attr_name, None)
+
+    def get_hookimpl_config(
+        self, func: Callable[..., object]
+    ) -> HookimplConfiguration | None:
+        """Extract the hook implementation configuration from a decorated
+        function, or ``None`` if it is not decorated with this project's
+        hookimpl marker."""
+        attr_name = self.project_name + "_impl"
+        return getattr(func, attr_name, None)
+
+    def __repr__(self) -> str:
+        return f"ProjectSpec(project_name={self.project_name!r})"

testing/test_project_spec.py

@@ -0,0 +1,173 @@
+"""
+Tests for ProjectSpec functionality.
+"""
+
+from __future__ import annotations
+
+from pluggy import HookimplMarker
+from pluggy import HookspecMarker
+from pluggy import PluginManager
+from pluggy import ProjectSpec
+
+
+def test_project_spec_basic_creation() -> None:
+    project = ProjectSpec("testproject")
+
+    assert project.project_name == "testproject"
+    assert isinstance(project.hookspec, HookspecMarker)
+    assert isinstance(project.hookimpl, HookimplMarker)
+    assert project.hookspec.project_name == "testproject"
+    assert project.hookimpl.project_name == "testproject"
+    assert repr(project) == "ProjectSpec(project_name='testproject')"
+
+
+def test_project_spec_plugin_manager_creation() -> None:
+    project = ProjectSpec("testproject")
+
+    pm1 = project.create_plugin_manager()
+    pm2 = project.create_plugin_manager()
+
+    assert pm1 is not pm2
+    assert pm1.project_name == "testproject"
+    assert pm2.project_name == "testproject"
+    assert isinstance(pm1, PluginManager)
+    assert isinstance(pm2, PluginManager)
+
+
+def test_project_spec_custom_plugin_manager_class() -> None:
+    class CustomPluginManager(PluginManager):
+        def __init__(self, project_name: str | ProjectSpec) -> None:
+            super().__init__(project_name)
+            self.custom_attr = "custom_value"
+
+    project = ProjectSpec("testproject", plugin_manager_cls=CustomPluginManager)
+    pm = project.create_plugin_manager()
+
+    assert isinstance(pm, CustomPluginManager)
+    assert pm.project_name == "testproject"
+    assert pm.custom_attr == "custom_value"
+
+
+def test_project_spec_functional_integration() -> None:
+    project = ProjectSpec("testproject")
+
+    hookspec = project.hookspec
+    hookimpl = project.hookimpl
+
+    class HookSpecs:
+        @hookspec
+        def my_hook(self, arg: int) -> int:  # type: ignore[empty-body]
+            ...
+
+    class Plugin:
+        @hookimpl
+        def my_hook(self, arg: int) -> int:
+            return arg * 2
+
+    pm = project.create_plugin_manager()
+    pm.add_hookspecs(HookSpecs)
+    pm.register(Plugin())
+
+    result = pm.hook.my_hook(arg=5)
+    assert result == [10]
+
+
+def test_project_spec_multiple_plugin_managers_independent() -> None:
+    project = ProjectSpec("testproject")
+
+    pm1 = project.create_plugin_manager()
+    pm2 = project.create_plugin_manager()
+
+    class Plugin1:
+        pass
+
+    class Plugin2:
+        pass
+
+    pm1.register(Plugin1(), name="plugin1")
+    pm2.register(Plugin2(), name="plugin2")
+
+    assert pm1.has_plugin("plugin1")
+    assert not pm1.has_plugin("plugin2")
+    assert pm2.has_plugin("plugin2")
+    assert not pm2.has_plugin("plugin1")
+
+
+def test_project_spec_hook_attribute_naming() -> None:
+    project = ProjectSpec("myproject")
+
+    @project.hookspec
+    def test_hook() -> None:
+        pass
+
+    @project.hookimpl
+    def test_hook_impl() -> None:
+        pass
+
+    assert hasattr(test_hook, "myproject_spec")
+    assert hasattr(test_hook_impl, "myproject_impl")
+
+
+def test_project_spec_get_hook_configs() -> None:
+    project = ProjectSpec("testproject")
+
+    @project.hookspec(firstresult=True)
+    def my_hook() -> None:
+        pass
+
+    @project.hookimpl(tryfirst=True, optionalhook=True)
+    def my_hook_impl() -> None:
+        pass
+
+    spec_config = project.get_hookspec_config(my_hook)
+    assert spec_config is not None
+    assert spec_config.firstresult is True
+
+    impl_config = project.get_hookimpl_config(my_hook_impl)
+    assert impl_config is not None
+    assert impl_config.tryfirst is True
+    assert impl_config.optionalhook is True
+    assert impl_config.wrapper is False
+
+    def undecorated() -> None:
+        pass
+
+    assert project.get_hookspec_config(undecorated) is None
+    assert project.get_hookimpl_config(undecorated) is None
+
+
+def test_marker_classes_accept_project_spec() -> None:
+    project = ProjectSpec("testproject")
+
+    hookspec_from_project = HookspecMarker(project)
+    hookimpl_from_project = HookimplMarker(project)
+
+    assert hookspec_from_project.project_name == "testproject"
+    assert hookimpl_from_project.project_name == "testproject"
+    assert hookspec_from_project._project_spec is project
+    assert hookimpl_from_project._project_spec is project
+
+
+def test_marker_classes_accept_string() -> None:
+    hookspec_from_string = HookspecMarker("testproject")
+    hookimpl_from_string = HookimplMarker("testproject")
+
+    assert hookspec_from_string.project_name == "testproject"
+    assert hookimpl_from_string.project_name == "testproject"
+    assert hookspec_from_string._project_spec.project_name == "testproject"
+    assert hookimpl_from_string._project_spec.project_name == "testproject"
+
+
+def test_plugin_manager_accepts_project_spec() -> None:
+    project = ProjectSpec("testproject")
+    pm = PluginManager(project)
+
+    assert pm.project_name == "testproject"
+    assert pm._project_spec is project
+
+
+def test_plugin_manager_accepts_string() -> None:
+    pm = PluginManager("testproject")
+
+    assert pm.project_name == "testproject"
+    assert pm._project_spec.project_name == "testproject"