Extension Manager Classes

DriverManager

class stevedore.driver.DriverManager(namespace, name, invoke_on_load=False, invoke_args=(), invoke_kwds={})

Bases: stevedore.named.NamedExtensionManager

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

Parameters:
  • namespace (str) – The namespace for the entry points.
  • name (str) – The name of the driver to load.
  • invoke_on_load (bool) – Boolean controlling whether to invoke the object returned by the entry point after the driver is loaded.
  • invoke_args (tuple) – Positional arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • invoke_kwds (dict) – Named arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
__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.

HookManager

class stevedore.hook.HookManager(namespace, name, invoke_on_load=False, invoke_args=(), invoke_kwds={})

Bases: stevedore.named.NamedExtensionManager

Coordinate execution of multiple extensions using a common name.

Parameters:
  • namespace (str) – The namespace for the entry points.
  • name (str) – The name of the hooks to load.
  • invoke_on_load (bool) – Boolean controlling whether to invoke the object returned by the entry point after the driver is loaded.
  • invoke_args (tuple) – Positional arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • invoke_kwds (dict) – Named arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
__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().

NamedExtensionManager

class stevedore.named.NamedExtensionManager(namespace, names, invoke_on_load=False, invoke_args=(), invoke_kwds={}, name_order=False, propagate_map_exceptions=False)

Bases: stevedore.extension.ExtensionManager

Loads only the named extensions.

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

Parameters:
  • namespace (str) – The namespace for the entry points.
  • names (list(str)) – The names of the extensions to load.
  • invoke_on_load (bool) – Boolean controlling whether to invoke the object returned by the entry point after the driver is loaded.
  • invoke_args (tuple) – Positional arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • invoke_kwds (dict) – Named arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • name_order (bool) – If true, sort the loaded extensions to match the order used in names.
  • propagate_map_exceptions – Boolean controlling whether exceptions are propagated up through the map call or whether they are logged and then ignored

EnabledExtensionManager

class stevedore.enabled.EnabledExtensionManager(namespace, check_func, invoke_on_load=False, invoke_args=(), invoke_kwds={}, propagate_map_exceptions=False)

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.

Parameters:
  • namespace (str) – The namespace for the entry points.
  • check_func (callable) – Function to determine which extensions to load.
  • invoke_on_load (bool) – Boolean controlling whether to invoke the object returned by the entry point after the driver is loaded.
  • invoke_args (tuple) – Positional arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • invoke_kwds (dict) – Named arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • propagate_map_exceptions – Boolean controlling whether exceptions are propagated up through the map call or whether they are logged and then ignored

DispatchExtensionManager

class stevedore.dispatch.DispatchExtensionManager(namespace, check_func, invoke_on_load=False, invoke_args=(), invoke_kwds={}, propagate_map_exceptions=False)

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.

Parameters:
  • namespace (str) – The namespace for the entry points.
  • check_func (callable) – Function to determine which extensions to load.
  • invoke_on_load (bool) – Boolean controlling whether to invoke the object returned by the entry point after the driver is loaded.
  • invoke_args (tuple) – Positional arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • invoke_kwds (dict) – Named arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • propagate_map_exceptions – Boolean controlling whether exceptions are propagated up through the map call or whether they are logged and then ignored
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()

NameDispatchExtensionManager

class stevedore.dispatch.NameDispatchExtensionManager(namespace, check_func, invoke_on_load=False, invoke_args=(), invoke_kwds={}, propagate_map_exceptions=False)

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.

Parameters:
  • namespace (str) – The namespace for the entry points.
  • check_func (callable) – Function to determine which extensions to load.
  • invoke_on_load (bool) – Boolean controlling whether to invoke the object returned by the entry point after the driver is loaded.
  • invoke_args (tuple) – Positional arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • invoke_kwds (dict) – Named arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • propagate_map_exceptions – Boolean controlling whether exceptions are propagated up through the map call or whether they are logged and then 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()

ExtensionManager

class stevedore.extension.ExtensionManager(namespace, invoke_on_load=False, invoke_args=(), invoke_kwds={}, propagate_map_exceptions=False)

Bases: object

Base class for all of the other managers.

Parameters:
  • namespace (str) – The namespace for the entry points.
  • invoke_on_load (bool) – Boolean controlling whether to invoke the object returned by the entry point after the driver is loaded.
  • invoke_args (tuple) – Positional arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • invoke_kwds (dict) – Named arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • propagate_map_exceptions – Boolean controlling whether exceptions are propagated up through the map call or whether they are logged and then ignored
__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)

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

names()

Returns the names of the discovered extensions

Extension

class stevedore.extension.Extension(name, entry_point, plugin, obj)

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.

Parameters:
  • name (str) – The entry point name.
  • entry_point (EntryPoint) – The EntryPoint instance returned by pkg_resources.
  • plugin – The value returned by entry_point.load()
  • obj – The object returned by plugin(*args, **kwds) if the manager invoked the extension on load.

TestExtensionManager

class stevedore.tests.manager.TestExtensionManager(extensions, namespace='test', invoke_on_load=False, invoke_args=(), invoke_kwds={})

Bases: stevedore.extension.ExtensionManager

ExtensionManager that is explicitly initialized for tests.

Parameters:
  • extensions (list of Extension) – Pre-configured Extension instances to use instead of loading them from entry points.
  • namespace (str) – The namespace for the entry points.
  • invoke_on_load (bool) – Boolean controlling whether to invoke the object returned by the entry point after the driver is loaded.
  • invoke_args (tuple) – Positional arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.
  • invoke_kwds (dict) – Named arguments to pass when invoking the object returned by the entry point. Only used if invoke_on_load is True.