API Reference

Classes

class pluginlib.Plugin

Mixin class for plugins. All parents and child plugins will inherit from this class automatically.

Class Attributes

The following attributes can be set as class attributes in subclasses

_alias_ = None

str – Friendly name to refer to plugin. Accessed through name property.

_skipload_ = False

bool – When True, plugin is not loaded. Can also be a static or class method that returns a tuple (bool, message)

_version_ = None

str – Plugin version. Should adhere to PEP 440. Accessed through version property.

Class Properties

name = 'Plugin'

str – _alias_ if set or falls back to class name

plugin_group = <pluginlib._util.ClassProperty object>
plugin_type = <pluginlib._util.ClassProperty object>
version = None

str – Returns _version_ if set, otherwise falls back to module __version__ or None

class pluginlib.PluginLoader(group=None, library=None, modules=None, paths=None, entry_point=None, blacklist=None, prefix_package='pluginlib.importer', type_filter=None)
Parameters:

  • group (str) – Group to retrieve plugins from

  • library (str) – Standard library package

  • modules (list) – Iterable of modules to import recursively

  • paths (list) – Iterable of paths to import recursively

  • entry_point (str) – Entry point for additional plugins

  • blacklist (list) – Iterable of BlacklistEntry objects or tuples

  • prefix_package (str) – Alternative prefix for imported packages

  • type_filter (list) – Iterable of parent plugin types to allow

Interface for importing and accessing plugins

Plugins are loaded from sources specified at initialization when load_modules() is called or when the plugins property is first accessed.

group specifies the group whose members will be returned by plugins This corresponds directly with the group attribute for Parent(). When not specified, the default group is used. group should be specified if plugins for different projects could be accessed in an single program, such as in libraries and frameworks.

library indicates the package of a program’s standard library. This should be a package which is always loaded.

modules is an iterable of optional modules to load. If a package is given, it will be loaded recursively.

paths is an iterable of optional paths to find modules to load. The paths are searched recursively and imported under the namespace specified by prefix_package.

entry_point specifies an entry point group to identify additional modules and packages which should be loaded.

blacklist is an iterable containing BlacklistEntry objects or tuples with arguments for new BlacklistEntry objects.

prefix_package must be the name of an existing package under which to import the paths specified in paths. Because the package paths will be traversed recursively, this should be an empty path.

type_filter limits plugins types to only those specified. A specified type is not guaranteed to be available.

get_plugin(plugin_type, name, version=None)
Parameters:

  • plugin_type (str) – Parent type

  • name (str) – Plugin name

  • version (str) – Plugin version

Returns:

Plugin, or None if plugin can’t be found

Return type:

Plugin

Retrieve a specific plugin. blacklist and type_filter still apply.

If version is not specified, the newest available version is returned.

load_modules()

Locate and import modules from locations specified during initialization.

Locations include:

  • Program’s standard library (library)

  • Entry points (entry_point)

  • Specified modules (modules)

  • Specified paths (paths)

If a malformed child plugin class is imported, a PluginWarning will be issued, the class is skipped, and loading operations continue.

If an invalid entry point is specified, an EntryPointWarning is issued and loading operations continue.

property plugins

Newest version of all plugins in the group filtered by blacklist

Returns:

Nested dictionary of plugins accessible through dot-notation.

Return type:

dict

Plugins are returned in a nested dictionary, but can also be accessed through dot-notion. Just as when accessing an undefined dictionary key with index-notation, a KeyError will be raised if the plugin type or plugin does not exist.

Parent types are always included. Child plugins will only be included if a valid, non-blacklisted plugin is available.

property plugins_all

All resulting versions of all plugins in the group filtered by blacklist

Returns:

Nested dictionary of plugins accessible through dot-notation.

Return type:

dict

Similar to plugins, but lowest level is an OrderedDict of all unfiltered plugin versions for the given plugin type and name.

Parent types are always included. Child plugins will only be included if at least one valid, non-blacklisted plugin is available.

The newest plugin can be retrieved by accessing the last item in the dictionary.

plugins = loader.plugins_all
tuple(plugins.parser.json.values())[-1]
class pluginlib.BlacklistEntry(plugin_type=None, name=None, version=None, operator=None)
Parameters:

  • plugin_type (str) – Parent type

  • name (str) – Plugin name

  • version (str) – Plugin version

  • operator (str) – Comparison operator (‘=’, ‘==’, ‘!=’, ‘<’, ‘<=’, ‘>’, ‘>=’)

Container for blacklist entry

If operator is None or not specified, it defaults to ‘==’.

One of plugin_type, name, or version must be specified. If any are unspecified or None, they are treated as a wildcard.

In order to be more compatible with parsed text, the order of operator and version can be swapped. The following are equivalent:

BlacklistEntry('parser', 'json', '1.0', '>=')

BlacklistEntry('parser', 'json', '>=', '1.0')

version is evaluated using packaging.version.parse() and should conform to PEP 440

class pluginlib.abstractattribute

A class to be used to identify abstract attributes

@pluginlib.Parent
class ParentClass:
    abstract_attribute = pluginlib.abstractattribute

Decorators

@pluginlib.Parent(plugin_type=None, group=None)
Parameters:

  • plugin_type (str) – Plugin type

  • group (str) – Group to store plugins

Class Decorator for plugin parents

plugin_type determines under what attribute child plugins will be accessed in PluginLoader.plugins. When not specified, the class name is used.

group specifies the parent and all child plugins are members of the specified plugin group. A PluginLoader instance only accesses the plugins group specified when it was initialized. When not specified, the default group is used. group should be specified if plugins for different projects could be accessed in an single program, such as in libraries and frameworks.

@pluginlib.abstractmethod

Provides @abc.abstractmethod decorator

Used in parent classes to identify methods required in child plugins

@pluginlib.abstractproperty

Provides @abc.abstractproperty decorator

Used in parent classes to identify properties required in child plugins

This decorator has been deprecated since Python 3.3. The preferred implementation is:

@property
@pluginlib.abstractmethod
def abstract_property(self):
    return self.foo
@pluginlib.abstractstaticmethod

A decorator for abstract static methods

Used in parent classes to identify static methods required in child plugins

This decorator is included to support older versions of Python and should be considered deprecated as of Python 3.3. The preferred implementation is:

@staticmethod
@pluginlib.abstractmethod
def abstract_staticmethod():
    return 'foo'
@pluginlib.abstractclassmethod

A decorator for abstract class methods

Used in parent classes to identify class methods required in child plugins

This decorator is included to support older versions of Python and should be considered deprecated as of Python 3.3. The preferred implementation is:

@classmethod
@pluginlib.abstractmethod
def abstract_classmethod(cls):
    return cls.foo

Exceptions

class pluginlib.PluginlibError(*args, **kwargs)

Base exception class for Pluginlib exceptions

All Pluginlib exceptions are derived from this class.

Subclass of Exception

Custom Instance Attributes

friendly = None

str – Optional friendly output

class pluginlib.PluginImportError(*args, **kwargs)

Exception class for Pluginlib import errors

Subclass of PluginlibError

Custom Instance Attributes

friendly = None

str – May contain abbreviated traceback

When an exception is raised while importing a module, an attempt is made to create a “friendly” version of the output with a traceback limited to the plugin itself or, failing that, the loader module.

class pluginlib.PluginWarning

Warning for errors with imported plugins

Subclass of UserWarning

class pluginlib.EntryPointWarning

Warning for errors with importing entry points

Subclass of ImportWarning