Discovery Modes¶
A manager learns which plugins exist from its sources, when it is created. By default the only source is entry points. There are four ways in, and a host can combine them.
| Mode | Imports plugin code when discovering | Use it for |
|---|---|---|
| Entry points (default) | no | installed plugin packages: the normal case |
| Index file | no | a project's own plugins, without writing entry points by hand |
| Package scan | yes, every module | development, drop-a-file plugins |
register() |
n/a | tests, embedding, plugins defined in the host itself |
Entry points¶
from pluxeo import PluginManager
pm = PluginManager("acme.renderers") # same as sources=[EntryPointSource()]
Every installed distribution declaring an entry point in the group acme.renderers becomes a plugin. Discovery reads metadata only; the module the entry point names is imported when the plugin is loaded. See Distributing a Plugin.
An index file¶
A project that does not want to maintain entry points by hand can generate an index of its plugins, ship it with the package, and point the manager at it.
Configure the scan in pyproject.toml:
Generate the index, typically in CI before building:
The command imports the modules under scan to find Plugin subclasses and @plugin functions, and writes a JSON file mapping each namespace to its plugins ({"acme.renderers": {"charts": "acme.charts:Charts"}}). Then:
from pathlib import Path
from pluxeo import IndexFileSource, PluginManager
INDEX = Path(__file__).with_name("_pluxeo_index.json")
pm = PluginManager("acme.renderers", sources=[IndexFileSource(INDEX)])
Reading the index imports nothing; each plugin's module is imported when it loads. The trade-off: the index is only as current as the last pluxeo index run. Run it wherever the package is built. See Command Line for the options.
Scanning a package¶
During development, a host can collect plugins from the modules of a package, so that dropping a file in is enough:
from pluxeo import NamespacePackageSource, PluginManager
pm = PluginManager("acme.renderers", sources=[NamespacePackageSource("acme.renderers_plugins")])
The source imports every direct submodule of the package when the manager is created, and keeps the Plugin subclasses and @plugin functions whose namespace matches. Importing everything at startup is the cost of not declaring anything, which is why this mode is opt-in and not recommended for command-line tools that start often.
Registering directly¶
from pluxeo import Plugin, PluginManager
class Inline(Plugin):
namespace = "acme.renderers"
name = "inline"
pm = PluginManager("acme.renderers", discover=False)
spec = pm.register(Inline)
register() accepts a Plugin subclass, a Plugin instance (used as is: the manager will not create another), a @plugin function, or a PluginSpec. It returns the PluginSpec. Registering a name that is already known replaces it, so a host can override a discovered plugin. discover=False skips the sources altogether.
Combining sources¶
from pluxeo import EntryPointSource, NamespacePackageSource, PluginManager
pm = PluginManager(
"acme.renderers",
sources=[EntryPointSource(), NamespacePackageSource("acme.local_plugins")],
)
Sources are read in order; a later source's plugin replaces an earlier one of the same name. A source that yields a plugin of another namespace raises NamespaceMismatchError.
A source is any object with a find(namespace) method returning PluginSpecs (the DiscoverySource protocol), so a host can read plugins from a database or a configuration file.
Refreshing¶
pluxeo never watches the file system. To pick up newly installed packages or newly added modules, call:
refresh() unloads every loaded plugin (running their cleanup, in reverse load order), forgets every plugin, including those added with register(), and runs the sources again.