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

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.

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.

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

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

a_plugin_info:
a instance of plugin info
get_a_plugin(key, **keywords)[source]

Get a plugin

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

plugin_info:
a instance of plugin info
load_me_now(key, library=None, **keywords)[source]

Import a plugin from plugin registry

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

key:
the key to find the plugin
register_a_plugin(plugin_cls, plugin_info)[source]

for dynamically loaded plugin during runtime

plugin_cls:
the actual plugin class refered to by the second parameter
plugin_info:
a instance of plugin info