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, which a host can combine.

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: 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:

pyproject.toml
[tool.plushy]
scan = ["src/acme"]
index = "src/acme/_plushy_index.json"

Generate the index, typically in CI before building:

plushy 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 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:

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

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.