acmecse.helpers.PluginManager

module documentation

PluginManager class for managing plugins.

Class	`Dependency`	Dataclass to hold information about a dependency.
Class	`PluginInfo`	Dataclass to hold runtime information, metadata about a plugin, and state management.
Class	`PluginManager`	PluginManager class.
Class	`PluginState`	Plugin states.
Class	`Service`	Base class for service classes.
Exception	`DependencyError`	Raised when a dependency resolution fails.
Exception	`EndpointNotFoundError`	Raised when an endpoint is not found.
Exception	`EndpointTimeoutError`	Raised when an endpoint method times out.
Exception	`PluginConfigurationError`	Raised when a plugin is not configured correctly.
Exception	`PluginError`	Base class for all plugin system errors.
Exception	`PluginNotFoundError`	Raised when a plugin is not found.
Exception	`PluginTimeoutError`	Raised when a plugin method times out.
Function	`configure`	Decorator to mark configuration functions in plugins.
Function	`endpoint`	Decorator to mark a method as an endpoint for a Service. The service name of the endpoint is given as an argument.
Function	`finish`	Decorator to mark finalization functions in plugins.
Function	`init`	Decorator to mark initialization functions in plugins.
Function	`onResolved`	Decorator to mark a method as a callback to be called when the plugin or class becomes resolved.
Function	`onUnresolved`	Decorator to mark a method as a callback to be called when the plugin or class becomes unresolved.
Function	`pause`	Decorator to mark pause functions in plugins.
Function	`plugin`	Decorator to mark plugin classes in plugins.
Function	`provide`	Decorator to mark a function as provided function that can be called by other plugins or external code.
Function	`requires`	Class decorator to mark plugin and other classes with dependencies.
Function	`restart`	Decorator to mark restart functions in plugins.
Function	`start`	Decorator to mark start functions in plugins.
Function	`stop`	Decorator to mark stop functions in plugins.
Function	`unpause`	Decorator to mark unpause functions in plugins.
Function	`validate`	Decorator to mark validation functions in plugins.
Type Alias	`DependencyGraph`	Type alias for a dependency graph. The keys are (plugin) classes or names, and the values are lists of dependencies.
Variable	`dependencies`	Dictionary to hold the dependencies of plugin and other classes.
Variable	`dependentClasses`	Dictionary to hold the classes that depend on a plugin or other class. These are classes that have a @requires decorator attached.
Variable	`providedFunctions`	Dictionary to hold the provided functions. The keys are the function paths, the values are the functions themselves.
Variable	`serviceClasses`	Dictionary to hold the service classes. The keys are the service names, the values are the service classes.
Function	`_executePluginMethod`	Call a function with a timeout. If the function does not complete within the specified time, a PluginTimeoutError is raised.
Function	`_wrap`	Helper function to wrap a function and set a tag attribute to the wrapper function.
Variable	`_shuttingDown`	Flag to indicate whether the CSE is shutting down. This is used to prevent starting new threads during shutdown, which can lead to deadlocks and other issues.
Variable	`_tagEndpointMap`	Internal tag to specify the endpoint map of the plugin.
Variable	`_tagEnpoints`	Internal tag to specify the endpoints of the plugin.
Variable	`_tagInstanceName`	Internal tag to specify the attribute name under which the plugin instance should be accessible in the PluginManager.
Variable	`_tagInstancePriority`	Internal tag to specify the priority of the plugin. Lower values mean higher priority.
Variable	`_tagInstanceTags`	Internal tag to specify the tags of the plugin.
Variable	`_tagNoRestartWhilePaused`	Internal tag to specify that the plugin should not be restarted while paused.
Variable	`_tagTimeout`	Internal tag to specify a timeout for plugin methods.
Variable	`_tagTimeoutMap`	Internal tag to specify the endpoint timeout map of the plugin.
Variable	`_tagType`	Internal tag to identify plugin classes and methods.

def configure(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark configuration functions in plugins.

Parameters
func:`Callable \| None`	The function to decorate.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The decorated function.

def endpoint(name: str, timeout: float | None = None) -> Callable: ¶

Decorator to mark a method as an endpoint for a Service. The service name of the endpoint is given as an argument.

def finish(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark finalization functions in plugins.

Parameters
func:`Callable \| None`	The function to decorate.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The decorated function.

def init(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark initialization functions in plugins.

Parameters
func:`Callable \| None`	The function to decorate.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The decorated function.

def onResolved(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark a method as a callback to be called when the plugin or class becomes resolved.

Parameters
func:`Callable \| None`	The function to decorate.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The decorated function.

def onUnresolved(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark a method as a callback to be called when the plugin or class becomes unresolved.

Parameters
func:`Callable \| None`	The function to decorate.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The decorated function.

def pause(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark pause functions in plugins.

Parameters
func:`Callable \| None`	The function to decorate.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The decorated function.

def plugin(property: str | ClassVar = None, priority: int = 50, tags: list[str] = [], noRestartWhilePaused: bool = False) -> ClassVar: ¶

Decorator to mark plugin classes in plugins.

Parameters
property:`str \| ClassVar`	Optional name for the plugin instance. If a class is given here, it is treated directly as the class to decorate.
priority:`int`	The priority of the plugin. It determines the order in which plugins are started, stopped, etc. Lower values mean higher priority.
tags:`list[str]`	Optional list of tags to attach to the plugin for easier identification and filtering.
noRestartWhilePaused:`bool`	Flag to indicate whether the plugin should not restart while paused.

Returns
`ClassVar`	The class with the plugin class tag set.

def provide(functionPath: str) -> Callable: ¶

Decorator to mark a function as provided function that can be called by other plugins or external code.

It can be injected as a dependency into other plugins or classes using the @requires decorator, by using the function path as the plugin name in the dependency.

def requires(*args: Any, **kwargs: Any) -> Callable: ¶

Class decorator to mark plugin and other classes with dependencies.

Parameters
*args:`Any`	Positional arguments to pass to the plugin decorator.
**kwargs:`Any`	Keyword arguments to pass to the plugin decorator.

Returns
`Callable`	The class.

def restart(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark restart functions in plugins.

Parameters
func:`Callable \| None`	The function to decorate.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The decorated function.

def start(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark start functions in plugins.

def stop(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark stop functions in plugins.

Parameters
func:`Callable \| None`	The function to decorate.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The decorated function.

def unpause(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark unpause functions in plugins.

Parameters
func:`Callable \| None`	The function to decorate.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The decorated function.

def validate(func: Callable | None = None, timeout: float | None = None) -> Callable: ¶

Decorator to mark validation functions in plugins.

Parameters
func:`Callable \| None`	The function to decorate.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The decorated function.

DependencyGraph = ¶

Type alias for a dependency graph. The keys are (plugin) classes or names, and the values are lists of dependencies.

Value

dict[type | str, list[Dependency]]

dependencies: DependencyGraph = ¶

Dictionary to hold the dependencies of plugin and other classes.

dependentClasses: dict[type, tuple[str, bool]] = ¶

Dictionary to hold the classes that depend on a plugin or other class. These are classes that have a @requires decorator attached.

The keys are the classes, the values are tuples containing the names of the plugins they depend: on and a boolean indicating whether the dependency is resolved.

providedFunctions: dict[str, Callable] = ¶

Dictionary to hold the provided functions. The keys are the function paths, the values are the functions themselves.

serviceClasses: dict[str, type] = ¶

Dictionary to hold the service classes. The keys are the service names, the values are the service classes.

def _executePluginMethod(_func_: Callable, *args: Any, _timeout_: float | None = None, **kwargs: Any) -> Any: ¶

Call a function with a timeout. If the function does not complete within the specified time, a PluginTimeoutError is raised.

The timeout can be specified by setting the _tagTimeout attribute on the function.

If no timeout is specified, the function is called directly without the overhead of creating a thread and executor.

Parameters
_func_:`Callable`	The function to call.
*args:`Any`	Positional arguments to pass to the function.
_timeout_:`float \| None`	The timeout for the function call.
**kwargs:`Any`	Keyword arguments to pass to the function.

Returns
`Any`	The result of the function call.

Raises
`PluginTimeoutError`	If the function does not complete within the specified time.

def _wrap(func: Callable, tagValue: str, timeout: float | None = None) -> Callable: ¶

Helper function to wrap a function and set a tag attribute to the wrapper function.

Parameters
func:`Callable`	The function to wrap.
tagValue:`str`	The tag value to set to the wrapper function.
timeout:`float \| None`	Optional timeout value for the function.

Returns
`Callable`	The wrapped function.

_shuttingDown: bool = ¶

Flag to indicate whether the CSE is shutting down. This is used to prevent starting new threads during shutdown, which can lead to deadlocks and other issues.

_tagEndpointMap: str = ¶

Internal tag to specify the endpoint map of the plugin.

_tagEnpoints: str = ¶

Internal tag to specify the endpoints of the plugin.

_tagInstanceName: str = ¶

Internal tag to specify the attribute name under which the plugin instance should be accessible in the PluginManager.

_tagInstancePriority: str = ¶

Internal tag to specify the priority of the plugin. Lower values mean higher priority.

_tagInstanceTags: str = ¶

Internal tag to specify the tags of the plugin.

_tagNoRestartWhilePaused: str = ¶

Internal tag to specify that the plugin should not be restarted while paused.

_tagTimeout: str = ¶

Internal tag to specify a timeout for plugin methods.

_tagTimeoutMap: str = ¶

Internal tag to specify the endpoint timeout map of the plugin.

_tagType: str = ¶

Internal tag to identify plugin classes and methods.