102 lines
4 KiB
ReStructuredText
102 lines
4 KiB
ReStructuredText
.. _sec-plugins-developing:
|
|
|
|
******************
|
|
Developing Plugins
|
|
******************
|
|
|
|
.. todo::
|
|
|
|
A section on how to develop plugins yourself, including a tutorial creating an exemplary plugin as well as
|
|
a documentation of the plugin API, will be added in the near future.
|
|
|
|
.. note::
|
|
|
|
This section is still a heavy WIP, so take it with a bit of caution ;)
|
|
|
|
.. _sec-plugins-developing-structure:
|
|
|
|
OctoPrint Plugin Structure
|
|
==========================
|
|
|
|
OctoPrint plugins are simple `Python modules or packages <https://docs.python.org/2/tutorial/modules.html>`_ providing
|
|
a couple of properties describing the module:
|
|
|
|
``__plugin_name__``
|
|
Name of your plugin
|
|
``__plugin_version__``
|
|
Version of your plugin
|
|
``__plugin_description__``
|
|
Description of your plugin
|
|
``__plugin_author__``
|
|
Author of your plugin
|
|
``__plugin_url__``
|
|
URL of the webpage of your plugin, e.g. the Github repository
|
|
``__plugin_implementations__``
|
|
Instances of one or more of the various :ref:`plugin mixins <sec-plugins-developing-mixins>`
|
|
``__plugin_hooks__``
|
|
Handlers for one or more of the various :ref:`plugin hooks <sec-plugins-developing-hooks>`
|
|
``__plugin_check__``
|
|
Method called upon discovery of the plugin by the plugin subsystem, should return ``True`` if the
|
|
plugin can be instantiated later on, ``False`` if there are reasons why not, e.g. if dependencies
|
|
are missing.
|
|
``__plugin_init__``
|
|
Method called upon initializing of the plugin by the plugin subsystem, can be used to instantiate
|
|
plugin implementations, connecting them to hooks etc.
|
|
|
|
A very simple example plugin which only hooks into OctoPrint's startup sequence and logs "Oh hello!" would
|
|
be the following snippet:
|
|
|
|
.. code-block:: python
|
|
|
|
# coding=utf-8
|
|
from __future__ import absolute_import
|
|
|
|
import octoprint.plugin
|
|
|
|
__plugin_name__ = "Example Plugin"
|
|
__plugin_version__ = "0.1"
|
|
__plugin_description__ = "Logs \"Oh hello!\" upon OctoPrint's startup"
|
|
|
|
def __plugin_init__():
|
|
global __plugin_implementations__
|
|
__plugin_implementations__ = [ExamplePlugin()]
|
|
|
|
class ExamplePlugin(octoprint.plugin.StartupPlugin):
|
|
def on_startup(self, host, port):
|
|
self._logger.info("Oh hello!")
|
|
|
|
.. _sec-plugins-developing-distribution:
|
|
|
|
Distributing your plugin
|
|
========================
|
|
|
|
You can distribute a plugin with OctoPrint via two ways:
|
|
|
|
- You can have your users copy it to OctoPrint's plugin folder (normally located at ``~/.octoprint/plugins`` under Linux,
|
|
``%APPDATA%\OctoPrint\plugins`` on Windows and ... on Mac). In this case your plugin will be distributed directly
|
|
as a Python module (a single ``.py`` file containing all of your plugin's code directly and named
|
|
like your plugin) or a package (a folder named like your plugin + ``__init.py__`` contained within).
|
|
- You can have your users install it via ``pip`` and register it for the `entry point <https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins>`_ ``octoprint.plugin`` via
|
|
your plugin's ``setup.py``, this way it will be found automatically by OctoPrint upon initialization of the
|
|
plugin subsystem [#f1]_.
|
|
|
|
For an example of how the directory structure and related files would look like in this case, please take a
|
|
look at the `helloworld example from OctoPrint's example plugins <https://github.com/OctoPrint/Plugin-Examples/tree/master/helloworld>`_.
|
|
|
|
This variant is highly recommended for pretty much any plugin besides the most basic ones since it also allows
|
|
requirements management and pretty much any thing else that Python's setuptools provide to the developer.
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#f1] The automatic registration will only work within the same Python installation (this also includes virtual
|
|
environments), so make sure to instruct your users to use the exact same Python installation for installing
|
|
the plugin that they also used for installing & running OctoPrint.
|
|
|
|
.. _sec-plugins-developing-mixins:
|
|
|
|
Available plugin mixins
|
|
=======================
|
|
|
|
.. automodule:: octoprint.plugin.types
|
|
:members:
|
|
:undoc-members:
|