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: |
|
---|---|
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: |
|
---|---|
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