Module p.c.plugins

Part of pida.core

A flexible plugin framework.

Clear your mind of any previously defined concept of a plugin.

Key components:

    * Registry: stores a set of plugins
    * Plugin: defines a set of behaviours
    * Registry key: unique behavioural identifier

Types of definable behaviour:

    1. Singleton
    2. Feature
    3. Extension Point/Extender

A plugin can register any number of the above behaviour
types.

1. Singleton

When a plugin registers as a singleton for a key, it is saying "I provide the
behaviour", so when the registry is looked up for that key, the object is
returned. At this point, please consider that an ideal registry key may be an
Interface definition (formal or otherwise), so when you ask for the behaviour
by interface you are actually returned an object implementing that interface.

2. Feature

When a plugin defines a Feature, it is again saying "I provide the behaviour",
the difference with singleton is that many plugins can define a feature, and
these plugins are aggregated and can be looked up by registry key. The look up
returns a list of objects that claim to provide the key.

3. Extension point

An extension point is identical to a feature except that the keys for it must
be predefined and are fixed. While a plugin may invent a feature and others
can join it, it is expected that whatever creates the registry formally
defines the extension points and they are then fixed. This can be used to
simulate the behaviour of traditional (Eclipse or Trac) extension points. The
plugin itself supplies the Extender (that which extends), while the registry
contains the Extension point itself (that which is to be extended).

Defining Plugins:

1. Singletons

a. First you will need a registry item:

    reg = Registry()

b. now define a behavioural interface:

    class IAmYellow(Interface):
        def get_shade():
            "get the shade of yellow"

c. now write a class that implements this behaviour:

    class Banana(object):
        def get_shade(self):
            return 'light and greeny'

d. create an instance of the plugin

    plugin = Banana()

e. register it with the registry:

    reg.register_plugin(
            instance=plugin,
            singletons=(IAmYellow,)
        )

f. get the item from the registry at a later time:

    plugin = reg.get_singleton(IAmYellow)
    print plugin.get_shade()

Things to note:

    * Attempting to register another plugin with a singleton of IAmYellow will
      fail.

    * Looking up a non-existent singleton will raise a SingletonError.
Line # Kind Name Docs
96 Function copy_docs Undocumented
102 Class NamedSets The theory of the plugin architecture has its foundations
169 Class StrictNamedSets A strict named sets is a NamedSets that has fixed predefined sets.
200 Class DynamicNamedSets In a dynamic named set the sets are created (empty sets) when you access
238 Class Plugin A possible implementation of a Plugin. A plugin holds an object.
278 Class ExtensionPointError Raised when there's an error of some sort
281 Class ExtensionPoint This class is based on Eclipse's plugin architecture. An extension
358 Class PluginExtensionPoint This is an `ExtensionPoint` prepared to hold `Plugin`s.
370 Class FactoryDict A factory dict is a dictionary that creates objects, once, when they
411 Class SingletonError Raised when you there's a problem related to Singletons.
414 Class PluginEntry Undocumented
426 Class PluginFactoryCreator This is a factory of plugin factories.
459 Class Registry No class docstring; 5/14 methods documented
def copy_docs(cls):
Undocumented
API Documentation for PIDA, generated by pydoctor.