Reference¶
Generic Python class loader for robust plugin infrastructure.
Loader delivers plugins from one or many plugin packages.
Loader¶
Loader is the dict-like singleton providing the following services:
- plugin initialization and fetching.
- plugins enumeration.
Plugins are not dependent on the loader and do not need any registration process. The loaders are lazy by nature, meaning the plugin will be imported and initialized just in time when the user code requests the plugin.
Plugins¶
Plugins are named entities dedicated to the given task. Each plugin is defined in its python module. Depending on the loader settings plugins can be:
- Instances: Singleton instances having the class as the ancestor.
- Subclasses: Classes having the common ancestor.
- Protocols: Classes following the set of methods.
Plugin Packages¶
Plugin packages are plain Python packages: the directory containing
python files with plugins and the empty __init__.py
file.
Plugin name must match the module name. For example, module
my_plugin.py
will define the plugin my_plugin
.
Attributes:
Name | Type | Description |
---|---|---|
__version__ |
str
|
Current version |
Loader
¶
Bases: Generic[T]
Generic loader. Used as singleton instantiated from generic.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
base |
Optional[str]
|
Plugins package name. |
None
|
bases |
Optional[Iterable[str]]
|
Iterable of plugin package names. |
None
|
strict |
bool
|
Ignore missed plugin packages if set to False, Fail otherwise. |
False
|
exclude |
Optional[Iterable[str]]
|
Iterable of names to be excluded from plugins lists. |
None
|
Note
base
and bases
parameters are mutually exclusive.
Either base
or bases
must be provided.
__getitem__(name)
¶
Get plugin by name.
Returns plugin item depending on generic type.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name |
str
|
Name of plugin. |
required |
Returns:
Type | Description |
---|---|
T
|
Plugin item depending on generic type. |
Raises:
Type | Description |
---|---|
KeyError
|
if plugin is missed. |
__iter__()
¶
get(name, default=None)
¶
Get plugin by name.
Return default
value if plugin is missed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name |
str
|
Name of plugin. |
required |
default |
Optional[T]
|
Default value, if plugin is missed. |
None
|
Returns:
Type | Description |
---|---|
Optional[T]
|
Plugin item depending on generic type or default value. |
items()
¶
Iterate the (name
, item
) tuples for all plugin items.
Return
Iterable of tuples of (name
, item
)
None
items()
will force plugin module loading and instantination.
keys()
¶
Iterate over plugin name.
Iterable yielding all existing plugin names.
Returns:
Type | Description |
---|---|
Iterable[str]
|
Iterable of strings with all plugin names. |
Note
keys()
do not force plugin module loading and instantination.
values()
¶
Iterate all found plugin items.
Returns:
Type | Description |
---|---|
Iterable[T]
|
Iterable of plugin items. |
Note
values()
will force plugin module loading and instantination.