pluginkit 0.2.0__tar.gz → 0.3.0__tar.gz

{pluginkit-0.2.0 → pluginkit-0.3.0}/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.0
+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.0}/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.0}/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.0"
+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.0/src/pluginkit/__init__.py

@@ -0,0 +1,77 @@
+"""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,
+    HookCaller,
+    HookImpl,
+    HookRelay,
+    PipelineCaller,
+    PluginManager,
+)
+from pluginkit.markers import (
+    CollectingSpec,
+    FirstResultSpec,
+    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",
+    "HookCaller",
+    "HookImpl",
+    "HookRelay",
+    "HookimplMarker",
+    "HookimplOpts",
+    "HookspecMarker",
+    "HookspecOpts",
+    "PipelineCaller",
+    "PipelineSpec",
+    "PluginManager",
+    "PluginValidationError",
+    "__version__",
+]

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

@@ -15,10 +15,16 @@ 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,
+    HookimplOpts,
+    HookspecOpts,
+    PipelineSpec,
+)
 
 
 class AsyncHookCaller(HookCaller):
@@ -107,6 +113,32 @@ class AsyncHookCaller(HookCaller):
         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."""
 
@@ -114,6 +146,18 @@ class AsyncPluginManager(PluginManager):
         """Build an AsyncHookCaller instead of the synchronous one."""
         return AsyncHookCaller(name=name, spec=spec, params=params)
 
+    @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:
     """Await a value if it is awaitable, otherwise return it unchanged."""

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

@@ -23,10 +23,16 @@ 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, Self, overload
 
 from pluginkit.exceptions import PluginValidationError
-from pluginkit.markers import HookimplOpts, HookspecOpts
+from pluginkit.markers import (
+    CollectingSpec,
+    FirstResultSpec,
+    HookimplOpts,
+    HookspecOpts,
+    PipelineSpec,
+)
 
 # Sentinel distinguishing "no result yet" from a legitimate None result.
 _UNSET: Any = object()
@@ -274,6 +280,34 @@ 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 HookRelay:
     """Attribute-style access to hook callers, e.g. pm.hook.add_ingredients(...)."""
 
@@ -330,6 +364,31 @@ class PluginManager:
         """Build the caller for a spec; overridden by AsyncPluginManager."""
         return HookCaller(name=name, spec=spec, params=params)
 
+    @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: 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:
         """Reject contradictory or impossible spec option combinations."""

{pluginkit-0.2.0 → pluginkit-0.3.0}/src/pluginkit/markers.py

@@ -1,15 +1,20 @@
 """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.
+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, TypeVar, overload
-
-F = TypeVar("F", bound=Callable[..., Any])
+from typing import Any, Literal, overload
 
 
 @dataclass(frozen=True, slots=True)
@@ -32,6 +37,30 @@ class HookimplOpts:
     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 HookspecMarker:
     """Creates the @hookspec decorator bound to a project name."""
 
@@ -41,24 +70,30 @@ class HookspecMarker:
         self.attribute = f"{project_name}_spec"
 
     @overload
-    def __call__(self, function: F) -> F: ...
-
+    def __call__[**P, R](self, function: Callable[P, R]) -> CollectingSpec[P, R]: ...
     @overload
-    def __call__(
-        self, function: None = ..., *, firstresult: bool = ..., historic: bool = ..., pipeline: bool = ...
-    ) -> Callable[[F], F]: ...
-
+    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: bool = ...
+    ) -> Callable[[Callable[P, R]], CollectingSpec[P, R]]: ...
     def __call__(
         self,
-        function: F | None = None,
+        function: Callable[..., Any] | None = None,
         *,
         firstresult: bool = False,
         historic: bool = False,
         pipeline: bool = False,
-    ) -> F | Callable[[F], F]:
+    ) -> Any:
         """Stamp HookspecOpts onto the function; supports bare and called forms."""
 
-        def mark(func: F) -> F:
+        def mark(func: Callable[..., Any]) -> Callable[..., Any]:
             setattr(func, self.attribute, HookspecOpts(firstresult=firstresult, historic=historic, pipeline=pipeline))
             return func
 
@@ -74,10 +109,9 @@ class HookimplMarker:
         self.attribute = f"{project_name}_impl"
 
     @overload
-    def __call__(self, function: F) -> F: ...
-
+    def __call__[F: Callable[..., Any]](self, function: F) -> F: ...
     @overload
-    def __call__(
+    def __call__[F: Callable[..., Any]](
         self,
         function: None = ...,
         *,
@@ -87,8 +121,7 @@ class HookimplMarker:
         optionalhook: bool = ...,
         specname: str | None = ...,
     ) -> Callable[[F], F]: ...
-
-    def __call__(
+    def __call__[F: Callable[..., Any]](
         self,
         function: F | None = None,
         *,

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__",
-]