Extension Manager Classes¶

Bases: stevedore.named.NamedExtensionManager

Load a single plugin with a given name from the namespace.

__call__(func, *args, **kwds)¶

Invokes func() for the single loaded extension.

The signature for func() should be:

def func(ext, *args, **kwds):
    pass

The first argument to func(), ‘ext’, is the Extension instance.

Exceptions raised from within func() are logged and ignored.

Parameters:	func – Callable to invoke for each extension. args – Variable arguments to pass to func() kwds – Keyword arguments to pass to func()
Returns:	List of values returned from func()

driver¶

Returns the driver being used by this manager.

classmethod make_test_instance(extension, namespace='TESTING', propagate_map_exceptions=False, on_load_failure_callback=None, verify_requirements=False)¶

Construct a test DriverManager

Test instances are passed a list of extensions to work from rather than loading them from entry points.

Parameters:

extension (Extension) – Pre-configured Extension instance namespace (str) – The namespace for the manager; used only for identification since the extensions are passed in. propagate_map_exceptions (bool) – Boolean controlling whether exceptions are propagated up through the map call or whether they are logged and then ignored on_load_failure_callback (function) – Callback function that will be called when a entrypoint can not be loaded. The arguments that will be provided when this is called (when an entrypoint fails to load) are (manager, entrypoint, exception) verify_requirements (bool) – Use setuptools to enforce the dependencies of the plugin(s) being loaded. Defaults to False.

Returns:

The manager instance, initialized for testing

Bases: stevedore.named.NamedExtensionManager

Coordinate execution of multiple extensions using a common name.

__getitem__(name)¶

Return the named extensions.

Accessing a HookManager as a dictionary (em['name']) produces a list of the Extension instance(s) with the specified name, in the order they would be invoked by map().

Bases: stevedore.extension.ExtensionManager

Loads only the named extensions.

This is useful for explicitly enabling extensions in a configuration file, for example.

classmethod make_test_instance(extensions, namespace='TESTING', propagate_map_exceptions=False, on_load_failure_callback=None, verify_requirements=False)¶

Construct a test NamedExtensionManager

Test instances are passed a list of extensions to use rather than loading them from entry points.

Parameters:

extensions (list of Extension) – Pre-configured Extension instances namespace (str) – The namespace for the manager; used only for identification since the extensions are passed in. propagate_map_exceptions (bool) – Boolean controlling whether exceptions are propagated up through the map call or whether they are logged and then ignored on_load_failure_callback (function) – Callback function that will be called when a entrypoint can not be loaded. The arguments that will be provided when this is called (when an entrypoint fails to load) are (manager, entrypoint, exception) verify_requirements (bool) – Use setuptools to enforce the dependencies of the plugin(s) being loaded. Defaults to False.

Returns:

The manager instance, initialized for testing

Bases: stevedore.extension.ExtensionManager

Loads only plugins that pass a check function.

The check_func argument should return a boolean, with True indicating that the extension should be loaded and made available and False indicating that the extension should be ignored.

Bases: stevedore.enabled.EnabledExtensionManager

Loads all plugins and filters on execution.

This is useful for long-running processes that need to pass different inputs to different extensions.

map(filter_func, func, *args, **kwds)¶

Iterate over the extensions invoking func() for any where filter_func() returns True.

The signature of filter_func() should be:

def filter_func(ext, *args, **kwds):
    pass

The first argument to filter_func(), ‘ext’, is the Extension instance. filter_func() should return True if the extension should be invoked for the input arguments.

The signature for func() should be:

def func(ext, *args, **kwds):
    pass

The first argument to func(), ‘ext’, is the Extension instance.

Exceptions raised from within func() are propagated up and processing stopped if self.propagate_map_exceptions is True, otherwise they are logged and ignored.

Parameters:	filter_func – Callable to test each extension. func – Callable to invoke for each extension. args – Variable arguments to pass to func() kwds – Keyword arguments to pass to func()
Returns:	List of values returned from func()

map_method(filter_func, method_name, *args, **kwds)¶

Iterate over the extensions invoking each one’s object method called method_name for any where filter_func() returns True.

This is equivalent of using map() with func set to lambda x: x.obj.method_name() while being more convenient.

Exceptions raised from within the called method are propagated up and processing stopped if self.propagate_map_exceptions is True, otherwise they are logged and ignored.

New in version 0.12.

Parameters:	filter_func – Callable to test each extension. method_name – The extension method name to call for each extension. args – Variable arguments to pass to method kwds – Keyword arguments to pass to method
Returns:	List of values returned from methods

Bases: stevedore.dispatch.DispatchExtensionManager

Loads all plugins and filters on execution.

This is useful for long-running processes that need to pass different inputs to different extensions and can predict the name of the extensions before calling them.

The check_func argument should return a boolean, with True indicating that the extension should be loaded and made available and False indicating that the extension should be ignored.

map(names, func, *args, **kwds)¶

Iterate over the extensions invoking func() for any where the name is in the given list of names.

The signature for func() should be:

def func(ext, *args, **kwds):
    pass

The first argument to func(), ‘ext’, is the Extension instance.

Exceptions raised from within func() are propagated up and processing stopped if self.propagate_map_exceptions is True, otherwise they are logged and ignored.

Parameters:	names – List or set of name(s) of extension(s) to invoke. func – Callable to invoke for each extension. args – Variable arguments to pass to func() kwds – Keyword arguments to pass to func()
Returns:	List of values returned from func()

map_method(names, method_name, *args, **kwds)¶

Iterate over the extensions invoking each one’s object method called method_name for any where the name is in the given list of names.

This is equivalent of using map() with func set to lambda x: x.obj.method_name() while being more convenient.

Exceptions raised from within the called method are propagated up and processing stopped if self.propagate_map_exceptions is True, otherwise they are logged and ignored.

New in version 0.12.

Parameters:	names – List or set of name(s) of extension(s) to invoke. method_name – The extension method name to call for each extension. args – Variable arguments to pass to method kwds – Keyword arguments to pass to method
Returns:	List of values returned from methods

Bases: object

Base class for all of the other managers.

__contains__(name)¶

Return true if name is in list of enabled extensions.

__getitem__(name)¶

Return the named extension.

Accessing an ExtensionManager as a dictionary (em['name']) produces the Extension instance with the specified name.

__iter__()¶

Produce iterator for the manager.

Iterating over an ExtensionManager produces the Extension instances in the order they would be invoked.

__weakref__¶

list of weak references to the object (if defined)

entry_points_names()¶

Return the list of entry points names for this namespace.

list_entry_points()¶

Return the list of entry points for this namespace.

The entry points are not actually loaded, their list is just read and returned.

classmethod make_test_instance(extensions, namespace='TESTING', propagate_map_exceptions=False, on_load_failure_callback=None, verify_requirements=False)¶

Construct a test ExtensionManager

Test instances are passed a list of extensions to work from rather than loading them from entry points.

Parameters:

extensions (list of Extension) – Pre-configured Extension instances to use namespace (str) – The namespace for the manager; used only for identification since the extensions are passed in. propagate_map_exceptions (bool) – When calling map, controls whether exceptions are propagated up through the map call or whether they are logged and then ignored on_load_failure_callback (function) – Callback function that will be called when a entrypoint can not be loaded. The arguments that will be provided when this is called (when an entrypoint fails to load) are (manager, entrypoint, exception) verify_requirements (bool) – Use setuptools to enforce the dependencies of the plugin(s) being loaded. Defaults to False.

Returns:

The manager instance, initialized for testing

map(func, *args, **kwds)¶

Iterate over the extensions invoking func() for each.

The signature for func() should be:

def func(ext, *args, **kwds):
    pass

The first argument to func(), ‘ext’, is the Extension instance.

Exceptions raised from within func() are propagated up and processing stopped if self.propagate_map_exceptions is True, otherwise they are logged and ignored.

Parameters:	func – Callable to invoke for each extension. args – Variable arguments to pass to func() kwds – Keyword arguments to pass to func()
Returns:	List of values returned from func()

map_method(method_name, *args, **kwds)¶

Iterate over the extensions invoking a method by name.

This is equivalent of using map() with func set to lambda x: x.obj.method_name() while being more convenient.

Exceptions raised from within the called method are propagated up and processing stopped if self.propagate_map_exceptions is True, otherwise they are logged and ignored.

New in version 0.12.

Parameters:	method_name – The extension method name to call for each extension. args – Variable arguments to pass to method kwds – Keyword arguments to pass to method
Returns:	List of values returned from methods

names()¶

Returns the names of the discovered extensions

Bases: object

Book-keeping object for tracking extensions.

The arguments passed to the constructor are saved as attributes of the instance using the same names, and can be accessed by the callables passed to map() or when iterating over an ExtensionManager directly.

entry_point_target¶

The module and attribute referenced by this extension’s entry_point.

Returns:	A string representation of the target of the entry point in ‘dotted.module:object’ format.

Bases: stevedore.extension.ExtensionManager

ExtensionManager that is explicitly initialized for tests.