[Docs] Plugin and PluginInfo docs now includes members, OctoPrintPlugin now includes ref to base class
This commit is contained in:
Gina Häußge
parent
d198cccf75
commit
05c11911fb
2 changed files with 122 additions and 1 deletions
|
|
@ -4,10 +4,13 @@ In this module resides the core data structures and logic of the plugin system.
|
|||
way and could be extracted into a separate Python module in the future.
|
||||
|
||||
.. autoclass:: PluginManager
|
||||
:members:
|
||||
|
||||
.. autoclass:: PluginInfo
|
||||
:members:
|
||||
|
||||
.. autoclass:: Plugin
|
||||
:members:
|
||||
|
||||
"""
|
||||
|
||||
|
|
@ -33,29 +36,51 @@ class PluginInfo(object):
|
|||
|
||||
It works on Python module objects and extracts the relevant data from those via accessing the
|
||||
:ref:`control properties <sec-plugins-infrastructure-controlproperties>`.
|
||||
|
||||
Arguments:
|
||||
key (str): Identifier of the plugin
|
||||
location (str): Installation folder of the plugin
|
||||
instance (module): Plugin module instance
|
||||
name (str): Human readable name of the plugin
|
||||
version (str): Version of the plugin
|
||||
description (str): Description of the plugin
|
||||
author (str): Author of the plugin
|
||||
url (str): URL of the website of the plugin
|
||||
license (str): License of the plugin
|
||||
"""
|
||||
|
||||
attr_name = '__plugin_name__'
|
||||
""" Module attribute from which to retrieve the plugin's human readable name. """
|
||||
|
||||
attr_description = '__plugin_description__'
|
||||
""" Module attribute from which to retrieve the plugin's description. """
|
||||
|
||||
attr_version = '__plugin_version__'
|
||||
""" Module attribute from which to retrieve the plugin's version. """
|
||||
|
||||
attr_author = '__plugin_author__'
|
||||
""" Module attribute from which to retrieve the plugin's author. """
|
||||
|
||||
attr_url = '__plugin_url__'
|
||||
""" Module attribute from which to retrieve the plugin's website URL. """
|
||||
|
||||
attr_license = '__plugin_license__'
|
||||
""" Module attribute from which to retrieve the plugin's license. """
|
||||
|
||||
attr_hooks = '__plugin_hooks__'
|
||||
""" Module attribute from which to retrieve the plugin's provided hooks. """
|
||||
|
||||
attr_implementations = '__plugin_implementations__'
|
||||
""" Module attribute from which to retrieve the plugin's provided implementations. """
|
||||
|
||||
attr_helpers = '__plugin_helpers__'
|
||||
""" Module attribute from which to retrieve the plugin's provided helpers. """
|
||||
|
||||
attr_check = '__plugin_check__'
|
||||
""" Module attribute which to call to determine if the plugin can be loaded. """
|
||||
|
||||
attr_init = '__plugin_init__'
|
||||
""" Module attribute which to call when loading the plugin. """
|
||||
|
||||
def __init__(self, key, location, instance, name=None, version=None, description=None, author=None, url=None, license=None):
|
||||
self.key = key
|
||||
|
|
@ -76,11 +101,27 @@ class PluginInfo(object):
|
|||
return "{name} ({version})".format(name=self.name, version=self.version if self.version else "unknown")
|
||||
|
||||
def get_hook(self, hook):
|
||||
"""
|
||||
Arguments:
|
||||
hook (str): Hook to return.
|
||||
|
||||
Returns:
|
||||
callable or None: Handler for the requested ``hook`` or None if no handler is registered.
|
||||
"""
|
||||
|
||||
if not hook in self.hooks:
|
||||
return None
|
||||
return self.hooks[hook]
|
||||
|
||||
def get_implementations(self, *types):
|
||||
"""
|
||||
Arguments:
|
||||
types (list): List of :class:`Plugin` sub classes all returned implementations need to implement.
|
||||
|
||||
Returns:
|
||||
~__builtin__.set: The plugin's implementations matching all of the requested ``types``. Might be empty.
|
||||
"""
|
||||
|
||||
result = set()
|
||||
for implementation in self.implementations:
|
||||
matches_all = True
|
||||
|
|
@ -93,46 +134,125 @@ class PluginInfo(object):
|
|||
|
||||
@property
|
||||
def name(self):
|
||||
"""
|
||||
Human readable name of the plugin. Will be taken from name attribute of the plugin module if available,
|
||||
otherwise from the ``name`` supplied during construction with a fallback to ``key``.
|
||||
|
||||
Returns:
|
||||
str: Name of the plugin, fallback is the plugin's identifier.
|
||||
"""
|
||||
return self._get_instance_attribute(self.__class__.attr_name, defaults=(self._name, self.key))
|
||||
|
||||
@property
|
||||
def description(self):
|
||||
"""
|
||||
Description of the plugin. Will be taken from the description attribute of the plugin module as defined in
|
||||
:attr:`attr_description` if available, otherwise from the ``description`` supplied during construction.
|
||||
May be None.
|
||||
|
||||
Returns:
|
||||
str or None: Description of the plugin.
|
||||
"""
|
||||
return self._get_instance_attribute(self.__class__.attr_description, default=self._description)
|
||||
|
||||
@property
|
||||
def version(self):
|
||||
"""
|
||||
Version of the plugin. Will be taken from the version attribute of the plugin module as defined in
|
||||
:attr:`attr_version` if available, otherwise from the ``version`` supplied during construction. May be None.
|
||||
|
||||
Returns:
|
||||
str or None: Version of the plugin.
|
||||
"""
|
||||
return self._version if self._version is not None else self._get_instance_attribute(self.__class__.attr_version, default=self._version)
|
||||
|
||||
@property
|
||||
def author(self):
|
||||
"""
|
||||
Author of the plugin. Will be taken from the author attribute of the plugin module as defined in
|
||||
:attr:`attr_author` if available, otherwise from the ``author`` supplied during construction. May be None.
|
||||
|
||||
Returns:
|
||||
str or None: Author of the plugin.
|
||||
"""
|
||||
return self._get_instance_attribute(self.__class__.attr_author, default=self._author)
|
||||
|
||||
@property
|
||||
def url(self):
|
||||
"""
|
||||
Website URL for the plugin. Will be taken from the url attribute of the plugin module as defined in
|
||||
:attr:`attr_url` if available, otherwise from the ``url`` supplied during construction. May be None.
|
||||
|
||||
Returns:
|
||||
str or None: Website URL for the plugin.
|
||||
"""
|
||||
return self._get_instance_attribute(self.__class__.attr_url, default=self._url)
|
||||
|
||||
@property
|
||||
def license(self):
|
||||
"""
|
||||
License of the plugin. Will be taken from the license attribute of the plugin module as defined in
|
||||
:attr:`attr_license` if available, otherwise from the ``license`` supplied during construction. May be None.
|
||||
|
||||
Returns:
|
||||
str or None: License of the plugin.
|
||||
"""
|
||||
return self._get_instance_attribute(self.__class__.attr_license, default=self._license)
|
||||
|
||||
@property
|
||||
def hooks(self):
|
||||
"""
|
||||
Hooks provided by the plugin. Will be taken from the hooks attribute of the plugin module as defiend in
|
||||
:attr:`attr_hooks` if available, otherwise an empty dictionary is returned.
|
||||
|
||||
Returns:
|
||||
dict: Hooks provided by the plugin.
|
||||
"""
|
||||
return self._get_instance_attribute(self.__class__.attr_hooks, default={})
|
||||
|
||||
@property
|
||||
def implementations(self):
|
||||
"""
|
||||
Implementations provided by the plugin. Will be taken from the implementations attribute of the plugin module
|
||||
as defined in :attr:`attr_implementations` if available, otherwise an empty list is returned.
|
||||
|
||||
Returns:
|
||||
list: Implementations provided by the plugin.
|
||||
"""
|
||||
return self._get_instance_attribute(self.__class__.attr_implementations, default=[])
|
||||
|
||||
@property
|
||||
def helpers(self):
|
||||
"""
|
||||
Helpers provided by the plugin. Will be taken from the helpers attribute of the plugin module as defined in
|
||||
:attr:`attr_helpers` if available, otherwise an empty list is returned.
|
||||
|
||||
Returns:
|
||||
dict: Helpers provided by the plugin.
|
||||
"""
|
||||
return self._get_instance_attribute(self.__class__.attr_helpers, default={})
|
||||
|
||||
@property
|
||||
def check(self):
|
||||
"""
|
||||
Method for pre-load check of plugin. Will be taken from the check attribute of the plugin module as defined in
|
||||
:attr:`attr_check` if available, otherwise a lambda always returning True is returned.
|
||||
|
||||
Returns:
|
||||
callable: Check method for the plugin module which should return True if the plugin can be loaded, False
|
||||
otherwise.
|
||||
"""
|
||||
return self._get_instance_attribute(self.__class__.attr_check, default=lambda: True)
|
||||
|
||||
@property
|
||||
def init(self):
|
||||
"""
|
||||
Method for initializing the plugin module. Will be taken from the init attribute of the plugin module as defined
|
||||
in :attr:`attr_init` if available, otherwise a lambda always returning True is returned.
|
||||
|
||||
Returns:
|
||||
callable: Init method for the plugin module.
|
||||
"""
|
||||
return self._get_instance_attribute(self.__class__.attr_init, default=lambda: True)
|
||||
|
||||
def _get_instance_attribute(self, attr, default=None, defaults=None):
|
||||
|
|
@ -460,6 +580,6 @@ class Plugin(object):
|
|||
|
||||
def initialize(self):
|
||||
"""
|
||||
Called by the plugin core after performing all injections.
|
||||
Called by the plugin core after performing all injections. Override this to initialize your implementation.
|
||||
"""
|
||||
pass
|
||||
|
|
|
|||
|
|
@ -7,6 +7,7 @@ Please note that the plugin implementation types are documented in the section
|
|||
:ref:`Available plugin mixins <sec-plugins-mixins>`.
|
||||
|
||||
.. autoclass:: OctoPrintPlugin
|
||||
:show-inheritance:
|
||||
|
||||
"""
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue