Install¶

pip install straight.plugin

That was super easy.

Decide on a Namespace¶

You’ll want to decide on a namespace within your package where you’ll keep your own plugins and where other developers can add more plugins for your package to use.

For example, if you’re writing a log filtering library named logfilter you may choose logfilter.plugins as a package to hold your plugins, so you’ll create the empty package as you would any other python package. However, the only contents of logfilter/plugins/__init__.py will be a little bit of special code telling python this is a namespace package.

# This file will not be needed in Python 3.3
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

Now, any modules you place in this package are plugin modules able to be loaded by straight.plugin.

from straight.plugin import load

plugins = load("logfilter.plugins")

If you’ll be using more plugins than writing them, you should read more about the loaders available and how they work.

Write a Plugin¶

Writing a plugin is even easier than loading them. There are two important plugin types to learn: Module plugins and class Plugins. Every module in your namespace package is a module plugin. Every class they define is a class plugin.

When you load module plugins, you get all of them.

When you load class plugins, you filter them by a common base and only get those class plugins which inherit it.

Module plugins are simple and usually define a few functions with names expected by whoever is loading and using the plugins.

# This is a module plugin

def add_extra(data):
    if 'x' in data and 'y' in data:
        data['z'] = x * y

# This was a fairly useless plugin

Class plugins are only a little longer, but can be a bit more controlled to work with. They depend on a common class the plugins inherit, and this would be defined by the project loading and using the plugins.

# This is a class plugin

class RstContentParser(ContentPlugin):
    """Parses any .rst files in a bundle."""

    extensions = ('.rst',)

    def parse(self, content_file):
        src = content_file.read()
        return self.parse_string(src)

    def parse_string(self, src):
        parts = publish_parts(source=src, writer_name='html')
        return parts['html_body']

You can fit as many class plugins inside a module plugin as you want, and to load them instead of the modules you simply pass a subclasses parameter to load().

from straight.plugin import load

plugins = load("jules.plugins", subclasses=ContentPlugin)

The resulting set of plugins are all the classes found which inherit from ContentPlugin. You can do whatever you want with these, but there are some helpful tools to make it easier to work with Class plugins.

You can easily create instances of all the classes, which gives you a set of Instance plugins.

instances = plugins.produce()

You can even pass initialization parameters to produce() and they’ll be used when creating instances of all the classes. You can see the API docs for the PluginManager to see the other ways you can work with groups of plugins.

Example¶

# logfilter/__init__.py

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

# logfilter/hide_extra.py

from logfilter import Skip

def filter(log_entry):
    level = log_entry.split(':', 1)[0]
    if level != 'EXTRA':
        return log_entry
    else:
        raise Skip()

from straight.plugin import load

class Skip(Exception):
    pass

plugins = load('logfilter')

def filter_entry(log_entry):
    for plugin in plugins:
        try:
            log_entry = plugin.filter(log_entry)
        except Skip:
            pass
    return log_entry

setup(
    # ...
    namespace_packages = ['logfilter.plugins']
)

ClassLoader¶

The recommended loader is the ClassLoader, used to load all the classes from all of the modules in the namespace given. Optionally, you can pass a subclasses parameter to load(), which will filter the loaded classes to those which are a sub-class of any given type.

For example,

import os
from straight.plugin.loaders import ClassLoader
from myapp import FileHandler

plugins = ClassLoader().load('myplugins', subclasses=FileHandler)

for filename in os.listdir('.'):
    for handler_cls in plugins:
        handler = handler_cls(filename)
        if handler.valid():
            handler.process()

However, it is preferred that you use the load() helper provided.

from straight.plugin import load

plugins = load('myplugins', subclasses=FileHandler)

This will automatically use the ClassLoader when given a subclasses argument.

ModuleLoader¶

Before anything else, straight.plugin loads modules. The ModuleLoader is used to do this.

from straight.plugin.loaders import ModuleLoader

plugins = ModuleLoader().load('myplugins')

A note about PEP-420:

Python 3.3 will support a new type of package, the Namespace Package. This allows language-level support for the namespaces that make straight.plugin work and when 3.3 lands, you can create addition plugins to be found in a namespace. For now, continue to use the pkgutil boilerplate, but when 3.3 is released, straight.plugin already supports both forms of namespace package!

ObjectLoader¶

If you need to combine multiple plugins inside each module, you can load all the objects from the modules, rather than the modules themselves.

from straight.plugin.loaders import ObjectLoader

plugins = ObjectLoader().load('myplugins')

Loaders¶

straight.plugin.loaders.unified_load(namespace, subclasses=None, recurse=False)¶

Provides a unified interface to both the module and class loaders, finding modules by default or classes if given a subclasses parameter.

class straight.plugin.loaders.Loader(*args, **kwargs)¶

Base loader class. Only used as a base-class for other loaders.

class straight.plugin.loaders.ModuleLoader(recurse=False)¶

Performs the work of locating and loading straight plugins.

This looks for plugins in every location in the import path.

class straight.plugin.loaders.ObjectLoader(recurse=False)¶

Loads classes or objects out of modules in a namespace, based on a provided criteria.

The load() method returns all objects exported by the module.

class straight.plugin.loaders.ClassLoader(recurse=False)¶

Loads classes out of plugin modules which are subclasses of a single given base class.

PluginManager¶

class straight.plugin.manager.PluginManager(plugins)¶

call(methodname, *args, **kwargs)¶

Call a common method on all the plugins, if it exists.

first(methodname, *args, **kwargs)¶

Call a common method on all the plugins, if it exists. Return the first result (the first non-None)

pipe(methodname, first_arg, *args, **kwargs)¶

Call a common method on all the plugins, if it exists. The return value of each call becomes the replaces the first argument in the given argument list to pass to the next.

Useful to utilize plugins as sets of filters.

produce(*args, **kwargs)¶

Produce a new set of plugins, treating the current set as plugin factories.