Skip to content

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.

Discovery sources feed one sorted set of specs. Plugin code is imported only when a plugin is loaded.

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:

pyproject.toml
[tool.pluxeo]
scan = ["src/acme"]
index = "src/acme/_pluxeo_index.json"

Generate the index, typically in CI before building:

pluxeo index

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:

# pm: an existing manager
pm.refresh()
pm.load_all()

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.