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.

Example

Plugins as the subclasses:

loader = Loader[Type[BasePlugin]](base="myproject.plugins")

Example

Plugins as the singletones:

loader = Loader[BasePlugin](base="myproject.plugins")

Example

Plugins as the protocols:

loader = Loader[MyProtocol](base="myproject.plugins")

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__()

Iterate over plugin names.

Iterate over all existing plugin names. Shortland for

loader.keys()

Returns:

Type	Description
Iterator[str]	Iterable of plugin names.

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.