octoprint.plugin

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

PluginSettings(settings, plugin_key, defaults = None, get_preprocessors = None, set_preprocessors = None)

The 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 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:

• settings (octoprint.settings.Settings) –

  The Settings instance on which to operate.

• plugin_key (str) –

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

• defaults (dict) –

  The plugin's defaults settings.

• get_preprocessors (dict) –

  The plugin's get preprocessors. A dict of settings paths to callables that will be called with the value of the setting and should return the processed value.

• set_preprocessors (dict) –

  The plugin's set preprocessors. A dict of settings paths to callables that will be called with the value of the setting and should return the processed value.

defaults = None instance-attribute

The plugin's defaults settings, prefixed with the plugin's settings path.

get_preprocessors = {'plugins': {}} instance-attribute

The plugin's get preprocessors, prefixed with the plugin's settings path.

plugin_key = plugin_key instance-attribute

The plugin identifier of the plugin for which this instance was created.

set_preprocessors = {'plugins': {}} instance-attribute

The plugin's set preprocessors, prefixed with the plugin's settings path.

settings = settings instance-attribute

The Settings instance on which to operate.

add_overlay(overlay, **kwargs)

Adds an overlay for th plugin to the settings.

Parameters:

• overlay (dict) –

  The overlay to add.

Returns:

• str –

  The key under which the overlay was added.

clean_all_data()

Removes all data stored for this plugin.

get(path, **kwargs)

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

Parameters:

• path ((list, tuple)) –

  The path for which to retrieve the value.

• merged (bool) –

  Whether to merge the returned result with the default settings (True) or not (False, default).

• asdict (bool) –

  Whether to return the result as a dictionary (True) or not (False, default).

Returns:

• object –

  The retrieved settings value.

get_all_data(**kwargs)

Returns all data stored for this plugin.

Parameters:

• merged (bool) –

  Whether to merge the data with the defaults. Defaults to True.

• asdict (bool) –

  Whether to return the data as a dict. Defaults to True.

• defaults (bool) –

  Which defaults to use. Defaults to the plugin defaults.

• preprocessors (list) –

  List of preprocessors to apply to the data. Defaults to the plugin preprocessors.

get_boolean(path, **kwargs)

Like get but tries to convert the retrieved value to bool.

Parameters:

• path ((list, tuple)) –

  The path for which to retrieve the value.

Returns:

• bool | None –

  The retrieved settings value, converted to a boolean, if possible, None otherwise

get_float(path, **kwargs)

Like 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.

Parameters:

• path ((list, tuple)) –

  The path for which to retrieve the value.

• min (float) –

  The minimum value to return.

• max (float) –

  The maximum value to return.

Returns:

• float | None –

  The retrieved settings value, converted to a float, if possible, None otherwise

get_int(path, **kwargs)

Like 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.

Parameters:

• path ((list, tuple)) –

  The path for which to retrieve the value.

• min (int) –

  The minimum value to return.

• max (int) –

  The maximum value to return.

Returns:

• int | None –

  The retrieved settings value, converted to an integer, if possible, None otherwise

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 octoprint.plugin.types.SlicerPlugin might want to create a log file for logging the output of the slicing engine itself if some debug flag is set.

Parameters:

• 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.

Returns:

• str –

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

global_get(path, **kwargs)

Gets a value from the global settings structure.

Directly forwards to [octoprint.settings.Settings.get][]. See its documentation for possible parameters.

global_get_basefolder(folder_type, **kwargs)

Retrieves a globally defined basefolder of the given folder_type.

Directly forwards to [octoprint.settings.Settings.getBaseFolder][].

global_get_boolean(path, **kwargs)

Gets a value from the global settings structure and tries to convert it to bool.

Directly forwards to [octoprint.settings.Settings.getBoolean][]. See its documentation for possible parameters.

global_get_float(path, **kwargs)

Gets a value from the global settings structure and tries to convert it to float.

Directly forwards to [octoprint.settings.Settings.getFloat][]. See its documentation for possible parameters.

global_get_int(path, **kwargs)

Gets a value from the global settings structure and tries to convert it to int.

Directly forwards to [octoprint.settings.Settings.getInt][]. See its documentation for possible parameters.

global_has(path, **kwargs)

Checks whether the global settings structure has a value for path.

Directly forwards to [octoprint.settings.Settings.has][].

global_remove(path, **kwargs)

Removes the value for path from the global settings structure.

Directly forwards to [octoprint.settings.Settings.remove][].

global_set(path, value, **kwargs)

Sets a value in the global settings structure.

Directly forwards to [octoprint.settings.Settings.set][]. See its documentation for possible parameters.

global_set_boolean(path, value, **kwargs)

Sets a value in the global settings structure and tries to convert it to bool.

Directly forwards to [octoprint.settings.Settings.setBoolean][]. See its documentation for possible parameters.

global_set_float(path, value, **kwargs)

Sets a value in the global settings structure and tries to convert it to float.

Directly forwards to [octoprint.settings.Settings.setFloat][]. See its documentation for possible parameters.

global_set_int(path, value, **kwargs)

Sets a value in the global settings structure and tries to convert it to int.

Directly forwards to [octoprint.settings.Settings.setInt][]. See its documentation for possible parameters.

has(path, **kwargs)

Checks whether a value for path is present in the settings.

Parameters:

• path ((list, tuple)) –

  The path for which to check the value.

Returns:

• bool –

  Whether a value for path is present in the settings.

remove(path, **kwargs)

Removes the value for path from the settings.

Parameters:

• path ((list, tuple)) –

  The path for which to remove the value.

remove_overlay(key)

Removes an overlay from the settings by key.

Parameters:

• key (str) –

  The key of the overlay to remove.

set(path, value, **kwargs)

Sets the raw value on the settings for path.

Parameters:

• path ((list, tuple)) –

  The path for which to set the value.

• value (object) –

  The value to set.

• force (bool) –

  If set to True, the modified configuration will be written back to disk even if the value didn't change.

set_boolean(path, value, **kwargs)

Like set but ensures the value is an bool through attempted conversion before setting it.

Parameters:

• path ((list, tuple)) –

  The path for which to set the value.

• value (object) –

  The value to set.

set_float(path, value, **kwargs)

Like 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.

Parameters:

• path ((list, tuple)) –

  The path for which to set the value.

• value (object) –

  The value to set.

• min (float) –

  The minimum value to set.

• max (float) –

  The maximum value to set.

set_int(path, value, **kwargs)

Like 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.

Parameters:

• path ((list, tuple)) –

  The path for which to set the value.

• value (object) –

  The value to set.

• min (int) –

  The minimum value to set.

• max (int) –

  The maximum value to set.

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

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:

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:

• types (list) –

  A list of plugin implementation types to match against.

• method (str) –

  Name of the method to call on all matching implementations.

• args (tuple) –

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

• kwargs (dict) –

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

• callback (callable) –

  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.

• error_callback (callable) –

  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.

• initialized (bool) –

  Ignored.

• manager (octoprint.plugin.core.PluginManager | None) –

  The plugin manager to use. If not provided, the global plugin manager

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 PluginManager singleton.

Will set the logging prefix to octoprint.plugins..

Parameters:

• init (bool) –

  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 ValueError will be raised. The same will happen if the plugin manager has not yet been initialized and this is set to 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.

• plugin_bases (list) –

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

• 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.

• 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.

• 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.

• plugin_blacklist (list) –

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

• 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 glob patterns. If not provided this defaults to octoprint.server.http.*, octoprint.printer.factory, octoprint.access.permissions and octoprint.timelapse.extensions.

• 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. If not provided this defaults to octoprint.comm.protocol.gcode.

• plugin_considered_bundled (list) –

  A list of plugin identifiers that are considered bundled plugins even if installed separately. If not provided this defaults to firmware_check, file_check and pi_support.

• plugin_validators (list) –

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

• 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.

Returns:

• octoprint.plugin.core.PluginManager –

  A fully initialized PluginManager instance to be used for plugin management tasks.

Raises:

• 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 PluginSettings instance.

Parameters:

• plugin_key (str) –

  The plugin identifier for which to create the settings instance.

• defaults (dict) –

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

• get_preprocessors (dict) –

  The getter preprocessors for the plugin.

• set_preprocessors (dict) –

  The setter preprocessors for the plugin.

• settings (octoprint.settings.Settings) –

  The settings instance to use.

Returns:

• octoprint.plugin.PluginSettings –

  A fully initialized 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 PluginSettings instance for a given SettingsPlugin instance.

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

Parameters:

• plugin_key (string) –

  The plugin identifier for which to create the settings instance.

• instance (octoprint.plugin.types.SettingsPlugin) –

  The SettingsPlugin instance.

• settings (octoprint.settings.Settings) –

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

Returns:

• octoprint.plugin.PluginSettings | None –

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