pluginkit 0.2.0__tar.gz → 0.3.1__tar.gz

{pluginkit-0.2.0 → pluginkit-0.3.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: pluginkit
-Version: 0.2.0
-Summary: A small, dependency-free plugin framework: hook specs, entry-point discovery, and sync/async dispatch
+Version: 0.3.1
+Summary: A strictly-typed, generics-first plugin framework for Python 3.13: hooks with derived return types
 Keywords: plugins,hooks,protocol,entry-points
 Author: Morten Hansen
 Author-email: Morten Hansen <morten@winterop.com>
@@ -9,12 +9,10 @@ License: MIT
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Python: >=3.11
+Requires-Python: >=3.13
 Project-URL: Homepage, https://github.com/winterop-com/pluginkit
 Project-URL: Repository, https://github.com/winterop-com/pluginkit
 Project-URL: Issues, https://github.com/winterop-com/pluginkit/issues
@@ -29,21 +27,22 @@ Description-Content-Type: text/markdown
 [![Docs](https://img.shields.io/badge/docs-pages-blue.svg)](https://winterop-com.github.io/pluginkit/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-A small, **dependency-free** plugin framework for Python: declare hook
-specifications, let plugins implement them, and discover plugins via entry points.
-Supports sync and async dispatch, hook ordering, wrappers, pipeline (fold)
-dispatch, and historic hooks - in a few readable files.
+A small, **strictly-typed**, generics-first plugin framework for **Python 3.13+**.
+Declare hook specifications, let plugins implement them, discover plugins via entry
+points - and, unlike untyped hook systems, get the **right return type for every
+call**, derived from the spec and checked by your type checker.
 
-The library is three files under `src/pluginkit/` (`markers.py`, `manager.py`,
-`exceptions.py`), has **zero runtime dependencies** (standard library only), runs on
-**Python 3.11+**, and ships a `py.typed` marker.
+`pm.caller(spec)` hands back a caller whose result type matches the dispatch mode -
+`list[R]` for collecting, `R | None` for firstresult, `R` for pipeline - with no
+hand-annotations and no drift. Zero runtime dependencies, a `py.typed` marker, and a
+few readable files.
 
 ```bash
 pip install pluginkit   # or: uv add pluginkit
 ```
 
 ```python
-from pluginkit import HookspecMarker, HookimplMarker, PluginManager
+from pluginkit import HookimplMarker, HookspecMarker, PluginManager
 
 hookspec = HookspecMarker("greeter")
 hookimpl = HookimplMarker("greeter")
@@ -65,7 +64,9 @@ class Casual:
 pm = PluginManager("greeter")
 pm.add_hookspecs(Specs)
 pm.register(Casual(), name="casual")
-print(pm.hook.greeting(name="Ada"))   # ['hey Ada!']
+
+greetings = pm.caller(Specs.greeting)(name="Ada")   # typed list[str] - derived, not asserted
+print(greetings)                                     # ['hey Ada!']
 ```
 
 ## What it supports

{pluginkit-0.2.0 → pluginkit-0.3.1}/README.md

@@ -6,21 +6,22 @@
 [![Docs](https://img.shields.io/badge/docs-pages-blue.svg)](https://winterop-com.github.io/pluginkit/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-A small, **dependency-free** plugin framework for Python: declare hook
-specifications, let plugins implement them, and discover plugins via entry points.
-Supports sync and async dispatch, hook ordering, wrappers, pipeline (fold)
-dispatch, and historic hooks - in a few readable files.
+A small, **strictly-typed**, generics-first plugin framework for **Python 3.13+**.
+Declare hook specifications, let plugins implement them, discover plugins via entry
+points - and, unlike untyped hook systems, get the **right return type for every
+call**, derived from the spec and checked by your type checker.
 
-The library is three files under `src/pluginkit/` (`markers.py`, `manager.py`,
-`exceptions.py`), has **zero runtime dependencies** (standard library only), runs on
-**Python 3.11+**, and ships a `py.typed` marker.
+`pm.caller(spec)` hands back a caller whose result type matches the dispatch mode -
+`list[R]` for collecting, `R | None` for firstresult, `R` for pipeline - with no
+hand-annotations and no drift. Zero runtime dependencies, a `py.typed` marker, and a
+few readable files.
 
 ```bash
 pip install pluginkit   # or: uv add pluginkit
 ```
 
 ```python
-from pluginkit import HookspecMarker, HookimplMarker, PluginManager
+from pluginkit import HookimplMarker, HookspecMarker, PluginManager
 
 hookspec = HookspecMarker("greeter")
 hookimpl = HookimplMarker("greeter")
@@ -42,7 +43,9 @@ class Casual:
 pm = PluginManager("greeter")
 pm.add_hookspecs(Specs)
 pm.register(Casual(), name="casual")
-print(pm.hook.greeting(name="Ada"))   # ['hey Ada!']
+
+greetings = pm.caller(Specs.greeting)(name="Ada")   # typed list[str] - derived, not asserted
+print(greetings)                                     # ['hey Ada!']
 ```
 
 ## What it supports

{pluginkit-0.2.0 → pluginkit-0.3.1}/pyproject.toml

@@ -1,18 +1,16 @@
 [project]
 name = "pluginkit"
-version = "0.2.0"
-description = "A small, dependency-free plugin framework: hook specs, entry-point discovery, and sync/async dispatch"
+version = "0.3.1"
+description = "A strictly-typed, generics-first plugin framework for Python 3.13: hooks with derived return types"
 readme = "README.md"
 authors = [{ name = "Morten Hansen", email = "morten@winterop.com" }]
 license = { text = "MIT" }
-requires-python = ">=3.11"
+requires-python = ">=3.13"
 keywords = ["plugins", "hooks", "protocol", "entry-points"]
 classifiers = [
   "Development Status :: 4 - Beta",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: MIT License",
-  "Programming Language :: Python :: 3.11",
-  "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Typing :: Typed",
@@ -56,7 +54,7 @@ pluginkit-tour = { workspace = true }
 smoothie-extra = { workspace = true }
 
 [tool.ruff]
-target-version = "py311"
+target-version = "py313"
 line-length = 120
 
 [tool.ruff.lint]
@@ -85,7 +83,7 @@ pythonpath = ["examples/recipes", "examples/integrations"]
 norecursedirs = [".git", ".venv", "__pycache__"]
 
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.13"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
@@ -110,7 +108,7 @@ disable_error_code = ["empty-body"]
 include = ["src", "tests", "examples/recipes", "examples/integrations", "examples/tour/src"]
 extraPaths = ["examples/recipes", "examples/integrations", "examples/tour/src"]
 exclude = ["**/.venv"]
-pythonVersion = "3.11"
+pythonVersion = "3.13"
 typeCheckingMode = "strict"
 useLibraryCodeForTypes = true
 reportPrivateUsage = false

pluginkit-0.3.1/src/pluginkit/__init__.py

@@ -0,0 +1,81 @@
+"""pluginkit: a small, strictly-typed, generics-first plugin framework for Python 3.13+.
+
+Unlike untyped hook systems, pluginkit derives a hook call's return type from its
+spec: ``pm.caller(spec)`` hands back a caller whose result is ``list[R]``
+(collecting), ``R | None`` (firstresult), or ``R`` (pipeline) - checked, not asserted.
+
+Public API:
+
+- :class:`HookspecMarker` / :class:`HookimplMarker` - decorators that declare hook
+  specifications and implementations. ``@hookspec`` brands the spec by dispatch mode.
+- :class:`HookspecOpts` / :class:`HookimplOpts` - the option records the markers stamp.
+- :class:`PluginManager` - registers plugins and dispatches hook calls; ``caller(spec)``
+  returns a typed caller.
+- :class:`CollectingSpec` / :class:`FirstResultSpec` / :class:`PipelineSpec` - branded
+  spec types, and :class:`CollectingCaller` / :class:`FirstResultCaller` /
+  :class:`PipelineCaller` (and the ``Async*`` variants) - the typed callers.
+- :class:`HookRelay` / :class:`HookCaller` / :class:`HookImpl` - the dispatch internals.
+- :class:`PluginValidationError` - raised when a plugin is invalid.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from pluginkit.aio import (
+    AsyncCollectingCaller,
+    AsyncFirstResultCaller,
+    AsyncHookCaller,
+    AsyncPipelineCaller,
+    AsyncPluginManager,
+)
+from pluginkit.exceptions import PluginValidationError
+from pluginkit.manager import (
+    CollectingCaller,
+    FirstResultCaller,
+    HistoricCaller,
+    HookCaller,
+    HookImpl,
+    HookRelay,
+    PipelineCaller,
+    PluginManager,
+)
+from pluginkit.markers import (
+    CollectingSpec,
+    FirstResultSpec,
+    HistoricSpec,
+    HookimplMarker,
+    HookimplOpts,
+    HookspecMarker,
+    HookspecOpts,
+    PipelineSpec,
+)
+
+try:
+    __version__ = version("pluginkit")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree without an install
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "AsyncCollectingCaller",
+    "AsyncFirstResultCaller",
+    "AsyncHookCaller",
+    "AsyncPipelineCaller",
+    "AsyncPluginManager",
+    "CollectingCaller",
+    "CollectingSpec",
+    "FirstResultCaller",
+    "FirstResultSpec",
+    "HistoricCaller",
+    "HistoricSpec",
+    "HookCaller",
+    "HookImpl",
+    "HookRelay",
+    "HookimplMarker",
+    "HookimplOpts",
+    "HookspecMarker",
+    "HookspecOpts",
+    "PipelineCaller",
+    "PipelineSpec",
+    "PluginManager",
+    "PluginValidationError",
+    "__version__",
+]

{pluginkit-0.2.0 → pluginkit-0.3.1}/src/pluginkit/aio.py

@@ -15,10 +15,15 @@ a wrapper must transform the result.
 import inspect
 from collections.abc import Callable
 from types import AsyncGeneratorType
-from typing import Any
+from typing import Any, overload
 
 from pluginkit.manager import _UNSET, HookCaller, HookImpl, PluginManager
-from pluginkit.markers import HookimplOpts, HookspecOpts
+from pluginkit.markers import (
+    CollectingSpec,
+    FirstResultSpec,
+    HookspecOpts,
+    PipelineSpec,
+)
 
 
 class AsyncHookCaller(HookCaller):
@@ -28,16 +33,17 @@ class AsyncHookCaller(HookCaller):
         """Await the hook: a list, a single value (firstresult), or the threaded value (pipeline)."""
         if self.spec.historic:
             raise TypeError(f"historic hook {self.name!r} must be called via call_historic()")
-        self.check_arguments(kwargs)
+        kwargs = self.check_arguments(kwargs)
         return await self._execute_async(kwargs, self._nonwrappers)
 
     async def call_extra(self, functions: list[Callable[..., Any]], kwargs: dict[str, Any]) -> Any:
         """Await the hook with extra one-off implementations that are not registered."""
         if self.spec.historic:
             raise TypeError(f"historic hook {self.name!r} must be called via call_historic()")
-        self.check_arguments(kwargs)
-        extra = [HookImpl.from_function("<call_extra>", function, HookimplOpts()) for function in functions]
-        combined = sorted([*self._nonwrappers, *extra], key=lambda candidate: candidate.order_key)
+        kwargs = self.check_arguments(kwargs)
+        combined = sorted(
+            [*self._nonwrappers, *self._prepare_extra(functions)], key=lambda candidate: candidate.order_key
+        )
         return await self._execute_async(kwargs, combined)
 
     def call_historic(self, kwargs: dict[str, Any], result_callback: Callable[[Any], None] | None = None) -> None:
@@ -100,19 +106,61 @@ class AsyncHookCaller(HookCaller):
             except BaseException as new_exc:  # noqa: BLE001 - propagate the wrapper's error onward
                 exc = new_exc
             else:
+                # Double yield: capture the error but keep unwinding the remaining
+                # wrappers so their teardown still runs; raised after the loop.
                 await generator.aclose()
-                raise RuntimeError(f"async wrapper for {self.name!r} must yield exactly once")
+                exc = RuntimeError(f"async wrapper for {self.name!r} must yield exactly once")
         if exc is not None:
             raise exc
         return result
 
 
+# Async typed views returned by AsyncPluginManager.caller(); never instantiated
+# (the runtime object is an AsyncHookCaller). Awaiting a call yields the mode type.
+class AsyncCollectingCaller[**P, R](AsyncHookCaller):
+    """A collecting async hook's typed caller: `await` a call to get `list[R]`."""
+
+    async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> list[R]:
+        """Await the collecting hook, returning each impl's result as `list[R]`."""
+        raise NotImplementedError  # pragma: no cover - the runtime object is an AsyncHookCaller
+
+
+class AsyncFirstResultCaller[**P, R](AsyncHookCaller):
+    """A firstresult async hook's typed caller: `await` a call to get `R | None`."""
+
+    async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R | None:
+        """Await the firstresult hook, returning the first non-None `R` or `None`."""
+        raise NotImplementedError  # pragma: no cover - the runtime object is an AsyncHookCaller
+
+
+class AsyncPipelineCaller[**P, R](AsyncHookCaller):
+    """A pipeline async hook's typed caller: `await` a call to get `R`."""
+
+    async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Await the pipeline hook, returning the threaded value `R`."""
+        raise NotImplementedError  # pragma: no cover - the runtime object is an AsyncHookCaller
+
+
 class AsyncPluginManager(PluginManager):
     """A PluginManager whose hooks are awaited; impls may be coroutine functions."""
 
-    def _make_caller(self, name: str, spec: HookspecOpts, params: tuple[str, ...]) -> HookCaller:
+    def _make_caller(
+        self, name: str, spec: HookspecOpts, params: tuple[str, ...], defaults: dict[str, Any]
+    ) -> HookCaller:
         """Build an AsyncHookCaller instead of the synchronous one."""
-        return AsyncHookCaller(name=name, spec=spec, params=params)
+        return AsyncHookCaller(name=name, spec=spec, params=params, defaults=defaults)
+
+    @overload  # type: ignore[override]  # async manager returns awaitable callers
+    def caller[**P, R](self, spec: FirstResultSpec[P, R]) -> AsyncFirstResultCaller[P, R]: ...
+    @overload
+    def caller[**P, R](self, spec: PipelineSpec[P, R]) -> AsyncPipelineCaller[P, R]: ...
+    @overload
+    def caller[**P, R](self, spec: CollectingSpec[P, R]) -> AsyncCollectingCaller[P, R]: ...
+    def caller(  # pyright: ignore[reportIncompatibleMethodOverride]  # async returns awaitable callers
+        self, spec: object
+    ) -> HookCaller:
+        """Return the typed async caller for a `@hookspec`-decorated spec function."""
+        return self._caller(spec)
 
 
 async def _maybe_await(value: Any) -> Any:

{pluginkit-0.2.0 → pluginkit-0.3.1}/src/pluginkit/manager.py

@@ -23,10 +23,17 @@ from collections.abc import Callable, Generator, Iterator
 from dataclasses import dataclass, field
 from importlib.metadata import entry_points
 from types import GeneratorType
-from typing import Any, Self
+from typing import Any, NoReturn, Self, overload
 
 from pluginkit.exceptions import PluginValidationError
-from pluginkit.markers import HookimplOpts, HookspecOpts
+from pluginkit.markers import (
+    CollectingSpec,
+    FirstResultSpec,
+    HistoricSpec,
+    HookimplOpts,
+    HookspecOpts,
+    PipelineSpec,
+)
 
 # Sentinel distinguishing "no result yet" from a legitimate None result.
 _UNSET: Any = object()
@@ -82,6 +89,10 @@ class HookCaller:
     spec: HookspecOpts
     params: tuple[str, ...] = ()
     argnames: frozenset[str] = frozenset()
+    # Default values for spec params that declare one. A call may omit these (the
+    # branded caller's ParamSpec makes them optional); they are filled in at call
+    # time so the type checker and the runtime agree.
+    defaults: dict[str, Any] = field(default_factory=dict)
     _impls: list[HookImpl] = field(default_factory=list)
     _wrappers: list[HookImpl] = field(default_factory=list)
     _nonwrappers: list[HookImpl] = field(default_factory=list)
@@ -92,11 +103,18 @@ class HookCaller:
         if self.params and not self.argnames:
             self.argnames = frozenset(self.params)
 
-    def check_arguments(self, kwargs: dict[str, Any]) -> None:
-        """Validate that a call supplies exactly the spec's arguments."""
+    def check_arguments(self, kwargs: dict[str, Any]) -> dict[str, Any]:
+        """Fill any omitted defaulted args, then validate the call against the spec.
+
+        Returns the completed kwargs (defaults filled). Spec params with a default
+        are optional at the call site; required params and unknown args are still
+        rejected.
+        """
+        if self.defaults:
+            kwargs = {**self.defaults, **kwargs}
         # dict_keys compares as a set against the frozenset without allocating one.
         if kwargs.keys() == self.argnames:
-            return
+            return kwargs
         provided = frozenset(kwargs)
         problems: list[str] = []
         missing = self.argnames - provided
@@ -130,11 +148,23 @@ class HookCaller:
         """Return whether the named plugin contributes any impl to this hook."""
         return any(impl.plugin_name == plugin_name for impl in self._impls)
 
+    def _prepare_extra(self, functions: list[Callable[..., Any]]) -> list[HookImpl]:
+        """Build one-off impls for call_extra, validating their args against the spec."""
+        extra: list[HookImpl] = []
+        for function in functions:
+            impl = HookImpl.from_function("<call_extra>", function, HookimplOpts())
+            unknown = impl.accepts - self.argnames
+            if unknown:
+                raise TypeError(f"call_extra impl for {self.name!r} declares unknown argument(s) {sorted(unknown)}")
+            impl.passthrough = impl.accepts == self.argnames
+            extra.append(impl)
+        return extra
+
     def __call__(self, **kwargs: Any) -> Any:
         """Call the hook: a list, a single value (firstresult), or the threaded value (pipeline)."""
         if self.spec.historic:
             raise TypeError(f"historic hook {self.name!r} must be called via call_historic()")
-        self.check_arguments(kwargs)
+        kwargs = self.check_arguments(kwargs)
         return self._execute(kwargs, self._nonwrappers)
 
     def call_extra(self, functions: list[Callable[..., Any]], kwargs: dict[str, Any]) -> Any:
@@ -146,23 +176,17 @@ class HookCaller:
         """
         if self.spec.historic:
             raise TypeError(f"historic hook {self.name!r} must be called via call_historic()")
-        self.check_arguments(kwargs)
-        extra: list[HookImpl] = []
-        for function in functions:
-            impl = HookImpl.from_function("<call_extra>", function, HookimplOpts())
-            unknown = impl.accepts - self.argnames
-            if unknown:
-                raise TypeError(f"call_extra impl for {self.name!r} declares unknown argument(s) {sorted(unknown)}")
-            impl.passthrough = impl.accepts == self.argnames
-            extra.append(impl)
-        combined = sorted([*self._nonwrappers, *extra], key=lambda candidate: candidate.order_key)
+        kwargs = self.check_arguments(kwargs)
+        combined = sorted(
+            [*self._nonwrappers, *self._prepare_extra(functions)], key=lambda candidate: candidate.order_key
+        )
         return self._execute(kwargs, combined)
 
     def call_historic(self, kwargs: dict[str, Any], result_callback: Callable[[Any], None] | None = None) -> None:
         """Call a historic hook now and remember it for plugins registered later."""
         if not self.spec.historic:
             raise TypeError(f"hook {self.name!r} is not historic")
-        self.check_arguments(kwargs)
+        kwargs = self.check_arguments(kwargs)
         self._history.append((kwargs, result_callback))
         for outcome in self._collect(kwargs):
             if result_callback is not None:
@@ -259,8 +283,10 @@ class HookCaller:
                 exc = new_exc
             else:
                 # The generator yielded a second time, violating the one-yield contract.
+                # Capture the error but keep unwinding so the remaining wrappers still
+                # tear down; the error propagates through them and is raised at the end.
                 generator.close()
-                raise RuntimeError(f"wrapper for {self.name!r} must yield exactly once")
+                exc = RuntimeError(f"wrapper for {self.name!r} must yield exactly once")
         if exc is not None:
             raise exc
         return result
@@ -274,6 +300,46 @@ class HookCaller:
         return f"<HookCaller {self.name!r} impls={len(self._impls)}>"
 
 
+# Typed views returned by PluginManager.caller(). The runtime object is always a
+# plain HookCaller; these subclasses are never instantiated - they exist only to
+# refine the static return type of a call per dispatch mode, deriving the impl
+# ParamSpec P and return R from the branded spec.
+class CollectingCaller[**P, R](HookCaller):
+    """A collecting hook's typed caller: a call returns `list[R]`."""
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> list[R]:
+        """Call the collecting hook, returning each impl's result as `list[R]`."""
+        raise NotImplementedError  # pragma: no cover - the runtime object is a HookCaller
+
+
+class FirstResultCaller[**P, R](HookCaller):
+    """A firstresult hook's typed caller: a call returns `R | None`."""
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R | None:
+        """Call the firstresult hook, returning the first non-None `R` or `None`."""
+        raise NotImplementedError  # pragma: no cover - the runtime object is a HookCaller
+
+
+class PipelineCaller[**P, R](HookCaller):
+    """A pipeline hook's typed caller: a call returns `R`."""
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Call the pipeline hook, returning the threaded value `R`."""
+        raise NotImplementedError  # pragma: no cover - the runtime object is a HookCaller
+
+
+class HistoricCaller[**P, R](HookCaller):
+    """A historic hook's typed caller. Replay it with `call_historic({...})`.
+
+    Calling it directly raises - historic hooks have no plain call form - so the
+    typed `__call__` is `NoReturn` rather than a value it never produces.
+    """
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> NoReturn:
+        """Historic hooks cannot be called directly; use `call_historic`."""
+        raise NotImplementedError  # pragma: no cover - the runtime object is a HookCaller
+
+
 class HookRelay:
     """Attribute-style access to hook callers, e.g. pm.hook.add_ingredients(...)."""
 
@@ -322,13 +388,48 @@ class PluginManager:
                 spec = getattr(member, self._spec_attribute, None)
                 if not isinstance(spec, HookspecOpts):
                     continue
-                params = tuple(inspect.signature(member).parameters)
+                signature = inspect.signature(member)
+                params = tuple(signature.parameters)
+                defaults = {
+                    name: parameter.default
+                    for name, parameter in signature.parameters.items()
+                    if parameter.default is not inspect.Parameter.empty
+                }
                 self._validate_spec(member_name, spec, params)
-                self.hook._add_caller(self._make_caller(member_name, spec, params))
+                self.hook._add_caller(self._make_caller(member_name, spec, params, defaults))
 
-    def _make_caller(self, name: str, spec: HookspecOpts, params: tuple[str, ...]) -> HookCaller:
+    def _make_caller(
+        self, name: str, spec: HookspecOpts, params: tuple[str, ...], defaults: dict[str, Any]
+    ) -> HookCaller:
         """Build the caller for a spec; overridden by AsyncPluginManager."""
-        return HookCaller(name=name, spec=spec, params=params)
+        return HookCaller(name=name, spec=spec, params=params, defaults=defaults)
+
+    @overload
+    def caller[**P, R](self, spec: FirstResultSpec[P, R]) -> FirstResultCaller[P, R]: ...
+    @overload
+    def caller[**P, R](self, spec: PipelineSpec[P, R]) -> PipelineCaller[P, R]: ...
+    @overload
+    def caller[**P, R](self, spec: HistoricSpec[P, R]) -> HistoricCaller[P, R]: ...
+    @overload
+    def caller[**P, R](self, spec: CollectingSpec[P, R]) -> CollectingCaller[P, R]: ...
+    def caller(self, spec: object) -> HookCaller:
+        """Return the typed caller for a `@hookspec`-decorated spec function.
+
+        The result is a plain `HookCaller`, but its static type carries the spec's
+        dispatch mode, so a call returns `list[R]` (collecting), `R | None`
+        (firstresult), or `R` (pipeline) - derived from the spec, not asserted.
+        """
+        return self._caller(spec)
+
+    def _caller(self, spec: object) -> HookCaller:
+        """Resolve a spec function to its registered caller (shared by subclasses)."""
+        name = getattr(spec, "__name__", None)
+        if not isinstance(name, str):
+            raise TypeError("caller() expects a @hookspec-decorated function")
+        found = self.hook._get_caller(name)
+        if found is None:
+            raise PluginValidationError(self.project_name, f"unknown hook spec {name!r}; call add_hookspecs() first")
+        return found
 
     @staticmethod
     def _validate_spec(name: str, spec: HookspecOpts, params: tuple[str, ...]) -> None:
@@ -360,8 +461,16 @@ class PluginManager:
 
             impls = self._collect_impls(plugin_name, plugin)
             self._name2plugin[plugin_name] = plugin
-            for caller, impl in impls:
-                caller.add_impl(impl)
+            try:
+                for caller, impl in impls:
+                    caller.add_impl(impl)
+            except BaseException:
+                # add_impl can fail mid-loop (e.g. a historic replay raising). Roll the
+                # partial wiring back so registration is all-or-nothing.
+                self._name2plugin.pop(plugin_name, None)
+                for caller in self.hook._all_callers():
+                    caller.remove_plugin(plugin_name)
+                raise
             return plugin_name
 
     def unregister(self, name_or_plugin: str | object) -> object | None:
@@ -431,6 +540,11 @@ class PluginManager:
 
         Returns:
             The number of plugins successfully registered.
+
+        Note:
+            With ``ignore_errors=False``, a failure part-way through leaves the
+            plugins registered before it registered; this method does not roll back
+            across plugins.
         """
         count = 0
         for entry_point in entry_points(group=group):

pluginkit-0.3.1/src/pluginkit/markers.py

@@ -0,0 +1,162 @@
+"""Decorator markers that tag functions as hook specs or hook implementations.
+
+A marker stamps a small frozen dataclass of options onto the decorated function
+under a project-namespaced attribute, so the manager can later recognise specs and
+impls by introspection.
+
+The `@hookspec` decorator is **typed by dispatch mode**: it returns a branded spec
+type (`CollectingSpec` / `FirstResultSpec` / `PipelineSpec`) that carries the impl
+signature (`P`) and per-impl return type (`R`). `PluginManager.caller(spec)` reads
+that brand to hand back a caller whose result type is exactly right for the mode -
+`list[R]`, `R | None`, or `R`. The brand classes are type-level only; they are never
+instantiated (a spec is a declaration, not a callable you invoke directly).
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Literal, overload
+
+
+@dataclass(frozen=True, slots=True)
+class HookspecOpts:
+    """Options attached to a hook specification."""
+
+    firstresult: bool = False
+    historic: bool = False
+    pipeline: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class HookimplOpts:
+    """Options attached to a hook implementation."""
+
+    tryfirst: bool = False
+    trylast: bool = False
+    wrapper: bool = False
+    optionalhook: bool = False
+    specname: str | None = None
+
+
+class CollectingSpec[**P, R]:
+    """A collecting hook spec: a call collects each impl's `R` into `list[R]`."""
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Specs are declarations; obtain a callable via PluginManager.caller(spec)."""
+        raise NotImplementedError("a spec is a declaration; call it via PluginManager.caller(spec)")
+
+
+class FirstResultSpec[**P, R]:
+    """A firstresult hook spec: a call returns the first non-None `R`, or `None`."""
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Specs are declarations; obtain a callable via PluginManager.caller(spec)."""
+        raise NotImplementedError("a spec is a declaration; call it via PluginManager.caller(spec)")
+
+
+class PipelineSpec[**P, R]:
+    """A pipeline hook spec: a call threads `R` through the impls and returns it."""
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Specs are declarations; obtain a callable via PluginManager.caller(spec)."""
+        raise NotImplementedError("a spec is a declaration; call it via PluginManager.caller(spec)")
+
+
+class HistoricSpec[**P, R]:
+    """A historic hook spec: replayed to late plugins, driven via `call_historic`."""
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Specs are declarations; obtain a callable via PluginManager.caller(spec)."""
+        raise NotImplementedError("a spec is a declaration; call it via PluginManager.caller(spec)")
+
+
+class HookspecMarker:
+    """Creates the @hookspec decorator bound to a project name."""
+
+    def __init__(self, project_name: str) -> None:
+        """Bind the marker to a project name used for the stamped attribute."""
+        self.project_name = project_name
+        self.attribute = f"{project_name}_spec"
+
+    @overload
+    def __call__[**P, R](self, function: Callable[P, R]) -> CollectingSpec[P, R]: ...
+    @overload
+    def __call__[**P, R](
+        self, function: None = ..., *, firstresult: Literal[True], historic: bool = ...
+    ) -> Callable[[Callable[P, R]], FirstResultSpec[P, R]]: ...
+    @overload
+    def __call__[**P, R](
+        self, function: None = ..., *, pipeline: Literal[True], historic: bool = ...
+    ) -> Callable[[Callable[P, R]], PipelineSpec[P, R]]: ...
+    @overload
+    def __call__[**P, R](
+        self, function: None = ..., *, historic: Literal[True]
+    ) -> Callable[[Callable[P, R]], HistoricSpec[P, R]]: ...
+    @overload
+    def __call__[**P, R](
+        self, function: None = ..., *, historic: Literal[False] = ...
+    ) -> Callable[[Callable[P, R]], CollectingSpec[P, R]]: ...
+    def __call__(
+        self,
+        function: Callable[..., Any] | None = None,
+        *,
+        firstresult: bool = False,
+        historic: bool = False,
+        pipeline: bool = False,
+    ) -> Any:
+        """Stamp HookspecOpts onto the function; supports bare and called forms."""
+
+        def mark(func: Callable[..., Any]) -> Callable[..., Any]:
+            setattr(func, self.attribute, HookspecOpts(firstresult=firstresult, historic=historic, pipeline=pipeline))
+            return func
+
+        return mark(function) if function is not None else mark
+
+
+class HookimplMarker:
+    """Creates the @hookimpl decorator bound to a project name."""
+
+    def __init__(self, project_name: str) -> None:
+        """Bind the marker to a project name used for the stamped attribute."""
+        self.project_name = project_name
+        self.attribute = f"{project_name}_impl"
+
+    @overload
+    def __call__[F: Callable[..., Any]](self, function: F) -> F: ...
+    @overload
+    def __call__[F: Callable[..., Any]](
+        self,
+        function: None = ...,
+        *,
+        tryfirst: bool = ...,
+        trylast: bool = ...,
+        wrapper: bool = ...,
+        optionalhook: bool = ...,
+        specname: str | None = ...,
+    ) -> Callable[[F], F]: ...
+    def __call__[F: Callable[..., Any]](
+        self,
+        function: F | None = None,
+        *,
+        tryfirst: bool = False,
+        trylast: bool = False,
+        wrapper: bool = False,
+        optionalhook: bool = False,
+        specname: str | None = None,
+    ) -> F | Callable[[F], F]:
+        """Stamp HookimplOpts onto the function; supports bare and called forms."""
+
+        def mark(func: F) -> F:
+            setattr(
+                func,
+                self.attribute,
+                HookimplOpts(
+                    tryfirst=tryfirst,
+                    trylast=trylast,
+                    wrapper=wrapper,
+                    optionalhook=optionalhook,
+                    specname=specname,
+                ),
+            )
+            return func
+
+        return mark(function) if function is not None else mark

pluginkit-0.2.0/src/pluginkit/__init__.py

@@ -1,38 +0,0 @@
-"""pluginkit: a small, dependency-free, pluggy-style plugin framework.
-
-Public API:
-
-- :class:`HookspecMarker` / :class:`HookimplMarker` - decorators that declare hook
-  specifications and implementations.
-- :class:`HookspecOpts` / :class:`HookimplOpts` - the option records the markers stamp.
-- :class:`PluginManager` - registers plugins and dispatches hook calls.
-- :class:`HookRelay` / :class:`HookCaller` / :class:`HookImpl` - the dispatch internals.
-- :class:`PluginValidationError` - raised when a plugin is invalid.
-"""
-
-from pluginkit.aio import AsyncHookCaller, AsyncPluginManager
-from pluginkit.exceptions import PluginValidationError
-from pluginkit.manager import HookCaller, HookImpl, HookRelay, PluginManager
-from pluginkit.markers import (
-    HookimplMarker,
-    HookimplOpts,
-    HookspecMarker,
-    HookspecOpts,
-)
-
-__version__ = "0.1.0"
-
-__all__ = [
-    "AsyncHookCaller",
-    "AsyncPluginManager",
-    "HookCaller",
-    "HookImpl",
-    "HookRelay",
-    "HookimplMarker",
-    "HookimplOpts",
-    "HookspecMarker",
-    "HookspecOpts",
-    "PluginManager",
-    "PluginValidationError",
-    "__version__",
-]

pluginkit-0.2.0/src/pluginkit/markers.py

@@ -1,117 +0,0 @@
-"""Decorator markers that tag functions as hook specs or hook implementations.
-
-Mirrors pluggy's HookspecMarker / HookimplMarker. A marker stamps a small frozen
-dataclass of options onto the decorated function under a project-namespaced
-attribute, so the manager can later recognise specs and impls by introspection.
-"""
-
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import Any, TypeVar, overload
-
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-@dataclass(frozen=True, slots=True)
-class HookspecOpts:
-    """Options attached to a hook specification."""
-
-    firstresult: bool = False
-    historic: bool = False
-    pipeline: bool = False
-
-
-@dataclass(frozen=True, slots=True)
-class HookimplOpts:
-    """Options attached to a hook implementation."""
-
-    tryfirst: bool = False
-    trylast: bool = False
-    wrapper: bool = False
-    optionalhook: bool = False
-    specname: str | None = None
-
-
-class HookspecMarker:
-    """Creates the @hookspec decorator bound to a project name."""
-
-    def __init__(self, project_name: str) -> None:
-        """Bind the marker to a project name used for the stamped attribute."""
-        self.project_name = project_name
-        self.attribute = f"{project_name}_spec"
-
-    @overload
-    def __call__(self, function: F) -> F: ...
-
-    @overload
-    def __call__(
-        self, function: None = ..., *, firstresult: bool = ..., historic: bool = ..., pipeline: bool = ...
-    ) -> Callable[[F], F]: ...
-
-    def __call__(
-        self,
-        function: F | None = None,
-        *,
-        firstresult: bool = False,
-        historic: bool = False,
-        pipeline: bool = False,
-    ) -> F | Callable[[F], F]:
-        """Stamp HookspecOpts onto the function; supports bare and called forms."""
-
-        def mark(func: F) -> F:
-            setattr(func, self.attribute, HookspecOpts(firstresult=firstresult, historic=historic, pipeline=pipeline))
-            return func
-
-        return mark(function) if function is not None else mark
-
-
-class HookimplMarker:
-    """Creates the @hookimpl decorator bound to a project name."""
-
-    def __init__(self, project_name: str) -> None:
-        """Bind the marker to a project name used for the stamped attribute."""
-        self.project_name = project_name
-        self.attribute = f"{project_name}_impl"
-
-    @overload
-    def __call__(self, function: F) -> F: ...
-
-    @overload
-    def __call__(
-        self,
-        function: None = ...,
-        *,
-        tryfirst: bool = ...,
-        trylast: bool = ...,
-        wrapper: bool = ...,
-        optionalhook: bool = ...,
-        specname: str | None = ...,
-    ) -> Callable[[F], F]: ...
-
-    def __call__(
-        self,
-        function: F | None = None,
-        *,
-        tryfirst: bool = False,
-        trylast: bool = False,
-        wrapper: bool = False,
-        optionalhook: bool = False,
-        specname: str | None = None,
-    ) -> F | Callable[[F], F]:
-        """Stamp HookimplOpts onto the function; supports bare and called forms."""
-
-        def mark(func: F) -> F:
-            setattr(
-                func,
-                self.attribute,
-                HookimplOpts(
-                    tryfirst=tryfirst,
-                    trylast=trylast,
-                    wrapper=wrapper,
-                    optionalhook=optionalhook,
-                    specname=specname,
-                ),
-            )
-            return func
-
-        return mark(function) if function is not None else mark