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:
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¶
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:
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:
[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.