Control Properties¶

As already mentioned earlier, plugins are Python packages which provide certain pieces of metadata to tell OctoPrint’s plugin subsystem about themselves. These are simple package attributes defined in the top most package file, e.g.:

import octoprint.plugin

# ...

__plugin_name__ = "My Plugin"
__plugin_pythoncompat__ = ">=2.7,<4"
def __plugin_load__():
    # whatever you need to do to load your plugin, if anything at all
    pass

The following properties are recognized:

__plugin_name__

Name of your plugin, optional, overrides the name specified in setup.py if provided. If neither this property nor a name from setup.py is available to the plugin subsystem, the plugin’s identifier (= package name) will be used instead.

__plugin_version__

Version of your plugin, optional, overrides the version specified in setup.py if provided.

__plugin_description__

Description of your plugin, optional, overrides the description specified in setup.py if provided.

__plugin_author__

Author of your plugin, optional, overrides the author specified in setup.py if provided.

__plugin_url__

URL of the webpage of your plugin, e.g. the Github repository, optional, overrides the URL specified in setup.py if provided.

__plugin_license__

License of your plugin, optional, overrides the license specified in setup.py if provided.

__plugin_privacypolicy__

URL of the privacy policy of your plugin, optional.

__plugin_pythoncompat__

Python compatibility string of your plugin, optional, defaults to >=2.7,<3 if not set and thus Python 2 but no Python 3 compatibility. This is used as a precaution against issues with some of the Python 2 only plugins that are still out there, as OctoPrint will not even attempt to load plugins whose Python compatibility information doesn’t match its current environment.

If your plugin is compatible to supported Python 3 versions only, you should set this to >=3.9,<4.

__plugin_pythoncompat__ = ">=3.9,<4"

__plugin_implementation__

Instance of an implementation of one or more plugin mixins. E.g.

__plugin_implementation__ = MyPlugin()

__plugin_hooks__

Handlers for one or more of the various plugin hooks. E.g.

def handle_gcode_sent(comm_instance, phase, cmd, cmd_type, gcode, *args, **kwargs):
    if gcode in ("M106", "M107"):
        import logging
        logging.getLogger(__name__).info("We just sent a fan command to the printer!")

__plugin_hooks__ = {
    "octoprint.comm.protocol.gcode.sent": handle_gcode_sent
}

__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. An example:

def __plugin_check__():
    # Make sure we only run our plugin if some_dependency is available
    try:
        import some_dependency
    except ImportError:
        return False

    return True

__plugin_load__

Method called upon loading of the plugin by the plugin subsystem, can be used to instantiate plugin implementations, connecting them to hooks etc. An example:

def __plugin_load__():
    global __plugin_implementation__
    __plugin_implementation__ = MyPlugin()

    global __plugin_hooks__
    __plugin_hooks__ = {
        "octoprint.plugin.softwareupdate.check_config": __plugin_implementation__.get_update_information
    }

__plugin_unload__

Method called upon unloading of the plugin by the plugin subsystem, can be used to do any final clean ups.

__plugin_enable__

Method called upon enabling of the plugin by the plugin subsystem. Also see on_plugin_enabled().

__plugin_disable__

Method called upon disabling of the plugin by the plugin subsystem. Also see on_plugin_disabled().

__plugin_settings_overlay__

An optional dict providing an overlay over the application’s default settings. Plugins can use that to modify the default settings of OctoPrint and its plugins that apply when there’s no different configuration present in config.yaml. Note that config.yaml has the final say - it is not possible to override what is in there through an overlay. Plugin authors should use this sparingly - it’s supposed to be utilized when creating specific customization of the core application that necessitate changes in things like e.g. standard naming, UI ordering or API endpoints. Example:

__plugin_settings_overlay__ = dict(api=dict(enabled=False),
                                   server=dict(host="127.0.0.1",
                                               port=5001))