diff --git a/src/octoprint/plugin/core.py b/src/octoprint/plugin/core.py index d418483d..053e0909 100644 --- a/src/octoprint/plugin/core.py +++ b/src/octoprint/plugin/core.py @@ -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 `. + + 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 diff --git a/src/octoprint/plugin/types.py b/src/octoprint/plugin/types.py index 63e6aa56..561e684b 100644 --- a/src/octoprint/plugin/types.py +++ b/src/octoprint/plugin/types.py @@ -7,6 +7,7 @@ Please note that the plugin implementation types are documented in the section :ref:`Available plugin mixins `. .. autoclass:: OctoPrintPlugin + :show-inheritance: """