Skip to content

Quick Start

This page builds a small host application with one extension point, and a plugin for it in a separate package. It takes about five minutes.

1. The host declares a hook

The host decides what plugins can contribute. Here, plugins can add a greeting:

greeter/hooks.py
from pluxeo import hookspec


class GreeterSpec:
    @hookspec
    def greeting(self, name: str) -> str | None:
        """Return a greeting for `name`, or None to stay silent."""

2. The host loads plugins and calls the hook

greeter/app.py
from pluxeo import PluginManager

from greeter.hooks import GreeterSpec


def main() -> None:
    pm = PluginManager("greeter.plugins", hookspec=GreeterSpec)
    pm.load_all()
    for line in pm.hook.greeting(name="Ada"):
        print(line)

PluginManager("greeter.plugins", ...) looks for installed packages that declare an entry point in the greeter.plugins group. load_all() loads each one. pm.hook.greeting(...) calls every loaded plugin and returns the list of their non-None answers.

3. A plugin implements it

In a separate package, greeter-french:

greeter_french/plugin.py
from pluxeo import Plugin, hookimpl


class French(Plugin):
    namespace = "greeter.plugins"
    name = "french"

    @hookimpl
    def greeting(self, name):
        return f"Bonjour, {name} !"

4. The plugin declares itself

In the plugin package's pyproject.toml, one entry point, in the group named after the namespace:

greeter-french/pyproject.toml
[project.entry-points."greeter.plugins"]
french = "greeter_french.plugin:French"

Install both packages in the same environment, run the host, and it prints Bonjour, Ada !. The host did not change; installing the plugin was enough.

5. Try it without packaging

While developing, or in tests, skip discovery and register the plugin directly:

from pluxeo import Plugin, PluginManager, hookimpl, hookspec


class GreeterSpec:
    @hookspec
    def greeting(self, name: str) -> str | None: ...


class French(Plugin):
    namespace = "greeter.plugins"
    name = "french"

    @hookimpl
    def greeting(self, name):
        return f"Bonjour, {name} !"


pm = PluginManager("greeter.plugins", hookspec=GreeterSpec, discover=False)
pm.register(French)
pm.load_all()
assert pm.hook.greeting(name="Ada") == ["Bonjour, Ada !"]

What next

  • Concepts explains the lifecycle you just used.
  • Hooks covers first-result hooks, wrappers and ordering.
  • Selecting a Backend shows the other style: asking for one plugin by name.