Skip to content

octoprint.plugin.core#

In this module resides the core data structures and logic of the plugin system.

ControlProperties #

attr_author = '__plugin_author__' class-attribute #

Module attribute from which to retrieve the plugin's author.

attr_check = '__plugin_check__' class-attribute #

Module attribute which to call to determine if the plugin can be loaded.

attr_description = '__plugin_description__' class-attribute #

Module attribute from which to retrieve the plugin's description.

attr_disable = '__plugin_disable__' class-attribute #

Module attribute which to call when disabling the plugin.

attr_disabling_discouraged = '__plugin_disabling_discouraged__' class-attribute #

Module attribute from which to retrieve the reason why disabling the plugin is discouraged. Only effective if self.bundled is True.

attr_enable = '__plugin_enable__' class-attribute #

Module attribute which to call when enabling the plugin.

attr_helpers = '__plugin_helpers__' class-attribute #

Module attribute from which to retrieve the plugin's provided helpers.

attr_hidden = '__plugin_hidden__' class-attribute #

Module attribute from which to determine if the plugin's hidden or not.

Only evaluated for bundled plugins, in order to hide them from the Plugin Manager and similar places.

attr_hooks = '__plugin_hooks__' class-attribute #

Module attribute from which to retrieve the plugin's provided hooks.

attr_implementation = '__plugin_implementation__' class-attribute #

Module attribute from which to retrieve the plugin's provided mixin implementation.

attr_license = '__plugin_license__' class-attribute #

Module attribute from which to retrieve the plugin's license.

attr_load = '__plugin_load__' class-attribute #

Module attribute which to call when loading the plugin.

attr_name = '__plugin_name__' class-attribute #

Module attribute from which to retrieve the plugin's human readable name.

attr_pythoncompat = '__plugin_pythoncompat__' class-attribute #

Module attribute from which to retrieve the plugin's python compatibility string.

If unset a default of >=2.7,<3 will be assumed, meaning that the plugin will be considered compatible to Python 2 but not Python 3.

To mark a plugin as Python 3 compatible, a string of >=2.7,<4 is recommended.

Bundled plugins will automatically be assumed to be compatible.

attr_unload = '__plugin_unload__' class-attribute #

Module attribute which to call when unloading the plugin.

attr_url = '__plugin_url__' class-attribute #

Module attribute from which to retrieve the plugin's website URL.

attr_version = '__plugin_version__' class-attribute #

Module attribute from which to retrieve the plugin's version.

EntryPointOrigin #

Bases: _EntryPointOrigin

Origin of a plugin registered via an entry point.

Attributes:

Name Type Description
type str

Always entry_point.

entry_point str

Name of the entry point, usually octoprint.plugin.

module_name str

Module registered to the entry point.

package_name str

Python package containing the entry point.

package_version str

Version of the Python package containing the entry point.

FolderOrigin #

Bases: _FolderOrigin

Origin of a (single file) plugin loaded from a plugin folder.

Attributes:

Name Type Description
type str

Always folder.

ModuleOrigin #

Bases: _ModuleOrigin

Origin of a (single file) plugin loaded from a plugin folder.

Attributes:

Name Type Description
type str

Always module.

module_name str

Name of the module from which the plugin was loaded.

folder str

Folder path from which the plugin was loaded.

Plugin #

The parent class of all plugin implementations.

Attributes:

Name Type Description
_identifier str

The identifier of the plugin. Injected by the plugin core system upon initialization of the implementation.

_plugin_name str

The name of the plugin. Injected by the plugin core system upon initialization of the implementation.

_plugin_version str

The version of the plugin. Injected by the plugin core system upon initialization of the implementation.

_basefolder str

The base folder of the plugin. Injected by the plugin core system upon initialization of the implementation.

_logger logging.Logger

The logger instance to use, with the logging name set to the [logging_prefix][octoprint.plugin.core.PluginManager.logging_prefix] of the PluginManager concatenated with the value of _identifier. Injected by the plugin core system upon initialization of the implementation.

initialize() #

Called by the plugin core after performing all injections. Override this to initialize your implementation.

on_plugin_disabled() #

Called by the plugin core when the plugin was disabled. Override this to react to the event.

on_plugin_enabled() #

Called by the plugin core when the plugin was enabled. Override this to react to the event.

PluginInfo #

The PluginInfo class wraps all available information about a registered plugin.

This includes its meta data (like name, description, version, etc) as well as the actual plugin extensions like implementations, hooks and helpers.

It works on Python module objects and extracts the relevant data from those via accessing the control properties.

Parameters:

Name Type Description Default
key str

Identifier of the plugin

required
location str

Installation folder of the plugin

required
instance module

Plugin module instance - this may be None if the plugin has been blacklisted!

required
name str

Human readable name of the plugin

None
version str

Version of the plugin

None
description str

Description of the plugin

None
author str

Author of the plugin

None
url str

URL of the website of the plugin

None
license str

License of the plugin

None

blacklisted = False instance-attribute #

Whether the plugin is blacklisted.

bundled = False instance-attribute #

Whether this plugin is bundled with OctoPrint.

enabled = True instance-attribute #

Whether the plugin is enabled.

forced_disabled = False instance-attribute #

Whether the plugin has been force disabled by the system, e.g. due to safe mode blacklisting.

incompatible = False instance-attribute #

Whether this plugin has been detected as incompatible.

invalid_syntax = False instance-attribute #

Whether invalid syntax was encountered while trying to load this plugin.

loaded = False instance-attribute #

Whether this plugin has been loaded.

managable = True instance-attribute #

Whether this plugin can be managed by OctoPrint.

needs_restart = False instance-attribute #

Whether this plugin needs a restart of OctoPrint after enabling/disabling.

origin = None instance-attribute #

The origin from which this plugin was loaded, either a :class:EntryPointOrigin, :class:FolderOrigin or :class:ModuleOrigin instance. Set during loading, initially None.

author() property #

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:

Type Description
Optional[str]

Author of the plugin.

check() property #

Method for pre-load check of plugin. Will be taken from the check attribute of the plugin module as defined in attr_check if available, otherwise a lambda always returning True is returned.

Returns:

Type Description
callable

Check method for the plugin module which should return True if the plugin can be loaded, False otherwise.

description() property #

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:

Type Description
Optional[str]

Description of the plugin.

disable() property #

Method for disabling the plugin module. Will be taken from the disable attribute of the plugin module as defined in :attr:attr_disable if available, otherwise a no-operation lambda will be returned.

Returns:

Type Description
callable

Disable method for the plugin module.

disabling_discouraged() property #

Reason why disabling of this plugin is discouraged. Only evaluated for bundled plugins! Will be taken from the disabling_discouraged attribute of the plugin module as defined in :attr:attr_disabling_discouraged if available. False if unset or plugin not bundled.

Returns:

Type Description
Optional[str]

Reason why disabling this plugin is discouraged (only for bundled plugins)

enable() property #

Method for enabling the plugin module. Will be taken from the enable attribute of the plugin module as defined in attr_enable if available, otherwise a no-operation lambda will be returned.

Returns:

Type Description
callable

Enable method for the plugin module.

get_hook(hook) #

Parameters:

Name Type Description Default
hook str

Hook to return.

required

Returns:

Type Description
Optional[Callable]

Handler for the requested hook

get_implementation(*types) #

Parameters:

Name Type Description Default
types list

List of :class:Plugin sub classes the implementation needs to implement.

required

Returns:

Type Description
object

The plugin's implementation if it matches all of the requested types, None otherwise.

helpers() property #

Helpers provided by the plugin. Will be taken from the helpers attribute of the plugin module as defined in attr_helpers if available, otherwise an empty list is returned.

Returns:

Type Description
dict

Helpers provided by the plugin.

hidden() property #

Hidden flag.

Returns:

Type Description
bool

Whether the plugin should be flagged as hidden or not

hooks() property #

Hooks provided by the plugin. Will be taken from the hooks attribute of the plugin module as defined in attr_hooks if available, otherwise an empty dictionary is returned.

Returns:

Type Description
dict

Hooks provided by the plugin.

implementation() property #

Implementation provided by the plugin. Will be taken from the implementation attribute of the plugin module as defined in attr_implementation if available, otherwise None is returned.

Returns:

Type Description
object

Implementation provided by the plugin.

license() property #

License of the plugin. Will be taken from the license attribute of the plugin module as defined in attr_license if available, otherwise from the license supplied during construction. May be None.

Returns:

Type Description
Optional[str]

License of the plugin.

load() property #

Method for loading the plugin module. Will be taken from the load attribute of the plugin module as defined in attr_load if available, otherwise a no-operation lambda will be returned.

Returns:

Type Description
callable

Load method for the plugin module.

long_str(show_bundled=False, bundled_strs=(' [B]', ''), show_location=False, location_str=' - {location}', show_enabled=False, enabled_strs=('* ', ' ', 'X ', 'C ')) #

Long string representation of the plugin's information. Will return a string of the format <enabled><str(self)><bundled><location>.

enabled, bundled and location will only be displayed if the corresponding flags are set to True. The will be filled from enabled_str, bundled_str and location_str as follows:

enabled_str
a 4-tuple, the first entry being the string to insert when the plugin is enabled, the second entry the string to insert when it is not, the third entry the string when it is blacklisted and the fourth when it is incompatible.
bundled_str
a 2-tuple, the first entry being the string to insert when the plugin is bundled, the second entry the string to insert when it is not.
location_str
a format string (to be parsed with str.format), the {location} placeholder will be replaced with the plugin's installation folder on disk.

Parameters:

Name Type Description Default
show_enabled boolean

whether to show the enabled part

False
enabled_strs tuple

the 2-tuple containing the two possible strings to use for displaying the enabled state

('* ', ' ', 'X ', 'C ')
show_bundled boolean

whether to show the bundled part

False
bundled_strs(tuple)

the 2-tuple containing the two possible strings to use for displaying the bundled state

required
show_location boolean

whether to show the location part

False
location_str str

the format string to use for displaying the plugin's installation location

' - {location}'

Returns:

Type Description
str

The long string representation of the plugin as described above

looks_like_plugin() property #

Returns whether the plugin actually looks like a plugin (has control properties) or not.

name() property #

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:

Type Description
str

Name of the plugin, fallback is the plugin's identifier.

parsed_metadata() property #

The plugin metadata parsed from the plugin's AST.

pythoncompat() property #

Python compatibility string of the plugin module as defined in attr_pythoncompat if available, otherwise defaults to >=2.7,<3.

Returns:

Type Description
str

Python compatibility string of the plugin

unload() property #

Method for unloading the plugin module. Will be taken from the unload attribute of the plugin module as defined in attr_unload if available, otherwise a no-operation lambda will be returned.

Returns:

Type Description
callable

Unload method for the plugin module.

url() property #

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:

Type Description
Optional[str]

Website URL for the plugin.

validate(phase, additional_validators=None) #

Validates the plugin for various validation phases.

phase can be one of before_import, before_load, after_load.

Used by PluginManager, should not be used elsewhere.

version() property #

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:

Type Description
Optional[str]

Version of the plugin.

PluginManager #

The PluginManager is the central component for finding, loading and accessing plugins provided to the system.

It is able to discover plugins both through possible file system locations as well as customizable entry points.

disable_plugin(name, plugin=None) #

Disables a plugin

enable_plugin(name, plugin=None, initialize_implementation=True, startup=False) #

Enables a plugin

get_filtered_implementations(f, *types, **kwargs) #

Get all mixin implementations that implement all of the provided types and match the provided filter f.

Parameters:

Name Type Description Default
f callable

A filter function returning True for implementations to return and False for those to exclude.

required
types one or more type

The types a mixin implementation needs to implement in order to be returned.

required

Returns:

Type Description
list

A list of all found and matching implementations.

get_helpers(name, *helpers) #

Retrieves the named helpers for the plugin with identifier name.

If the plugin is not available, returns None. Otherwise returns a :class:dict with the requested plugin helper names mapped to the method - if a helper could not be resolved, it will be missing from the dict.

Parameters:

Name Type Description Default
name str

Identifier of the plugin for which to look up the helpers.

required
helpers one or more str

Identifiers of the helpers of plugin name to return.

required

Returns:

Type Description
dict

A dictionary of all resolved helpers, mapped by their identifiers, or None if the plugin was not registered with the system.

get_hooks(hook) #

Retrieves all registered handlers for the specified hook.

Parameters:

Name Type Description Default
hook str

The hook for which to retrieve the handlers.

required

Returns:

Type Description
dict

A dict containing all registered handlers mapped by their plugin's identifier.

get_implementations(*types, **kwargs) #

Get all mixin implementations that implement all of the provided types.

Parameters:

Name Type Description Default
types List[Type]

The types a mixin implementation needs to implement in order to be returned.

required

Returns:

Type Description
list

A list of all found implementations

get_plugin(identifier, require_enabled=True) #

Retrieves the module of the plugin identified by identifier. If the plugin is not registered or disabled and required_enabled is True (the default) None will be returned.

Parameters:

Name Type Description Default
identifier str

The identifier of the plugin to retrieve.

required
require_enabled boolean

Whether to only return the plugin if is enabled (True, default) or also if it's disabled.

True

Returns:

Type Description
module

The requested plugin module if it could be found

None

The plugin module could not be found

get_plugin_info(identifier, require_enabled=True) #

Retrieves the PluginInfo instance identified by identifier. If the plugin is not registered or disabled and required_enabled is True (the default) None will be returned.

Parameters:

Name Type Description Default
identifier str

The identifier of the plugin to retrieve.

required
require_enabled boolean

Whether to only return the plugin if is enabled (True, default) or also if it's disabled.

True

Returns:

Type Description
octoprint.plugin.core.PluginInfo

The requested PluginInfo if it could be found

None

The requested plugin could not be found

has_any_of_hooks(plugin, *hooks) staticmethod #

Tests if the plugin contains any of the provided hooks.

Uses :func:octoprint.plugin.core.PluginManager.hook_matches_hooks.

Parameters:

Name Type Description Default
plugin

plugin to test hooks for

required
hooks

hooks to test against

required

Returns:

Type Description
bool

True if any of the plugin's hooks match the provided hooks, False otherwise.

has_any_of_mixins(plugin, *mixins) staticmethod #

Tests if the plugin has an implementation implementing any of the provided mixins.

Parameters:

Name Type Description Default
plugin

plugin for which to check the implementation

required
mixins

mixins to test against

required

Returns:

Type Description
bool

True if the plugin's implementation implements any of the provided mixins, False otherwise.

has_obsolete_hooks(plugin) #

Checks whether the plugin uses any obsolete hooks

has_restart_needing_hooks(plugin) #

Checks whether the plugin has any hooks that need a restart on changes

has_restart_needing_implementation(plugin) #

Checks whether the plugin's implementation needs a restart on changes

hook_matches_hooks(hook, *hooks) staticmethod #

Tests if hook matches any of the provided hooks to test for.

hook is expected to be an exact hook name.

hooks is expected to be a list containing one or more hook names or patterns. That can be either an exact hook name or an :func:fnmatch.fnmatch pattern.

Parameters:

Name Type Description Default
hook

the hook to test

required
hooks

the hook name patterns to test against

required

Returns:

Type Description
bool

True if the hook matches any of the hooks, False otherwise.

is_obsolete_hook(hook) #

Checks whether a hook is obsolete

is_plugin_marked(name, flag) #

Checks whether a plugin has been marked with a certain flag.

Parameters:

Name Type Description Default
name str

the plugin's identifier

required
flag str

the flag to check

required

Returns:

Type Description
bool

True if the plugin has been flagged, False otherwise

is_restart_needing_hook(hook) #

Checks whether a hook needs a restart on changes

is_restart_needing_plugin(plugin) #

Checks whether the plugin needs a restart on changes

mark_plugin(name, **flags) #

Mark plugin name with an arbitrary number of flags.

Parameters:

Name Type Description Default
name str

plugin identifier

required
flags dict

dictionary of flag names and values

required

plugin_hooks() property #

Returns:

Type Description

(dict) dictionary of registered hooks and their handlers

plugins() property #

Returns:

Type Description

(list) list of enabled and disabled registered plugins

register_message_receiver(client) #

Registers a client for receiving plugin messages. The client needs to be a callable accepting two input arguments, plugin (the sending plugin's identifier) and data (the message itself), and one optional keyword argument, permissions (an optional list of permissions to test against).

reload_plugins(startup=False, initialize_implementations=True, force_reload=None) #

Reloads plugins, detecting newly added ones in the process.

Parameters:

Name Type Description Default
startup bool

whether this is called during startup of the platform

False
initialize_implementations bool

whether plugin implementations should be initialized

True
force_reload list

list of plugin identifiers which should be force reloaded

None

send_plugin_message(plugin, data, permissions=None) #

Sends data in the name of plugin to all currently registered message receivers by invoking them with the three arguments.

Parameters:

Name Type Description Default
plugin str

The sending plugin's identifier.

required
data object

The message.

required
permissions list

A list of permissions to test against in the client.

None

unregister_message_receiver(client) #

Unregisters a client for receiving plugin messages.

RestartNeedingPlugin #

Bases: Plugin

Mixin for plugin types that need a restart after enabling/disabling them.

SortablePlugin #

Bases: Plugin

Mixin for plugin types that are sortable.

get_sorting_key(context=None) #

Returns the sorting key to use for the implementation in the specified context.

May return None if order is irrelevant.

Implementations returning None will be ordered by plugin identifier after all implementations which did return a sorting key value that was not None sorted by that.

Parameters:

Name Type Description Default
context str

The sorting context for which to provide the sorting key value.

None

Returns:

Type Description
Optional[int]

An integer signifying the sorting key value of the plugin (sorting will be done ascending), or None if the implementation doesn't care about calling order.

is_sub_path_of(path, parent) #

Tests if path is a sub path of (or identical to) parent.

Parameters:

Name Type Description Default
path str

The path to test.

required
parent str

The parent path to test against.

required
Example
>>> is_sub_path_of("/a/b/c", "/a/b")
True
>>> is_sub_path_of("/a/b/c", "/a/b2")
False
>>> is_sub_path_of("/a/b/c", "/b/c")
False
>>> is_sub_path_of("/foo/bar/../../a/b/c", "/a/b")
True
>>> is_sub_path_of("/a/b", "/a/b")
True
Back to top