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, which a host can combine.
| 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: the package's modules | development, drop-a-file plugins |
register() |
n/a | tests, embedding, plugins defined in the host itself |
What it costs¶
Measured with 200 plugin packages installed, in a fresh process:
| Find the 200 plugins | Load one | |
|---|---|---|
| Entry points | about 20 ms | a few ms |
| Index file | under 1 ms | a few ms |
| Package scan | about 20 ms, importing the modules | already imported |
import plushy itself takes about 14 ms. Beyond that, a host pays mostly for the plugins it loads and for what their modules import.
Entry points¶
from plushy 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 plushy import IndexFileSource, PluginManager
INDEX = Path(__file__).with_name("_plushy_index.json")
pm = PluginManager("acme.renderers", sources=[IndexFileSource(INDEX)])
Reading the index imports nothing; each plugin's module is imported when it loads. The index is only as current as the last plushy index run, so 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 plushy 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 plushy 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 plushy 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¶
Plushy never watches the file system. To pick up newly installed packages or newly added modules, call:
refresh() unloads the loaded plugins (running their cleanup, in reverse load order), forgets all plugins, including those added with register(), and runs the sources again.