Skip to content

Hooks

A hook is an extension point the host calls and every active plugin can answer. The host declares it once, in a hookspec; plugins implement it with hookimpls; pluxeo calls them through Pluggy, the hook engine behind pytest.

Declare, implement, call

The host groups its hookspecs in a class:

from pluxeo import Plugin, PluginManager, hookimpl, hookspec


class RendererSpec:
    @hookspec
    def render_block(self, block: dict) -> str | None:
        """Render one content block as HTML, or return None to let another plugin do it."""


class Charts(Plugin):
    namespace = "acme.renderers"
    name = "charts"

    @hookimpl
    def render_block(self, block):
        if block["type"] != "chart":
            return None
        return f"<figure data-chart='{block['spec']}'></figure>"


class Quotes(Plugin):
    namespace = "acme.renderers"
    name = "quotes"

    @hookimpl
    def render_block(self, block):
        if block["type"] != "quote":
            return None
        return f"<blockquote>{block['text']}</blockquote>"


pm = PluginManager("acme.renderers", hookspec=RendererSpec, discover=False)
pm.register(Charts)
pm.register(Quotes)
pm.load_all()

assert pm.hook.render_block(block={"type": "quote", "text": "Hi"}) == ["<blockquote>Hi</blockquote>"]

Three rules:

  • Call with keyword arguments. pm.hook.render_block(block=b), never render_block(b).
  • An implementation may take fewer arguments than its spec, and receives only those it names. It may not take arguments the spec lacks: Pluggy rejects it when the plugin is registered.
  • None means "no answer". By default a call returns the list of every non-None result.

Without hookspec=, the manager has no hooks, and pm.hook.anything raises AttributeError. A manager used only to select backends does not need one.

Who is called

Exactly the plugins that are loaded and enabled. Calling a hook never loads a plugin: call pm.load_all() first, or create the manager with eager=True, which does it at construction. Plugins that are only discovered, that declined to load, that failed, or that the host disabled are not called.

Result modes

The hookspec decides how results combine:

from pluxeo import hookspec


class Spec:
    @hookspec
    def render_block(self, block): ...  # all non-None results, as a list

    @hookspec(firstresult=True)
    def resolve_url(self, ref): ...  # the first non-None result, or None

With firstresult=True, pluxeo stops calling implementations as soon as one returns something other than None.

Order

Implementations are called in reverse load order: the plugin loaded last is called first. Since plugins load in name order, this is reproducible. To move one implementation, mark it:

from pluxeo import hookimpl


class Example:
    @hookimpl(tryfirst=True)
    def render_block(self, block): ...

    @hookimpl(trylast=True)
    def resolve_url(self, ref): ...

Wrappers

A wrapper runs around all the other implementations of a hook, like middleware. It is a generator: the code before yield runs first, yield hands back the combined result of the others, and the wrapper returns the final result.

from pluxeo import Plugin, PluginManager, hookimpl, hookspec


class Spec:
    @hookspec
    def render_block(self, block): ...


cache = {}


class Cache(Plugin):
    namespace = "acme.renderers"
    name = "cache"

    @hookimpl(wrapper=True)
    def render_block(self, block):
        if block["id"] in cache:
            return cache[block["id"]]
        result = yield  # the other implementations run here
        cache[block["id"]] = result
        return result


class Text(Plugin):
    namespace = "acme.renderers"
    name = "text"

    @hookimpl
    def render_block(self, block):
        return block["text"]


pm = PluginManager("acme.renderers", hookspec=Spec, discover=False)
pm.register(Cache)
pm.register(Text)
pm.load_all()

assert pm.hook.render_block(block={"id": 1, "text": "hello"}) == ["hello"]
assert cache == {1: ["hello"]}

Wrappers work with the synchronous call only; see Async Hooks.

Hooks and the lifecycle

A plugin's hooks join dispatch when it finishes loading and leave it when it is disabled, unloaded or fails. Disabling and re-enabling a plugin removes and restores its hooks without running load() again (Enabling and Disabling).

Each manager has its own hook registry, so two namespaces may use the same hook names without interfering.

Other Pluggy options

hookspec and hookimpl are Pluggy's markers, and accept Pluggy's other options (specname, optionalhook, warn_on_impl). pluxeo's own tests cover the ones above. Historic hooks (historic=True) cannot be called through pluxeo yet: see Known Limitations.