Skip to content

octoprint.plugin#

This module represents OctoPrint's plugin subsystem. This includes management and helper methods as well as the registered plugin types.

.. autofunction:: plugin_manager

.. autofunction:: plugin_settings

.. autofunction:: call_plugin

.. autoclass:: PluginSettings :members:

PluginSettings #

The :class:PluginSettings class is the interface for plugins to their own or globally defined settings.

It provides some convenience methods for directly accessing plugin settings via the regular :class:octoprint.settings.Settings interfaces as well as means to access plugin specific folder locations.

All getter and setter methods will ensure that plugin settings are stored in their correct location within the settings structure by modifying the supplied paths accordingly.

Parameters:

Name Type Description Default
settings Settings

The :class:~octoprint.settings.Settings instance on which to operate.

required
plugin_key str

The plugin identifier of the plugin for which to create this instance.

required
defaults dict

The plugin's defaults settings, will be used to determine valid paths within the plugin's settings structure

None

.. method:: get(path, merged=False, asdict=False)

Retrieves a raw value from the settings for path, optionally merging the raw value with the default settings if merged is set to True.

:param path: The path for which to retrieve the value. :type path: list, tuple :param boolean merged: Whether to merge the returned result with the default settings (True) or not (False, default). :returns: The retrieved settings value. :rtype: object

.. method:: get_int(path, min=None, max=None)

Like :func:get but tries to convert the retrieved value to int. If min is provided and the retrieved value is less than it, it will be returned instead of the value. Likewise for max - it will be returned if the value is greater than it.

.. method:: get_float(path, min=None, max=None)

Like :func:get but tries to convert the retrieved value to float. If min is provided and the retrieved value is less than it, it will be returned instead of the value. Likewise for max - it will be returned if the value is greater than it.

.. method:: get_boolean(path)

Like :func:get but tries to convert the retrieved value to boolean.

.. method:: set(path, value, force=False)

Sets the raw value on the settings for path.

:param path: The path for which to retrieve the value. :type path: list, tuple :param object value: The value to set. :param boolean force: If set to True, the modified configuration will even be written back to disk if the value didn't change.

.. method:: set_int(path, value, force=False, min=None, max=None)

Like :func:set but ensures the value is an int through attempted conversion before setting it. If min and/or max are provided, it will also be ensured that the value is greater than or equal to min and less than or equal to max. If that is not the case, the limit value (min if less than that, max if greater than that) will be set instead.

.. method:: set_float(path, value, force=False, min=None, max=None)

Like :func:set but ensures the value is an float through attempted conversion before setting it. If min and/or max are provided, it will also be ensured that the value is greater than or equal to min and less than or equal to max. If that is not the case, the limit value (min if less than that, max if greater than that) will be set instead.

.. method:: set_boolean(path, value, force=False)

Like :func:set but ensures the value is an boolean through attempted conversion before setting it.

.. method:: save(force=False, trigger_event=False)

Saves the settings to config.yaml if there are active changes. If force is set to True the settings will be saved even if there are no changes. Settings trigger_event to True will cause a SettingsUpdated :ref:event <sec-events-available_events-settings> to get triggered.

:param force: Force saving to config.yaml even if there are no changes. :type force: boolean :param trigger_event: Trigger the SettingsUpdated :ref:event <sec-events-available_events-settings> on save. :type trigger_event: boolean

.. method:: add_overlay(overlay, at_end=False, key=None)

Adds a new config overlay for the plugin's settings. Will return the overlay's key in the map.

:param overlay: Overlay dict to add :type overlay: dict :param at_end: Whether to add overlay at end or start (default) of config hierarchy :type at_end: boolean :param key: Key to use to identify overlay. If not set one will be built based on the overlay's hash :type key: str :rtype: str

.. method:: remove_overlay(key)

Removes an overlay from the settings based on its key. Return True if the overlay could be found and was removed, False otherwise.

:param key: The key of the overlay to remove :type key: str :rtype: boolean

get_plugin_logfile_path(postfix=None) #

Retrieves the path to a logfile specifically for the plugin. If postfix is not supplied, the logfile will be named plugin_<plugin identifier>.log and located within the configured logs folder. If a postfix is supplied, the name will be plugin_<plugin identifier>_<postfix>.log at the same location.

Plugins may use this for specific logging tasks. For example, a :class:~octoprint.plugin.SlicingPlugin might want to create a log file for logging the output of the slicing engine itself if some debug flag is set.

Parameters:

Name Type Description Default
postfix str

Postfix of the logfile for which to create the path. If set, the file name of the log file will be plugin_<plugin identifier>_<postfix>.log, if not it will be plugin_<plugin identifier>.log.

None

Returns:

Name Type Description
str

Absolute path to the log file, directly usable by the plugin.

global_get(path, **kwargs) #

Getter for retrieving settings not managed by the plugin itself from the core settings structure. Use this to access global settings outside of your plugin.

Directly forwards to :func:octoprint.settings.Settings.get.

global_get_basefolder(folder_type, **kwargs) #

Retrieves a globally defined basefolder of the given folder_type. Directly forwards to :func:octoprint.settings.Settings.getBaseFolder.

global_get_boolean(path, **kwargs) #

Like :func:global_get but directly orwards to :func:octoprint.settings.Settings.getBoolean.

global_get_float(path, **kwargs) #

Like :func:global_get but directly forwards to :func:octoprint.settings.Settings.getFloat.

global_get_int(path, **kwargs) #

Like :func:global_get but directly forwards to :func:octoprint.settings.Settings.getInt.

global_set(path, value, **kwargs) #

Setter for modifying settings not managed by the plugin itself on the core settings structure. Use this to modify global settings outside of your plugin.

Directly forwards to :func:octoprint.settings.Settings.set.

global_set_boolean(path, value, **kwargs) #

Like :func:global_set but directly forwards to :func:octoprint.settings.Settings.setBoolean.

global_set_float(path, value, **kwargs) #

Like :func:global_set but directly forwards to :func:octoprint.settings.Settings.setFloat.

global_set_int(path, value, **kwargs) #

Like :func:global_set but directly forwards to :func:octoprint.settings.Settings.setInt.

call_plugin(types, method, args=None, kwargs=None, callback=None, error_callback=None, sorting_context=None, initialized=True) #

Helper method to invoke the indicated method on all registered plugin implementations implementing the indicated types. Allows providing method arguments and registering callbacks to call in case of success and/or failure of each call which can be used to return individual results to the calling code.

Example:

.. sourcecode:: python

def my_success_callback(name, plugin, result): print("{name} was called successfully and returned {result!r}".format(**locals()))

def my_error_callback(name, plugin, exc): print("{name} raised an exception: {exc!s}".format(**locals()))

octoprint.plugin.call_plugin( [octoprint.plugin.StartupPlugin], "on_startup", args=(my_host, my_port), callback=my_success_callback, error_callback=my_error_callback )

Parameters:

Name Type Description Default
types list

A list of plugin implementation types to match against.

required
method string

Name of the method to call on all matching implementations.

required
args tuple

A tuple containing the arguments to supply to the called method. Optional.

None
kwargs dict

A dictionary containing the keyword arguments to supply to the called method. Optional.

None
callback function

A callback to invoke after an implementation has been called successfully. Will be called with the three arguments name, plugin and result. name will be the plugin identifier, plugin the plugin implementation instance itself and result the result returned from the method invocation.

None
error_callback function

A callback to invoke after the call of an implementation resulted in an exception. Will be called with the three arguments name, plugin and exc. name will be the plugin identifier, plugin the plugin implementation instance itself and exc the caught exception.

None
initialized boolean

Ignored.

True

plugin_manager(init=False, plugin_folders=None, plugin_bases=None, plugin_entry_points=None, plugin_disabled_list=None, plugin_sorting_order=None, plugin_blacklist=None, plugin_restart_needing_hooks=None, plugin_obsolete_hooks=None, plugin_considered_bundled=None, plugin_validators=None, compatibility_ignored_list=None) #

Factory method for initially constructing and consecutively retrieving the :class:~octoprint.plugin.core.PluginManager singleton.

Parameters:

Name Type Description Default
init boolean

A flag indicating whether this is the initial call to construct the singleton (True) or not (False, default). If this is set to True and the plugin manager has already been initialized, a :class:ValueError will be raised. The same will happen if the plugin manager has not yet been initialized and this is set to False.

False
plugin_folders list

A list of folders (as strings containing the absolute path to them) in which to look for potential plugin modules. If not provided this defaults to the configured plugins base folder and src/plugins within OctoPrint's code base.

None
plugin_bases list

A list of recognized plugin base classes for which to look for provided implementations. If not provided this defaults to :class:~octoprint.plugin.OctoPrintPlugin.

None
plugin_entry_points list

A list of entry points pointing to modules which to load as plugins. If not provided this defaults to the entry point octoprint.plugin.

None
plugin_disabled_list list

A list of plugin identifiers that are currently disabled. If not provided this defaults to all plugins for which enabled is set to False in the settings.

None
plugin_sorting_order dict

A dict containing a custom sorting orders for plugins. The keys are plugin identifiers, mapped to dictionaries containing the sorting contexts as key and the custom sorting value as value.

None
plugin_blacklist list

A list of plugin identifiers/identifier-requirement tuples that are currently blacklisted.

None
plugin_restart_needing_hooks list

A list of hook namespaces which cause a plugin to need a restart in order be enabled/disabled. Does not have to contain full hook identifiers, will be matched with startswith similar to logging handlers

None
plugin_obsolete_hooks list

A list of hooks that have been declared obsolete. Plugins implementing them will not be enabled since they might depend on functionality that is no longer available.

None
plugin_considered_bundled list

A list of plugin identifiers that are considered bundled plugins even if installed separately.

None
plugin_validators list

A list of additional plugin validators through which to process each plugin.

None
compatibility_ignored_list list

A list of plugin keys for which it will be ignored if they are flagged as incompatible. This is for development purposes only and should not be used in production.

None

Returns:

Name Type Description
PluginManager

A fully initialized :class:~octoprint.plugin.core.PluginManager instance to be used for plugin management tasks.

Raises:

Type Description
ValueError

init was True although the plugin manager was already initialized, or it was False although the plugin manager was not yet initialized.

plugin_settings(plugin_key, defaults=None, get_preprocessors=None, set_preprocessors=None, settings=None) #

Factory method for creating a :class:PluginSettings instance.

Parameters:

Name Type Description Default
plugin_key string

The plugin identifier for which to create the settings instance.

required
defaults dict

The default settings for the plugin, if different from get_settings_defaults.

None
get_preprocessors dict

The getter preprocessors for the plugin.

None
set_preprocessors dict

The setter preprocessors for the plugin.

None
settings octoprint.settings.Settings

The settings instance to use.

None

Returns:

Name Type Description
PluginSettings

A fully initialized :class:PluginSettings instance to be used to access the plugin's settings

plugin_settings_for_settings_plugin(plugin_key, instance, settings=None) #

Factory method for creating a :class:PluginSettings instance for a given :class:SettingsPlugin instance.

Will return None if the provided instance is not a :class:SettingsPlugin instance.

Parameters:

Name Type Description Default
plugin_key string

The plugin identifier for which to create the settings instance.

required
implementation octoprint.plugin.SettingsPlugin

The :class:SettingsPlugin instance.

required
settings octoprint.settings.Settings

The settings instance to use. Defaults to the global OctoPrint settings.

None

Returns:

Type Description

PluginSettings or None: A fully initialized :class:PluginSettings instance to be used to access the plugin's settings, or None if the provided instance was not a class:SettingsPlugin

Back to top