Plugins 0.5a1dev

Querying and Notifying

In addition to simply providing iteration over registered implementations, hooks have two convenience methods for querying or notifying plugins. Specifically, you can use Hook.query() and Hook.notify() to invoke hooks whose implementations are functions or other callable objects. For example:

>>> def echo(*args, **kw):
...     print "called with", args, kw

>>> def compute(*args, **kw):
...     return 42, args, kw

>>> demo = plugins.Hook('plugins.demo.hook2')
>>> demo.register(echo)
>>> demo.register(compute)

>>> demo.notify()
called with () {}

>>> demo.notify(57, x=3)
called with (57,) {'x': 3}

>>> for result in demo.query(): print result
called with () {}
None
(42, (), {})

>>> for result in demo.query(99): print result
called with (99,) {}
None
(42, (99,), {})

As you can see, the .notify() method does not return a value, but simply calls each implementation of the hook with the given arguments. .query(), however, yields the result of each call.

Named Implementations

By default, the name of a registered implementation is not significant; most of the time, you just want all registered implementations for a specified group name, regardless of the individual implementations’ names. However, it is sometimes useful to subdivide a hook’s implementations using another level of names.

For example, suppose you are writing a blogging application that processes various input formats, and you’d like plugins to be able to register hook implementations for specific file extensions. You can do this by registering implementations with an implementation name:

>>> def rst_formatter(filename):
...     print "formatting",filename,"using reST"

>>> def txt_formatter(filename):
...     print "formatting",filename,"as plain text"

>>> formatters = plugins.Hook('blogtool.formatters')
>>> formatters.register(rst_formatter, '.rst')
>>> formatters.register(txt_formatter, '.txt')

>>> list(formatters)
[<function rst_formatter...>, <function txt_formatter...>]

And then retriveing them using a Hook that has both a group name and an implementation name:

>>> plugins.Hook('blogtool.formatters', '.rst').notify("foo.rst")
formatting foo.rst using reST

>>> plugins.Hook('blogtool.formatters', '.txt').notify("bar.txt")
formatting bar.txt as plain text

The second argument to the Hook() constructor (and the Hook.register() method) is an implementation name. If supplied, it must be a non-empty ASCII string that does not start with a [, contain any control characters or = signs. (It must also not begin or end with whitespace.)

Note, by the way, that these implementation names are not necessarily unique. For example, multiple plugins could register a .rst formatter, and it is up to the code using the Hook to decide how to handle that! Also notice that the blogtool.formatters hook above lists all registered formatters, no matter what implementation name they are registered under. It’s also possible for the same implementation to be registered under more than one name, in which case it will be listed more than once in the overall hook, e.g.:

>>> formatters.register(rst_formatter, '.txt')
>>> list(formatters)
[<function rst_formatter...>, <function txt_formatter...>,
 <function rst_formatter...>]

>>> list(plugins.Hook('blogtool.formatters', '.txt'))
[<function txt_formatter...>, <function rst_formatter...>]

Finally, note that hooks tied to a specific implementation name can also be used for registration, e.g.:

>>> foo = plugins.Hook('blogtool.formatters', '.foo')
>>> foo
Hook('blogtool.formatters', '.foo')

>>> foo.register(42)
>>> list(foo)
[42]

>>> list(formatters)
[..., 42]

But you must either omit the implementation name from the .register() call (as shown above), or else it must match the implementation name the hook was created with:

>>> foo.register(21, '.foo')    # ok - same name

>>> foo.register(99, 'blue!')   # not ok!
Traceback (most recent call last):
 ...
ValueError: Can only register .foo implementations

Automatic Discovery Using Entry Points and Eggs

So far, we have only seen manually-registered hook implementations. This is fine for demonstration, but in a real application with plugins, it would be necessary to first find and load the plugins’ code in order to do such registrations.

To address this issue, setuptools provides a feature called “entry points”, which can be used to include registration data in plugins’ eggs. This allows hook implementations to be imported on demand.

To register a hook implementation for auto-discovery, the plugin’s setup.py must use setuptools, and define entry points like this:

setup(
    ...
    entry_points = """
    [blogtool.formatters]
    .rst = some.module:some_object
    .txt = other.module:other_object

    [some.other.hook]
    any old name here = whatever:SomeClass
    something without an equals sign = foo:bar
    """
)

When the plugin is active on sys.path (i.e., it’s importable), iterating over an appropriate Hook object will automatically import the specified object(s) and yield them.

In the example above, some_object will be imported from some.module and yielded whenever iterating over Hook('blogtool.formatters') or Hook('blogtool.formatters', '.rst'). (Note that you must always name the implementations listed in setup.py, even if the application does not look up implementations by name!)

Through this automatic, on-demand import process, it is not necessary to find and import the plugins in order to register hook implementations. Instead, merely installing the plugin is sufficient to make its hook implementations available. This also speeds up application startup, because implementations are not imported until they are used. (And performance can often be further improved by putting less frequently-used hook implementations into separate modules from those that are used more often.)

Of course, most applications will want to have one or more special directories for installing and using egg plugins; you can use the PluginManager service to locate and selectively activate the plugins found in such directories.

See also:

• The setuptools documentation on entry points

• The pkg_resources entry point API

Replacing the PluginManager

TODO

• example of subclassing PluginManager and activating it using a with: block

Threading Concerns

By default, a separate PluginManager is created for each thread, and they will share a single working set but use different environments. This is probably NOT what you want in a threaded environment!

This issue will be addressed in future releases, but for now you should avoid using PluginManager configuration methods from multiple threads.

It is, however, safe to use Hook objects from multiple threads, as this is a read-only operation. In principle, accessing a Hook from one thread while configuring the PluginManager in another thread could cause a hook to be skipped or doubled, although this is very unlikely. It would be best to do all of your PluginManager configuration before starting threads that use Hook objects, at least with the current version of Plugins.