pluginkit 0.1.0__tar.gz

pluginkit-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.3
+Name: pluginkit
+Version: 0.1.0
+Summary: A small, dependency-free plugin framework: hook specs, entry-point discovery, and sync/async dispatch
+Keywords: plugins,hooks,protocol,entry-points
+Author: Morten Hansen
+Author-email: Morten Hansen <morten@winterop.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+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
+Project-URL: Documentation, https://winterop-com.github.io/pluginkit
+Description-Content-Type: text/markdown
+
+# pluginkit
+
+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.
+
+The library is three files under `src/pluginkit/` (`markers.py`, `manager.py`,
+`exceptions.py`), has **zero runtime dependencies** (standard library only), and
+ships a `py.typed` marker.
+
+```python
+from pluginkit import HookspecMarker, HookimplMarker, PluginManager
+
+hookspec = HookspecMarker("greeter")
+hookimpl = HookimplMarker("greeter")
+
+
+class Specs:
+    @staticmethod
+    @hookspec
+    def greeting(name: str) -> str:
+        """Return a greeting for the given name."""
+
+
+class Casual:
+    @hookimpl
+    def greeting(self, name: str) -> str:
+        return f"hey {name}!"
+
+
+pm = PluginManager("greeter")
+pm.add_hookspecs(Specs)
+pm.register(Casual(), name="casual")
+print(pm.hook.greeting(name="Ada"))   # ['hey Ada!']
+```
+
+## What it supports
+
+- collecting, `firstresult`, and **pipeline** (fold/middleware) hooks;
+- call ordering with `tryfirst` / `trylast`, plus `optionalhook` and `specname`;
+- generator **wrappers** that decorate results and observe exceptions safely;
+- **historic** hooks replayed to plugins registered later;
+- **async** dispatch via `AsyncPluginManager` (awaits coroutine impls);
+- plugin lifecycle: `register`, `unregister` (by name or object), `set_blocked`,
+  lookup, `call_extra`;
+- registration-time validation and call-time argument checking (failures are loud);
+- external plugin discovery via the stdlib `importlib.metadata` (no setuptools);
+- thread-safe registry mutation.
+
+## Layout
+
+```
+src/pluginkit/          the library (pure - no demo code)
+tour/                   pluginkit-tour: a guided CLI walkthrough, one step per mechanism
+examples/               standalone single-file recipes, run directly
+plugins/smoothie-extra/ an external plugin distribution (its own uv project)
+docs/                   mkdocs + Material documentation
+tests/                  library, tour, and example tests
+```
+
+The **tour** and **examples** are two complementary ways to learn it: the tour is
+a guided walkthrough on one host (`pluginkit-tour run all`), while the examples
+are independent, real-world recipes you run on their own.
+
+## Use it
+
+```bash
+make install              # uv sync (library + tour + external plugin)
+make test                 # pytest (framework, tour, examples)
+make lint                 # ruff + mypy + pyright
+make docs-serve           # serve the docs at http://127.0.0.1:8000
+make docs-build           # build the docs (strict)
+```
+
+## Two ways to learn it
+
+**The tour** (`tour/`) walks through one mechanism at a time on a single host:
+
+```bash
+make run                  # run every step
+make run DEMO=wrapper      # run one
+uv run pluginkit-tour list
+```
+
+**The examples** apply the library to different realistic domains - see
+[`examples/`](examples/README.md):
+
+```bash
+uv run python examples/report_builder.py
+uv run python examples/notification_router.py
+uv run python examples/validation_rules.py
+uv run python examples/app_lifecycle.py
+```
+
+## Documentation
+
+Full docs (concepts, one page per mechanism, production/hardening notes, and a
+generated API reference) live under [`docs/`](docs/index.md). Serve them with
+`make docs-serve`.
+
+## Is it production ready?
+
+It is solid - exception-safe wrappers, fail-fast validation, lifecycle management,
+resilient discovery, thread-safe mutation, strict typing, and a test suite. But
+for anything you ship, prefer **pluggy** itself: it is maintained and battle
+tested by pytest, tox, and datasette. See
+[docs/production/vs-pluggy.md](docs/production/vs-pluggy.md) for the honest
+inventory of what differs.

pluginkit-0.1.0/README.md

@@ -0,0 +1,109 @@
+# pluginkit
+
+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.
+
+The library is three files under `src/pluginkit/` (`markers.py`, `manager.py`,
+`exceptions.py`), has **zero runtime dependencies** (standard library only), and
+ships a `py.typed` marker.
+
+```python
+from pluginkit import HookspecMarker, HookimplMarker, PluginManager
+
+hookspec = HookspecMarker("greeter")
+hookimpl = HookimplMarker("greeter")
+
+
+class Specs:
+    @staticmethod
+    @hookspec
+    def greeting(name: str) -> str:
+        """Return a greeting for the given name."""
+
+
+class Casual:
+    @hookimpl
+    def greeting(self, name: str) -> str:
+        return f"hey {name}!"
+
+
+pm = PluginManager("greeter")
+pm.add_hookspecs(Specs)
+pm.register(Casual(), name="casual")
+print(pm.hook.greeting(name="Ada"))   # ['hey Ada!']
+```
+
+## What it supports
+
+- collecting, `firstresult`, and **pipeline** (fold/middleware) hooks;
+- call ordering with `tryfirst` / `trylast`, plus `optionalhook` and `specname`;
+- generator **wrappers** that decorate results and observe exceptions safely;
+- **historic** hooks replayed to plugins registered later;
+- **async** dispatch via `AsyncPluginManager` (awaits coroutine impls);
+- plugin lifecycle: `register`, `unregister` (by name or object), `set_blocked`,
+  lookup, `call_extra`;
+- registration-time validation and call-time argument checking (failures are loud);
+- external plugin discovery via the stdlib `importlib.metadata` (no setuptools);
+- thread-safe registry mutation.
+
+## Layout
+
+```
+src/pluginkit/          the library (pure - no demo code)
+tour/                   pluginkit-tour: a guided CLI walkthrough, one step per mechanism
+examples/               standalone single-file recipes, run directly
+plugins/smoothie-extra/ an external plugin distribution (its own uv project)
+docs/                   mkdocs + Material documentation
+tests/                  library, tour, and example tests
+```
+
+The **tour** and **examples** are two complementary ways to learn it: the tour is
+a guided walkthrough on one host (`pluginkit-tour run all`), while the examples
+are independent, real-world recipes you run on their own.
+
+## Use it
+
+```bash
+make install              # uv sync (library + tour + external plugin)
+make test                 # pytest (framework, tour, examples)
+make lint                 # ruff + mypy + pyright
+make docs-serve           # serve the docs at http://127.0.0.1:8000
+make docs-build           # build the docs (strict)
+```
+
+## Two ways to learn it
+
+**The tour** (`tour/`) walks through one mechanism at a time on a single host:
+
+```bash
+make run                  # run every step
+make run DEMO=wrapper      # run one
+uv run pluginkit-tour list
+```
+
+**The examples** apply the library to different realistic domains - see
+[`examples/`](examples/README.md):
+
+```bash
+uv run python examples/report_builder.py
+uv run python examples/notification_router.py
+uv run python examples/validation_rules.py
+uv run python examples/app_lifecycle.py
+```
+
+## Documentation
+
+Full docs (concepts, one page per mechanism, production/hardening notes, and a
+generated API reference) live under [`docs/`](docs/index.md). Serve them with
+`make docs-serve`.
+
+## Is it production ready?
+
+It is solid - exception-safe wrappers, fail-fast validation, lifecycle management,
+resilient discovery, thread-safe mutation, strict typing, and a test suite. But
+for anything you ship, prefer **pluggy** itself: it is maintained and battle
+tested by pytest, tox, and datasette. See
+[docs/production/vs-pluggy.md](docs/production/vs-pluggy.md) for the honest
+inventory of what differs.

pluginkit-0.1.0/pyproject.toml

@@ -0,0 +1,118 @@
+[project]
+name = "pluginkit"
+version = "0.1.0"
+description = "A small, dependency-free plugin framework: hook specs, entry-point discovery, and sync/async dispatch"
+readme = "README.md"
+authors = [{ name = "Morten Hansen", email = "morten@winterop.com" }]
+license = { text = "MIT" }
+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.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+# The library itself has ZERO runtime dependencies (standard library only).
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/winterop-com/pluginkit"
+Repository = "https://github.com/winterop-com/pluginkit"
+Issues = "https://github.com/winterop-com/pluginkit/issues"
+Documentation = "https://winterop-com.github.io/pluginkit"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.20.2",
+  "pyright>=1.1.409",
+  "ruff>=0.15.12",
+  "pytest>=9.0.3",
+  "pytest-cov>=7.1.0",
+  "mkdocs>=1.6.1",
+  "mkdocs-material>=9.7.6",
+  "mkdocstrings[python]>=1.0.4",
+  "pluginkit-tour",  # the walkthrough host, for tour tests and the docs API page
+  "smoothie-extra",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.workspace]
+members = ["tour", "plugins/*"]
+
+[tool.uv.sources]
+pluginkit-tour = { workspace = true }
+smoothie-extra = { workspace = true }
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+select = ["E", "W", "F", "I", "D"]
+ignore = ["D203", "D213"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D"]
+"**/__init__.py" = ["D104"]
+"src/**/*.py" = ["D105", "D107"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["examples"]
+norecursedirs = [".git", ".venv", "__pycache__"]
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_unused_ignores = true
+strict_equality = true
+mypy_path = ["src", "tour/src", "examples"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+# Tests define inline hook specs whose bodies are intentionally empty.
+disable_error_code = ["empty-body"]
+
+# Hook specs are intentionally empty (signature + docstring only).
+[[tool.mypy.overrides]]
+module = "pluginkit_tour.hookspecs"
+disable_error_code = ["empty-body"]
+
+[tool.pyright]
+include = ["src", "tests", "examples", "tour/src"]
+extraPaths = ["examples", "tour/src"]
+exclude = ["**/.venv"]
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+useLibraryCodeForTypes = true
+reportPrivateUsage = false
+reportUnusedFunction = false
+reportMissingModuleSource = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownParameterType = false
+reportUnknownVariableType = false
+reportUnknownLambdaType = false
+reportMissingTypeArgument = false

pluginkit-0.1.0/src/pluginkit/__init__.py

@@ -0,0 +1,38 @@
+"""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.1.0/src/pluginkit/aio.py

@@ -0,0 +1,122 @@
+"""Async dispatch: an AsyncPluginManager that awaits coroutine implementations.
+
+The registration, validation and lifecycle machinery is reused unchanged from the
+synchronous manager; only the *calling* path is asynchronous. Implementations may
+be plain functions or coroutine functions - their results are awaited when
+awaitable. Collecting, firstresult and pipeline dispatch are all supported.
+
+Wrappers in the async manager are **async generators** and are observe-only: they
+run setup before `yield` and teardown after it (including in a `finally`), and
+they observe exceptions thrown back in, but - because async generators cannot
+return a value - they do not replace the result. Use the synchronous manager when
+a wrapper must transform the result.
+"""
+
+import inspect
+from collections.abc import Callable
+from types import AsyncGeneratorType
+from typing import Any
+
+from pluginkit.manager import _UNSET, HookCaller, HookImpl, PluginManager
+from pluginkit.markers import HookimplOpts, HookspecOpts
+
+
+class AsyncHookCaller(HookCaller):
+    """A HookCaller whose calls are coroutines that await async implementations."""
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        """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)
+        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)
+        return await self._execute_async(kwargs, combined)
+
+    def call_historic(self, kwargs: dict[str, Any], result_callback: Callable[[Any], None] | None = None) -> None:
+        """Historic hooks are not supported by the async manager."""
+        raise NotImplementedError("historic hooks are not supported by AsyncPluginManager")
+
+    async def _execute_async(self, kwargs: dict[str, Any], nonwrappers: list[HookImpl]) -> Any:
+        """Start async wrappers, run the impls, then unwind wrappers exception-safely."""
+        started: list[AsyncGeneratorType[Any, Any]] = []
+        try:
+            for wrapper in self._wrappers:
+                generator = wrapper.call(kwargs)
+                if not isinstance(generator, AsyncGeneratorType):
+                    raise TypeError(f"async wrapper {wrapper.plugin_name}.{self.name} must be an async generator")
+                await generator.__anext__()  # advance to the yield
+                started.append(generator)
+            result = await self._core_async(kwargs, nonwrappers)
+        except BaseException as exc:  # noqa: BLE001 - re-raised after wrappers observe it
+            return await self._teardown_async(started, exc=exc)
+        return await self._teardown_async(started, result=result)
+
+    async def _core_async(self, kwargs: dict[str, Any], nonwrappers: list[HookImpl]) -> Any:
+        """Apply the spec's dispatch strategy, awaiting any awaitable results."""
+        if self.spec.pipeline:
+            return await self._run_pipeline_async(kwargs, nonwrappers)
+        results: list[Any] = []
+        for impl in nonwrappers:
+            outcome = await _maybe_await(impl.call(kwargs))
+            if outcome is None:
+                continue
+            results.append(outcome)
+            if self.spec.firstresult:
+                break
+        return (results[0] if results else None) if self.spec.firstresult else results
+
+    async def _run_pipeline_async(self, kwargs: dict[str, Any], nonwrappers: list[HookImpl]) -> Any:
+        """Thread the first argument through each impl, awaiting awaitable results."""
+        param = self.params[0]
+        value = kwargs[param]
+        current = dict(kwargs)
+        for impl in nonwrappers:
+            current[param] = value
+            outcome = await _maybe_await(impl.call(current))
+            if outcome is not None:
+                value = outcome
+        return value
+
+    async def _teardown_async(
+        self, started: list[AsyncGeneratorType[Any, Any]], *, result: Any = _UNSET, exc: BaseException | None = None
+    ) -> Any:
+        """Resume each async wrapper in reverse so its teardown runs and it observes errors."""
+        for generator in reversed(started):
+            try:
+                if exc is not None:
+                    await generator.athrow(exc)
+                else:
+                    await generator.asend(result)
+            except StopAsyncIteration:
+                pass  # normal completion; async wrappers cannot replace the result
+            except BaseException as new_exc:  # noqa: BLE001 - propagate the wrapper's error onward
+                exc = new_exc
+            else:
+                await generator.aclose()
+                raise RuntimeError(f"async wrapper for {self.name!r} must yield exactly once")
+        if exc is not None:
+            raise exc
+        return result
+
+
+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:
+        """Build an AsyncHookCaller instead of the synchronous one."""
+        return AsyncHookCaller(name=name, spec=spec, params=params)
+
+
+async def _maybe_await(value: Any) -> Any:
+    """Await a value if it is awaitable, otherwise return it unchanged."""
+    if inspect.isawaitable(value):
+        return await value
+    return value

pluginkit-0.1.0/src/pluginkit/exceptions.py

@@ -0,0 +1,10 @@
+"""Exceptions raised by the plugin framework."""
+
+
+class PluginValidationError(Exception):
+    """Raised when a plugin or one of its hook implementations is invalid."""
+
+    def __init__(self, plugin_name: str, message: str) -> None:
+        """Record the offending plugin name alongside the message."""
+        self.plugin_name = plugin_name
+        super().__init__(f"plugin {plugin_name!r}: {message}")

pluginkit-0.1.0/src/pluginkit/manager.py

@@ -0,0 +1,474 @@
+"""The plugin manager: registers plugins and dispatches calls to their hooks.
+
+A compact but hardened reimplementation of the pluggy ideas worth understanding:
+
+- introspection-based discovery of specs and impls via stamped attributes;
+- registration-time validation that impl arguments exist in the spec;
+- per-impl keyword-argument filtering so an impl declares only what it needs;
+- call ordering with tryfirst / trylast;
+- collecting vs firstresult dispatch;
+- generator wrappers that decorate the result and observe exceptions safely;
+- historic hooks replayed to plugins registered later;
+- plugin lifecycle: unregister, blocking, and lookup;
+- external plugin discovery via the stdlib importlib.metadata.
+
+The manager is safe to mutate (register / unregister / block) from multiple
+threads; hook *calls* are not internally locked and should be coordinated by the
+caller if they can race with registration.
+"""
+
+import inspect
+import threading
+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 pluginkit.exceptions import PluginValidationError
+from pluginkit.markers import HookimplOpts, HookspecOpts
+
+# Sentinel distinguishing "no result yet" from a legitimate None result.
+_UNSET: Any = object()
+
+
+@dataclass(slots=True)
+class HookImpl:
+    """One plugin's implementation of a hook, plus the kwargs it accepts."""
+
+    plugin_name: str
+    function: Callable[..., Any]
+    opts: HookimplOpts
+    accepts: frozenset[str]
+    params: tuple[str, ...]
+    # Set by the caller once it knows the hook's full argument set: True when this
+    # impl declares exactly those arguments, so kwargs can be forwarded directly.
+    passthrough: bool = False
+
+    @classmethod
+    def from_function(cls, plugin_name: str, function: Callable[..., Any], opts: HookimplOpts) -> Self:
+        """Build an impl, recording which keyword arguments the function declares."""
+        params = tuple(inspect.signature(function).parameters)
+        return cls(plugin_name=plugin_name, function=function, opts=opts, accepts=frozenset(params), params=params)
+
+    def call(self, kwargs: dict[str, Any]) -> Any:
+        """Invoke the function, passing only the arguments it declares.
+
+        The caller guarantees every declared argument is present in kwargs, so the
+        common "takes all the spec's arguments" case forwards kwargs directly and a
+        subset impl indexes the few it wants - both avoiding a membership scan.
+        """
+        if self.passthrough:
+            return self.function(**kwargs)
+        return self.function(**{name: kwargs[name] for name in self.params})
+
+    @property
+    def order_key(self) -> int:
+        """Sort key: tryfirst impls run first (0), normal next (1), trylast last (2)."""
+        match self.opts:
+            case HookimplOpts(tryfirst=True):
+                return 0
+            case HookimplOpts(trylast=True):
+                return 2
+            case _:
+                return 1
+
+
+@dataclass(slots=True)
+class HookCaller:
+    """Holds every implementation of one hook and dispatches calls to them."""
+
+    name: str
+    spec: HookspecOpts
+    params: tuple[str, ...] = ()
+    argnames: frozenset[str] = frozenset()
+    _impls: list[HookImpl] = field(default_factory=list)
+    _wrappers: list[HookImpl] = field(default_factory=list)
+    _nonwrappers: list[HookImpl] = field(default_factory=list)
+    _history: list[tuple[dict[str, Any], Callable[[Any], None] | None]] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        """Derive the argument-name set from the ordered parameters when given."""
+        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."""
+        # dict_keys compares as a set against the frozenset without allocating one.
+        if kwargs.keys() == self.argnames:
+            return
+        provided = frozenset(kwargs)
+        problems: list[str] = []
+        missing = self.argnames - provided
+        unknown = provided - self.argnames
+        if missing:
+            problems.append(f"missing {sorted(missing)}")
+        if unknown:
+            problems.append(f"unknown {sorted(unknown)}")
+        raise TypeError(f"hook {self.name!r} called with {'; '.join(problems)}; expects {sorted(self.argnames)}")
+
+    def add_impl(self, impl: HookImpl) -> None:
+        """Add an impl in priority order and replay any historic calls to it."""
+        impl.passthrough = impl.accepts == self.argnames
+        self._impls.append(impl)
+        self._reindex()
+        for kwargs, callback in self._history:
+            outcome = impl.call(kwargs)
+            if outcome is not None and callback is not None:
+                callback(outcome)
+
+    def remove_plugin(self, plugin_name: str) -> bool:
+        """Drop every impl contributed by a plugin; return True if any were removed."""
+        before = len(self._impls)
+        self._impls = [impl for impl in self._impls if impl.plugin_name != plugin_name]
+        removed = len(self._impls) != before
+        if removed:
+            self._reindex()
+        return removed
+
+    def has_plugin(self, plugin_name: str) -> bool:
+        """Return whether the named plugin contributes any impl to this hook."""
+        return any(impl.plugin_name == plugin_name for impl in self._impls)
+
+    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)
+        return self._execute(kwargs, self._nonwrappers)
+
+    def call_extra(self, functions: list[Callable[..., Any]], kwargs: dict[str, Any]) -> Any:
+        """Call the hook with extra one-off implementations that are not registered.
+
+        The extra functions run as normal-priority implementations for this call
+        only, ordered after the already-registered ones. Useful for tests and for
+        injecting a temporary implementation without mutating the manager.
+        """
+        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)
+        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)
+        self._history.append((kwargs, result_callback))
+        for outcome in self._collect(kwargs):
+            if result_callback is not None:
+                result_callback(outcome)
+
+    def _reindex(self) -> None:
+        """Re-sort impls by priority and refresh the wrapper / non-wrapper split."""
+        # Stable sort keeps registration order within each priority bucket.
+        self._impls.sort(key=lambda candidate: candidate.order_key)
+        self._wrappers = [impl for impl in self._impls if impl.opts.wrapper]
+        self._nonwrappers = [impl for impl in self._impls if not impl.opts.wrapper]
+
+    def _execute(self, kwargs: dict[str, Any], nonwrappers: list[HookImpl]) -> Any:
+        """Run the inner impls, wrapped by any wrappers, unwinding exception-safely."""
+        # Fast path: with no wrappers there is nothing to unwind, so skip the
+        # try/except and generator bookkeeping entirely and let errors propagate.
+        if not self._wrappers:
+            return self._core(kwargs, nonwrappers)
+        started: list[Generator[Any, Any, Any]] = []
+        try:
+            for wrapper in self._wrappers:
+                generator = wrapper.call(kwargs)
+                if not isinstance(generator, GeneratorType):
+                    raise TypeError(f"wrapper {wrapper.plugin_name}.{self.name} must be a generator function")
+                next(generator)  # advance to the yield
+                started.append(generator)
+            result = self._core(kwargs, nonwrappers)
+        except BaseException as exc:  # noqa: BLE001 - re-raised after wrappers observe it
+            return self._teardown(started, exc=exc)
+        return self._teardown(started, result=result)
+
+    def _core(self, kwargs: dict[str, Any], nonwrappers: list[HookImpl]) -> Any:
+        """Apply the spec's dispatch strategy to the non-wrapper impls."""
+        if self.spec.pipeline:
+            return self._run_pipeline(kwargs, nonwrappers)
+        if self.spec.firstresult:
+            for impl in nonwrappers:
+                outcome = impl.call(kwargs)
+                if outcome is not None:
+                    return outcome
+            return None
+        results: list[Any] = []
+        for impl in nonwrappers:
+            outcome = impl.call(kwargs)
+            if outcome is not None:
+                results.append(outcome)
+        return results
+
+    def _run_pipeline(self, kwargs: dict[str, Any], nonwrappers: list[HookImpl]) -> Any:
+        """Thread the first argument through each impl, feeding its result to the next."""
+        param = self.params[0]
+        value = kwargs[param]
+        current = dict(kwargs)
+        for impl in nonwrappers:
+            current[param] = value
+            outcome = impl.call(current)
+            if outcome is not None:  # None means "pass the value through unchanged"
+                value = outcome
+        return value
+
+    def _collect(self, kwargs: dict[str, Any]) -> list[Any]:
+        """Return the non-None results of the non-wrapper impls as a list."""
+        return list(self._collect_iter(kwargs, self._nonwrappers))
+
+    def _collect_iter(self, kwargs: dict[str, Any], nonwrappers: list[HookImpl]) -> Iterator[Any]:
+        """Yield non-None results from the given non-wrapper impls, honouring firstresult."""
+        for impl in nonwrappers:
+            outcome = impl.call(kwargs)
+            if outcome is None:
+                continue
+            yield outcome
+            if self.spec.firstresult:
+                return
+
+    def _teardown(
+        self, started: list[Generator[Any, Any, Any]], *, result: Any = _UNSET, exc: BaseException | None = None
+    ) -> Any:
+        """Resume each wrapper in reverse, letting it replace the result or handle the error."""
+        for generator in reversed(started):
+            try:
+                if exc is not None:
+                    generator.throw(exc)
+                else:
+                    generator.send(result)
+            except StopIteration as stop:
+                # A wrapper that returns after the yield ends here.
+                if exc is not None:
+                    # The wrapper swallowed the exception and supplied a result.
+                    exc = None
+                    result = stop.value
+                elif stop.value is not None:
+                    result = stop.value
+            except BaseException as new_exc:  # noqa: BLE001 - propagate the wrapper's error onward
+                exc = new_exc
+            else:
+                # The generator yielded a second time, violating the one-yield contract.
+                generator.close()
+                raise RuntimeError(f"wrapper for {self.name!r} must yield exactly once")
+        if exc is not None:
+            raise exc
+        return result
+
+    def implementations(self) -> list[HookImpl]:
+        """Return this hook's implementations in call order (wrappers excluded)."""
+        return list(self._nonwrappers)
+
+    def __repr__(self) -> str:
+        """Show the hook name and how many implementations it has."""
+        return f"<HookCaller {self.name!r} impls={len(self._impls)}>"
+
+
+class HookRelay:
+    """Attribute-style access to hook callers, e.g. pm.hook.add_ingredients(...)."""
+
+    def __init__(self) -> None:
+        """Start with no registered callers."""
+        self._callers: dict[str, HookCaller] = {}
+
+    def _add_caller(self, caller: HookCaller) -> None:
+        """Register a caller under its hook name."""
+        self._callers[caller.name] = caller
+
+    def _get_caller(self, name: str) -> HookCaller | None:
+        """Return the caller for a hook name, or None if undefined."""
+        return self._callers.get(name)
+
+    def _all_callers(self) -> list[HookCaller]:
+        """Return every registered caller."""
+        return list(self._callers.values())
+
+    def __getattr__(self, name: str) -> HookCaller:
+        """Resolve pm.hook.<name> to its HookCaller, or raise AttributeError."""
+        try:
+            return self._callers[name]
+        except KeyError:
+            raise AttributeError(f"no hook named {name!r}") from None
+
+
+class PluginManager:
+    """Registers plugins and exposes their hooks via a HookRelay."""
+
+    def __init__(self, project_name: str) -> None:
+        """Bind the manager to a project name shared with the markers."""
+        self.project_name = project_name
+        self.hook = HookRelay()
+        self._spec_attribute = f"{project_name}_spec"
+        self._impl_attribute = f"{project_name}_impl"
+        self._name2plugin: dict[str, object] = {}
+        self._blocked: set[str] = set()
+        self._lock = threading.RLock()
+
+    def add_hookspecs(self, namespace: object) -> None:
+        """Scan a module (or object) for hook specifications and create callers."""
+        with self._lock:
+            for member_name in dir(namespace):
+                member = getattr(namespace, member_name)
+                spec = getattr(member, self._spec_attribute, None)
+                if not isinstance(spec, HookspecOpts):
+                    continue
+                params = tuple(inspect.signature(member).parameters)
+                self._validate_spec(member_name, spec, params)
+                self.hook._add_caller(self._make_caller(member_name, spec, params))
+
+    def _make_caller(self, name: str, spec: HookspecOpts, params: tuple[str, ...]) -> HookCaller:
+        """Build the caller for a spec; overridden by AsyncPluginManager."""
+        return HookCaller(name=name, spec=spec, params=params)
+
+    @staticmethod
+    def _validate_spec(name: str, spec: HookspecOpts, params: tuple[str, ...]) -> None:
+        """Reject contradictory or impossible spec option combinations."""
+        modes = [
+            mode
+            for mode, on in (
+                ("firstresult", spec.firstresult),
+                ("historic", spec.historic),
+                ("pipeline", spec.pipeline),
+            )
+            if on
+        ]
+        if len(modes) > 1:
+            raise ValueError(f"hook {name!r} cannot combine {' and '.join(modes)}")
+        if spec.pipeline and not params:
+            raise ValueError(f"pipeline hook {name!r} must declare at least one argument to thread through")
+
+    def register(self, plugin: object, name: str | None = None) -> str:
+        """Register a plugin object, wiring up every hook implementation it carries."""
+        with self._lock:
+            plugin_name = name or self.get_canonical_name(plugin)
+            if plugin_name in self._blocked:
+                raise ValueError(f"plugin {plugin_name!r} is blocked")
+            if plugin_name in self._name2plugin:
+                raise ValueError(f"plugin name {plugin_name!r} is already registered")
+            if any(existing is plugin for existing in self._name2plugin.values()):
+                raise ValueError(f"plugin object {plugin!r} is already registered")
+
+            impls = self._collect_impls(plugin_name, plugin)
+            self._name2plugin[plugin_name] = plugin
+            for caller, impl in impls:
+                caller.add_impl(impl)
+            return plugin_name
+
+    def unregister(self, name_or_plugin: str | object) -> object | None:
+        """Remove a plugin by name or by object; return the removed plugin or None."""
+        with self._lock:
+            name = name_or_plugin if isinstance(name_or_plugin, str) else self.get_name(name_or_plugin)
+            if name is None:
+                return None
+            plugin = self._name2plugin.pop(name, None)
+            if plugin is None:
+                return None
+            for caller in self.hook._all_callers():
+                caller.remove_plugin(name)
+            return plugin
+
+    def set_blocked(self, name: str) -> None:
+        """Block a plugin name: unregister it if present and refuse future registration."""
+        with self._lock:
+            self._blocked.add(name)
+            self.unregister(name)
+
+    def is_blocked(self, name: str) -> bool:
+        """Return whether a plugin name is blocked."""
+        return name in self._blocked
+
+    def is_registered(self, plugin: object) -> bool:
+        """Return whether a plugin object is currently registered."""
+        return any(existing is plugin for existing in self._name2plugin.values())
+
+    def get_plugin(self, name: str) -> object | None:
+        """Return the plugin registered under a name, or None."""
+        return self._name2plugin.get(name)
+
+    def get_name(self, plugin: object) -> str | None:
+        """Return the registered name of a plugin object, or None."""
+        for registered_name, registered_plugin in self._name2plugin.items():
+            if registered_plugin is plugin:
+                return registered_name
+        return None
+
+    def get_canonical_name(self, plugin: object) -> str:
+        """Derive a default name for a plugin from its __name__ or type."""
+        return getattr(plugin, "__name__", None) or type(plugin).__name__
+
+    def plugin_names(self) -> list[str]:
+        """Return the names of all registered plugins, in registration order."""
+        return list(self._name2plugin)
+
+    def get_hookcallers(self, plugin: object) -> list[HookCaller] | None:
+        """Return the hooks a registered plugin contributes to, or None if unknown."""
+        name = self.get_name(plugin)
+        if name is None:
+            return None
+        return [caller for caller in self.hook._all_callers() if caller.has_plugin(name)]
+
+    def __repr__(self) -> str:
+        """Show the project name and number of registered plugins."""
+        return f"<PluginManager {self.project_name!r} plugins={len(self._name2plugin)}>"
+
+    def load_entrypoints(self, group: str, *, ignore_errors: bool = False) -> int:
+        """Discover and register external plugins advertised under an entry-point group.
+
+        Args:
+            group: The entry-point group name to scan.
+            ignore_errors: When True, skip plugins that fail to load or register
+                instead of raising, so one broken plugin cannot block discovery.
+
+        Returns:
+            The number of plugins successfully registered.
+        """
+        count = 0
+        for entry_point in entry_points(group=group):
+            if entry_point.name in self._name2plugin or entry_point.name in self._blocked:
+                continue
+            try:
+                plugin = entry_point.load()
+                self.register(plugin, name=entry_point.name)
+            except Exception as error:
+                if ignore_errors:
+                    continue
+                raise PluginValidationError(entry_point.name, f"failed to load entry point: {error}") from error
+            count += 1
+        return count
+
+    def _collect_impls(self, plugin_name: str, plugin: object) -> list[tuple[HookCaller, HookImpl]]:
+        """Find and validate every hook implementation a plugin carries."""
+        collected: list[tuple[HookCaller, HookImpl]] = []
+        for member_name in dir(plugin):
+            member = getattr(plugin, member_name)
+            opts = getattr(member, self._impl_attribute, None)
+            if not isinstance(opts, HookimplOpts):
+                continue
+            hook_name = opts.specname or member_name
+            caller = self.hook._get_caller(hook_name)
+            if caller is None:
+                if opts.optionalhook:
+                    continue
+                raise PluginValidationError(plugin_name, f"implements unknown hook {hook_name!r}")
+            if opts.wrapper and caller.spec.historic:
+                raise PluginValidationError(plugin_name, f"historic hook {hook_name!r} cannot have a wrapper")
+            impl = HookImpl.from_function(plugin_name, member, opts)
+            unknown = impl.accepts - caller.argnames
+            if unknown:
+                raise PluginValidationError(
+                    plugin_name,
+                    f"hook {hook_name!r} impl declares unknown argument(s) {sorted(unknown)}; "
+                    f"spec accepts {sorted(caller.argnames)}",
+                )
+            collected.append((caller, impl))
+        return collected

pluginkit-0.1.0/src/pluginkit/markers.py

@@ -0,0 +1,117 @@
+"""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