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), neverrender_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.
Nonemeans "no answer". By default a call returns the list of every non-Noneresult.
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.