Core API

class openpaperwork_core.Core(auto_load_dependencies=False)

Manage plugins and their callbacks.

call_all(callback_name, *args, **kwargs)

Call all the methods of all the plugins that have callback_name as name. Arguments are passed as is. Returned values are dropped (use callbacks for return values if required)

Method call order is defined by the plugin priorities: Plugins with a higher priority get their methods called first.

When we need a return value from callbacks called with call_all(), we need a way to get the results from all of them. The usual way to do that is to instantiate an empty list or set, and pass it as first argument of the callbacks (argument out). Callbacks can then complete this list or set using list.append() or set.add().

call_one(callback_name, *args, **kwargs)

Look for a plugin method called callback_name and calls it. Raises an error if no such method exists. If many exists, call one at random. Returns the value return by the callback.

Method call order is defined by the plugin priorities: Plugins with a higher priority get their methods called first.

You’re advised to use call_all() or call_success() instead whenever possible. This method is only provided as convenience for when you’re fairly sure there should be only one plugin with such callback (example: mainloop plugins).

call_success(callback_name, *args, **kwargs)

Call methods of all the plugins that have callback_name as name until one of them return a value that is not None. Arguments are passed as is. First value to be different from None is returned. If none of the callbacks returned a value different from None or if no callback has the specified name, this method will return None.

Method call order is defined by the plugin priorities: Plugins with a higher priority get their methods called first.

Callbacks should never raise any exception.

get_active_plugins()

get_by_interface(interface_name)

get_by_name(module_name)

Returns a Plugin instance based on the corresponding module name (assuming it has been loaded).

You shouldn’t use this function, except for: - unit tests - configuration (see cmd.plugins)

get_deps(plugin_name)

get_plugins()

You shouldn’t use this function, except for: - unit tests - configuration (see cmd.plugins)

init()

• Make sure all the dependencies of all the plugins are satisfied.

• Call the method init() of each plugin following the dependency order (those without dependencies are called first).

BEWARE of dependency loops !

load(module_name)

• Load the specified module

• Instantiate the class ‘Plugin()’ of this module

• Register all the methods of this plugin object (except those starting by ‘_’ and those from the class PluginBase) as callbacks

BEWARE of dependency loops !

Arguments:

• module_name: name of the Python module to load

exception openpaperwork_core.DependencyException

Failed to satisfy dependencies.

class openpaperwork_core.PluginBase

Indicates all the methods that must be implemented by any plugin managed by OpenPaperwork core. Also provides default implementations for each method.

PRIORITY = 0

USER_VISIBLE = False

get_deps()

Return the dependencies required by this plugin.

Example:

[
  {
    "interface": "some_interface_name",  # required
    "defaults": ['plugin_a', 'plugin_b'],  # required
    "expected_already_satisfied": False,  # optional, default: True
  },
]

get_interfaces()

Indicates the list of interfaces implemented by this plugin. Interface names are arbitrarily defined. Methods provided by each interface are arbitrarily defined (and no checks are done).

Returns a list of string.

init(core)

Plugins can initialize whatever they want here. When called, all dependencies have been loaded and initialized, so using them is safe. Does nothing by default.