Add ProjectSpec unified project management API

- Add new ProjectSpec class that manages hook markers and plugin manager creation
- ProjectSpec encapsulates HookspecMarker, HookimplMarker, and PluginManager creation
- Support for custom PluginManager subclasses via plugin_manager_cls parameter
- All components share the same project_name ensuring consistent behavior
- Update marker classes and PluginManager to accept str or ProjectSpec instances
- Use module references (_project.ProjectSpec) to avoid circular imports
- Add comprehensive test suite covering all ProjectSpec functionality

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: RonnyPfannschmidt

CLAUDE.md

@@ -22,6 +22,7 @@ It provides hook specification and implementation mechanisms through a plugin ma
 - `ruff format` - Format code with Ruff
 - `uv run mypy src/` - Type checking with mypy
 - `pre-commit run --all-files` - Run all pre-commit hooks
+- Use pre-commit to lint and fix code
 
 ### Documentation
 - `tox -e docs` - Build documentation

src/pluggy/__init__.py

@@ -11,6 +11,7 @@
     "HookRelay",
     "HookspecMarker",
     "HookimplMarker",
+    "ProjectSpec",
     "Result",
     "PluggyWarning",
     "PluggyTeardownRaisedWarning",
@@ -25,6 +26,7 @@
 from ._hooks import HookspecOpts
 from ._manager import PluginManager
 from ._manager import PluginValidationError
+from ._project import ProjectSpec
 from ._result import HookCallError
 from ._result import Result
 from ._warnings import PluggyTeardownRaisedWarning

src/pluggy/_hooks.py

@@ -23,6 +23,7 @@
 from typing import Union
 import warnings
 
+from . import _project
 from ._result import Result
 
 
@@ -155,15 +156,24 @@ def __repr__(self) -> str:
 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 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_or_spec: str | _project.ProjectSpec) -> None:
+        self._project_spec: Final = (
+            _project.ProjectSpec(project_name_or_spec)
+            if isinstance(project_name_or_spec, str)
+            else project_name_or_spec
+        )
+
+    @property
+    def project_name(self) -> str:
+        """The project name from the associated ProjectSpec."""
+        return self._project_spec.project_name
 
     @overload
     def __call__(
@@ -242,15 +252,24 @@ 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 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_or_spec: str | _project.ProjectSpec) -> None:
+        self._project_spec: Final = (
+            _project.ProjectSpec(project_name_or_spec)
+            if isinstance(project_name_or_spec, str)
+            else project_name_or_spec
+        )
+
+    @property
+    def project_name(self) -> str:
+        """The project name from the associated ProjectSpec."""
+        return self._project_spec.project_name
 
     @overload
     def __call__(

src/pluggy/_manager.py

@@ -12,6 +12,7 @@
 from typing import TYPE_CHECKING
 import warnings
 
+from . import _project
 from . import _tracing
 from ._callers import _multicall
 from ._hooks import _HookImplFunction
@@ -91,13 +92,17 @@ class PluginManager:
     For debugging purposes you can call :meth:`PluginManager.enable_tracing`
     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!
+    :param project_name_or_spec:
+        The short project name (string) or a ProjectSpec instance.
     """
 
-    def __init__(self, project_name: str) -> None:
-        #: The project name.
-        self.project_name: Final = project_name
+    def __init__(self, project_name_or_spec: str | _project.ProjectSpec) -> None:
+        self._project_spec: Final = (
+            _project.ProjectSpec(project_name_or_spec)
+            if isinstance(project_name_or_spec, str)
+            else project_name_or_spec
+        )
+
         self._name2plugin: Final[dict[str, _Plugin]] = {}
         self._plugin_distinfo: Final[list[tuple[_Plugin, DistFacade]]] = []
         #: The "hook relay", used to call a hook on all registered plugins.
@@ -109,6 +114,11 @@ def __init__(self, project_name: str) -> None:
         )
         self._inner_hookexec = _multicall
 
+    @property
+    def project_name(self) -> str:
+        """The project name from the associated ProjectSpec."""
+        return self._project_spec.project_name
+
     def _hookexec(
         self,
         hook_name: str,

src/pluggy/_project.py

@@ -0,0 +1,60 @@
+"""
+Project configuration and management for pluggy projects.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    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: HookspecMarker, HookimplMarker, and 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 PluginManager subclass to use (defaults to PluginManager).
+    """
+
+    def __init__(
+        self, project_name: str, plugin_manager_cls: type[PluginManager] | None = None
+    ) -> None:
+        from ._hooks import HookimplMarker
+        from ._hooks import HookspecMarker
+        from ._manager import PluginManager as DefaultPluginManager
+
+        #: The project name used across all components.
+        self.project_name: Final = project_name
+        #: The PluginManager class for creating new instances.
+        self._plugin_manager_cls: Final = plugin_manager_cls or DefaultPluginManager
+
+        # Create marker instances (these are stateless decorators, safe to share)
+        #: Hook specification marker for decorating hook specification functions.
+        self.hookspec: Final = HookspecMarker(self)
+        #: Hook implementation marker for decorating hook implementation functions.
+        self.hookimpl: Final = HookimplMarker(self)
+
+    def create_plugin_manager(self) -> PluginManager:
+        """Create a new PluginManager instance for this project.
+
+        Each call returns a fresh, independent PluginManager instance
+        configured with this project's name and using the specified
+        PluginManager class (if provided during initialization).
+
+        :returns: New PluginManager instance.
+        """
+        return self._plugin_manager_cls(self)
+
+    def __repr__(self) -> str:
+        return f"ProjectSpec(project_name={self.project_name!r})"