API documentation

lml.loader

Plugin discovery module. It supports plugins installed via pip tools and pyinstaller. scan_plugins() is expected to be called in the main package of yours at an earliest time of convenience.

copyright:
  1. 2017-2020 by Onni Software Ltd.

license:

New BSD License, see LICENSE for more details

lml.loader.scan_plugins_regex(plugin_name_patterns=None, pyinstaller_path=None, black_list=None, white_list=None)[source]

Implicitly discover plugins via pkgutil and pyinstaller path using regular expression

Parameters

plugin_name_patterns: python regular expression

it is used to match all your plugins, either it is a prefix, a suffix, some text in the middle or all.

pyinstaller_path:string

used in pyinstaller only. When your end developer would package your main library and its plugins using pyinstaller, this path helps pyinstaller to find the plugins.

black_list:list

a list of module names that should be skipped.

white_list:list

a list of modules that comes with your main module. If you have a built-in module, the module name should be inserted into the list.

For example, robot_cuisine is a built-in module inside robotchef. It is listed in white_list.

lml.plugin

lml divides the plugins into two category: load-me-later plugins and load-me-now ones. load-me-later plugins refer to the plugins were loaded when needed due its bulky and/or memory hungry dependencies. Those plugins has to use lml and respect lml’s design principle.

load-me-now plugins refer to the plugins are immediately imported. All conventional Python classes are by default immediately imported.

PluginManager should be inherited to form new plugin manager class. If you have more than one plugins in your architecture, it is advisable to have one class per plugin type.

PluginInfoChain helps the plugin module to declare the available plugins in the module.

PluginInfo can be subclassed to describe your plugin. Its method tags() can be overridden to help its matching PluginManager to look itself up.

copyright:
  1. 2017-2020 by Onni Software Ltd.

license:

New BSD License, see LICENSE for more details

class lml.plugin.PluginInfo(plugin_type, abs_class_path=None, tags=None, **keywords)[source]

Information about the plugin.

It is used together with PluginInfoChain to describe the plugins. Meanwhile, it is a class decorator and can be used to register a plugin immediately for use, in other words, the PluginInfo decorated plugin class is not loaded later.

Parameters

name:

plugin name

absolute_import_path:

absolute import path from your plugin name space for your plugin class

tags:

a list of keywords help the plugin manager to retrieve your plugin

keywords:

Another custom properties.

Examples

For load-me-later plugins:

>>> info = PluginInfo("sample",
...      abs_class_path='lml.plugin.PluginInfo', # demonstration only.
...      tags=['load-me-later'],
...      custom_property = 'I am a custom property')
>>> print(info.module_name)
lml
>>> print(info.custom_property)
I am a custom property

For load-me-now plugins:

>>> @PluginInfo("sample", tags=['load-me-now'])
... class TestPlugin:
...     def echo(self, words):
...         print("echoing %s" % words)

Now let’s retrive the second plugin back:

>>> class SamplePluginManager(PluginManager):
...     def __init__(self):
...         PluginManager.__init__(self, "sample")
>>> sample_manager = SamplePluginManager()
>>> test_plugin=sample_manager.get_a_plugin("load-me-now")
>>> test_plugin.echo("hey..")
echoing hey..
class lml.plugin.PluginInfoChain(path)[source]

Pandas style, chained list declaration

It is used in the plugin packages to list all plugin classes

class lml.plugin.PluginManager(plugin_type)[source]

Load plugin info into in-memory dictionary for later import

Parameters

plugin_type:

the plugin type. All plugins of this plugin type will be registered to it.

dynamic_load_library(a_plugin_info)[source]

Dynamically load the plugin info if not loaded

Parameters

a_plugin_info:

a instance of plugin info

get_a_plugin(key, **keywords)[source]

Get a plugin

Parameters

key:

the key to find the plugins

keywords:

additional parameters for help the retrieval of the plugins

load_me_later(plugin_info)[source]

Register a plugin info for later loading

Parameters

plugin_info:

a instance of plugin info

load_me_now(key, library=None, **keywords)[source]

Import a plugin from plugin registry

Parameters

key:

the key to find the plugin

library:

to use a specific plugin module

raise_exception(key)[source]

Raise plugin not found exception

Override this method to raise custom exception

Parameters

key:

the key to find the plugin

register_a_plugin(plugin_cls, plugin_info)[source]

for dynamically loaded plugin during runtime

Parameters

plugin_cls:

the actual plugin class refered to by the second parameter

plugin_info:

a instance of plugin info