plugin – Component system.

Core module for pluggdapps plugin framework. It uses metaclassing to automagically load and register a blue-print of interfaces and plugins into query-able classes. Developers can create plugin by deriving their class from Plugin. A plugin is expected to implement, by calling implement() function, one or more interfaces inside their plugin class’ scope. The base class Plugin itself is a plugin implementing ISettings interface, thus all configuration related methods are automatically added to the plugin. To provide configurable plugins, authors need to override methods from ISettings interface.

There is also a Singleton base class available for plugin authors to create singleton plugins. A singleton plugin is created only once for the entire life time of the python environment, they are instantiated when the plugin is queried for the first time. Subsequent queries will fetch the singleton instance of the plugin.

As mentioned else-where all plugins are but a dictionary of configuration settings gathered from sources like package-defaults, ini-files and backend-config-store. Platform classes will aggregate these configuration settings during statup-time and make them available during plugins instantiation. Refer pluggdapps.platform to learn more.

Plugins are instantiated by quering with APIs like query_plugin() or query_plugins(). These APIs are automatically avilable on every instantiated plugin and platform objects from Pluggdapps.

Plugin inheritance

It is also possible to create a plugin by deriving from another plugin class. Remember that a plugin class is any class that derives from the Plugin. For example,

class YourPlugin( Plugin ):
    def __init__( self, arg2, arg3 ):
        pass

class MyPlugin( YourPlugin ):
    def __init__( self, arg1, arg2, arg3 ):
        self._super_init( __class__, arg2, arg3 )

YourPlugin is a plugin class (since it derives from Plugin) with accepts two constructor arguments.

Another class MyPlugin wants to extend YourPlugin, hence can simply derive from YourPlugin class. And thus automatically becomes a plugin class. Note that MyPlugin class accepts 3 constructor arguments and to initialize the base class it uses a special method, _super_init() instead of using the builtin super().

Module contents

class pluggdapps.plugin.PluginMeta

Bases: builtins.type

Plugin component manager. Tracks interface specifications, plugin definitions and plugins implementing interfaces. All interfaces and plugins defined across pluggdapps are blueprinted and handles instantiation of plugins via one of the query_*() methods. Also responsibile for making plugin’s configuration settings available as a dictionary of settings.

class pluggdapps.plugin.Interface

Bases: builtins.object

Base class for all interface specifications. Interface specification classes are metaclassed by PluginMeta.

An interface specify a bunch of attributes and methods that provides an agreement between the implementing plugins and the host that is going to consume the plugin’s function.

class pluggdapps.plugin.Plugin

Bases: pluggdapps.plugin.PluginBase

Every plugin must derive from this class.

A plugin is a dictionary of configuration settings, that also implements one or more interface. Note that class:Plugin does not directly derive from built in type dict because dictionary methods from dict type might clash with one or more interface methods implemented by the derving plugin class. Instead, it provides necessary operator methods, to access plugin instances as a dictionary of settings.

Every other plugin class must derive from this class and can override the interface specification methods defined by ISettings. Deriving plugins can assume that plugin’s settings will be consolidated from web-backend, ini-files and default_settings() method, in the order of decreasing priority, and made available as a dictionary of key,value pairs on plugin instance.

Important Note

• All plugin classes must be defined at module top-level.
• For the plugins to be automatically available for querying, make sure to import the module implementing the plugin inside <package>/__init__.py

Similarly to facilitate meth:query_plugins, interfaces implemented by a plugin class (and all of its base classes) are saved under the plugin class attribute _interfs,

<plugin-cls>._interfs = [ <interface-class>, ... ]

A list of methods supplied to access plugin instance like a dictionary,

• __len__, a count of configurable parameters.
• __getitem__, access settings like self['item'].
• __setitem__, update settings like self['item'] = value.
• __delitem__, delete settings like del self['item'].
• __iter__, iterate on settings like [ ... for item in self ].
• __contains__, membership check like item in self

class pluggdapps.plugin.Singleton

Bases: pluggdapps.plugin.Plugin

If a plugin sub-class inherits from this Singleton class, then query_* methods / functions for plugins will always return a singleton instance of the plugin sub-class.

class pluggdapps.plugin.ISettings

Bases: pluggdapps.plugin.Interface

Every plugin is a dictionary of configuration. And its configuration settings are implicitly implemented via Plugin base class, which is the base class for all plugins, and provides default methods for configuration settings which can later be overriden by deriving plugins.

While instantiating plugins via query_plugin(), query_plugins(), query_pluginr() methods, passing a settings key-word argument will override plugin’s settings defined by ini files and backend-store.

All the attributes specified in this interface will automagically be initialised by PluginMeta.

pa = None

Platfrom instance, of Pluggdapps or one of its derivatives.

caname = 'pluggdapps.isettings'

Canonical name of plugin. For example, canonical name for plugin class ConfigSqlite3DB defined under pluggdapps package will be, pluggdapps.ConfigSqlite3DB.

classmethod default_settings()

Class method. Return instance of ConfigDict providing meta data associated with each configuration parameters supported by the plugin, like, default value, value type, help text, whether web configuration is allowed, optional values, etc ...

To be implemented by classes deriving Plugin.

Note that ConfigDict will be used to describe settings that are understood by the plugin and publish configuration manuals for users.

classmethod normalize_settings(settings)

Class method. settings is a dictionary of configuration parameters. This method will be called after aggregating all configuration parameters for a plugin and before updating the plugin instance with its configuration parameters.

Override this method to do any post processing on plugin’s configuration parameter and return the final form of configuration parameters. Processed parameters in settings are updated in-pace and returned.

classmethod web_admin(settings)

Class method. Plugin settings can be configured via web interfaces and stored in a backend like database, files etc ... Use this method for the following,

• To update the in-memory configuration settings with new settings
• To persist new settings in a backend data-store.

Web-admin settings will override settings from ini-files.

Important : This feature is still evolving.

pluggdapps.plugin.implements(*interfaces)

Plugin classes can use this function to declare interfaces that are implemented by them. This function can be called only inside the scope of a class deriving from Plugin.

pluggdapps.plugin.isimplement(plugin, interface)

Check whether plugin implements the interface interface.

pluggdapps.plugin.isplugin(plugin)

Return True if plugin is a plugin-object.

pluggdapps.plugin.interfaces()

Return a complete list of interface classes defined in this environment.

pluggdapps.plugin.interface(interf)

Return the interface class specified by name interf.

pluggdapps.plugin.plugin_info(*args)

Return information dictionary gathered by PluginMeta for a plugin class nm, where nm is the first argument in args. The second argument is optional, and if provided is the default value to be returned if a plugin by name nm is not found.

pluggdapps.plugin.interface_info(*args)

Return information dictionary gathered by PluginMeta for an interface class interf, where interf is the first argument in args. The second argument is optional, and if provided is the default value to be returned if an interface by name interf is not found.

pluggdapps.plugin.pluginnames(interface=None)

Return a list of plugin names implementing interface. If interface is None, then return a list of all plugins

pluggdapps.plugin.pluginclass(interface, name)

Return the plugin class by name implementing interface.

pluggdapps.plugin.webapps()

Return a list of application names (which are actually plugins implementing IWebApp interface.

pluggdapps.plugin.whichmodule(attr)

Try to fetch the module name in which attr is defined.

pluggdapps.plugin.plugin_init()

It is a chicken egg situation in pluggdapp’s component system.

• The plugin class objects are not available until the classes are fully parsed and loaded.
• PluginMeta._implementers need to save plugin class object based on the plugin class’s implements() calls which happens during class loading.

Additionally,

• Every plugin class object’s _interfs attribute is populated with a list of interfaces implemented by the class.

Hence the automagic of plugin system is supplemented by a call to this function, once during startup, after all pluggdapps packages are loaded.