API Reference¶
Classes¶
-
class
pluginlib.
Plugin
¶ Mixin class for plugins. All parents and child plugins will inherit from this class automatically.
Class Attributes
Class Properties
-
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 theplugins
property is first accessed.group
specifies the group whose members will be returned byplugins
This corresponds directly with thegroup
attribute forParent()
. 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 byprefix_package
.entry_point
specifies an entry point group to identify additional modules and packages which should be loaded.blacklist
is an iterable containingBlacklistEntry
objects or tuples with arguments for newBlacklistEntry
objects.prefix_package
must be the name of an existing package under which to import the paths specified inpaths
. 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: Returns: Plugin, or
None
if plugin can’t be foundReturn type: Retrieve a specific plugin.
blacklist
andtype_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
)
- Program’s standard library (
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.
-
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.
-
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 anOrderedDict
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: Container for blacklist entry
If
operator
isNone
or not specified, it defaults to ‘==’.One of
plugin_type
,name
, orversion
must be specified. If any are unspecified orNone
, they are treated as a wildcard.In order to be more compatible with parsed text, the order of
operator
andversion
can be swapped. The following are equivalent:BlacklistEntry('parser', 'json', '1.0', '>=')
BlacklistEntry('parser', 'json', '>=', '1.0')
version
is evaluated usingpkg_resources.parse_version()
and should conform to PEP 440
-
class
pluginlib.
abstractattribute
¶ A class to be used to identify abstract attributes
@pluginlib.Parent class ParentClass(object): abstract_attribute = pluginlib.abstractattribute
Decorators¶
-
@
pluginlib.
abstractmethod
¶ Provides
@abc.abstractmethod
decoratorUsed in parent classes to identify methods required in child plugins
-
@
pluginlib.
abstractproperty
¶ Provides
@abc.abstractproperty
decoratorUsed 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
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
-
class
pluginlib.
PluginImportError
(*args, **kwargs)¶ Exception class for Pluginlib import errors
Subclass of
PluginlibError
Custom Instance Attributes
-
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