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.

Import Path Resolver

ImportPathResolver resolves a dotted import string ("package.module.attr") into the actual Python object using importlib. It is useful for resolving handlers, classes, or any other symbols from configuration at runtime.

Example

Resolve a callable by path:

resolver = ImportPathResolver[Callable]()
func = resolver("myapp.handlers.main")
func()

Pass a resolved object directly — resolver returns it unchanged:

resolver(resolved_handler)  # returned as-is

Failed lookups may be cached to avoid repeated import overhead.

Example

Plugins as the subclasses:

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

Example

Plugins as the singletons:

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

Example

Plugins as the protocols:

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

Attributes:

Name	Type	Description
__version__	str	Current version

ImportPathResolver

Bases: Generic[T]

Resolve Python objects by import path.

This resolver converts dot-separated import paths into Python objects using importlib, with optional caching and support for already resolved values.

Both successful and (optionally) failed resolutions are cached: - Successful imports cache the resolved object. - Failed attribute lookups may be cached as negative results (controlled by cache_negative) to avoid repeated import attempts for missing symbols.

Typical use case is dynamic resolution of callables, handlers, classes, or other runtime-imported symbols in configuration-driven systems.

Example

resolver = ImportPathResolverCallable func = resolver("package.module.func") func()

Notes

This resolver is idempotent for string inputs.

Negative caching is optional and controlled by cache_negative. When enabled, missing attributes are cached to prevent repeated import attempts for unresolved symbols.

__call__(path)

Resolve item.

Parameters:

Name	Type	Description	Default
path	str | T	Dot-separated import path (e.g. "package.module.attr") or already resolved object. If value is not a string, it is returned as-is.	required

Returns:

Type	Description
T	Resolved object of type T.

Raises:

Type	Description
ValueError	If the provided import path is malformed or empty.
ImportError	If module cannot be imported or attribute is missing.

Loader

Bases: Generic[T]

Generic loader. Used as singleton instantiated from generic.

Parameters:

Name	Type	Description	Default
base	str | None	Plugins package name.	None
bases	Iterable[str] | None	Iterable of plugin package names.	None
strict	bool	Ignore missed plugin packages if set to False, Fail otherwise.	False
exclude	Iterable[str] | None	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. Shortcut for

loader.keys()

Returns:

Type	Description
Iterator[str]	Iterable of plugin names.

get(name, default=None)

get(name: str) -> T | None

get(name: str, default: T) -> T

Get plugin by name.

Return default value if plugin is missed.

Parameters:

Name	Type	Description	Default
name	str	Name of plugin.	required
default	T | None	Default value, if plugin is missed.	None

Returns:

Type	Description
T | None	Plugin item if found, otherwise the explicit default value.
T | None	If default is omitted, returns None when plugin is missing.

items()

Iterate the (name, item) tuples for all plugin items.

Return

Iterable of tuples of (name, item)

Note

items() will force plugin module loading and instantiation.

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 instantiation.

values()

Iterate all found plugin items.

Returns:

Type	Description
Iterable[T]	Iterable of plugin items.

Note

values() will force plugin module loading and instantiation.