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 instance-attribute #

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

attr_check = '__plugin_check__' class-attribute instance-attribute #

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

attr_description = '__plugin_description__' class-attribute instance-attribute #

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

attr_disable = '__plugin_disable__' class-attribute instance-attribute #

Module attribute which to call when disabling the plugin.

attr_disabling_DISCOURAGED = '__plugin_disabling_discouraged__' class-attribute instance-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 instance-attribute #

Module attribute which to call when enabling the plugin.

attr_helpers = '__plugin_helpers__' class-attribute instance-attribute #

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

attr_hidden = '__plugin_hidden__' class-attribute instance-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 instance-attribute #

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

attr_implementation = '__plugin_implementation__' class-attribute instance-attribute #

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

attr_license = '__plugin_license__' class-attribute instance-attribute #

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

attr_load = '__plugin_load__' class-attribute instance-attribute #

Module attribute which to call when loading the plugin.

attr_name = '__plugin_name__' class-attribute instance-attribute #

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

attr_privacypolicy = '__plugin_privacypolicy__' class-attribute instance-attribute #

Module attribute from which to retrieve the plugin's privacy policy URL, if any.

attr_pythoncompat = '__plugin_pythoncompat__' class-attribute instance-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 instance-attribute #

Module attribute which to call when unloading the plugin.

attr_url = '__plugin_url__' class-attribute instance-attribute #

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

attr_version = '__plugin_version__' class-attribute instance-attribute #

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

default_pythoncompat = '>=2.7,<3' class-attribute instance-attribute #

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

all() classmethod #

Returns a list of all recognized control properties, as defined in this class.

EntryPointMetadata(entry_point) #

Bases: pkginfo.Distribution

A wrapper around pkginfo.Distribution that extracts metadata from an EntryPoint object.

Parameters:

  • entry_point (pkg_resources.EntryPoint) –

    The entry point to extract metadata from.

EntryPointOrigin(type, entry_point, module_name, package_name, package_version) #

Origin of a plugin registered via an entry point.

entry_point = entry_point instance-attribute #

Name of the entry point, usually octoprint.plugin.

module_name = module_name instance-attribute #

Module registered to the entry point.

package_name = package_name instance-attribute #

Python package containing the entry point.

package_version = package_version instance-attribute #

Version of the python package containing the entry point.

type = type instance-attribute #

Always entry_point.

FolderOrigin(type, folder) #

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

folder = folder instance-attribute #

Folder path from which the plugin was loaded.

type = type instance-attribute #

Always folder.

ModuleOrigin(type, module_name, folder) #

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

folder = folder instance-attribute #

Folder path from which the plugin was loaded.

module_name = module_name instance-attribute #

Name of the module from which the plugin was loaded.

type = type instance-attribute #

Always module.

Plugin() #

The parent class of all plugin implementations.

_basefolder = None instance-attribute #

The base folder of the plugin.

_identifier = None instance-attribute #

The identifier of the plugin.

_logger = None instance-attribute #

The logger instance to use, with the logging name set to octoprint.plugin.core.PluginManager.logging_prefix concatenated with the contents of _identifier.

_plugin_name = None instance-attribute #

The name of the plugin.

_plugin_version = None instance-attribute #

The version of the plugin.

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.

PluginCantDisable(name, reason) #

Bases: PluginLifecycleException

Thrown by plugins that cannot be disabled.

PluginCantEnable(name, reason) #

Bases: PluginLifecycleException

Thrown by plugins that cannot be enabled.

PluginCantInitialize(name, reason) #

Bases: PluginLifecycleException

Thrown by plugins that cannot be initialized.

PluginInfo(key, location, instance, name = None, version = None, description = None, author = None, url = None, license = None, parsed_metadata = None) #

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

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

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

Parameters:

  • key (str) –

    Identifier of the plugin

  • location (str) –

    Installation folder of the plugin

  • instance (module) –

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

  • name (str) –

    Human readable name of the plugin

  • version (str) –

    Version of the plugin

  • description (str) –

    Description of the plugin

  • author (str) –

    Author of the plugin

  • url (str) –

    URL of the website of the plugin

  • license (str) –

    License of the plugin

author property #

Author of the plugin.

Will be taken from the author attribute of the plugin module if available, otherwise from the author supplied during construction. May be None.

Returns:

  • str | None –

    Author of the plugin.

blacklisted = False instance-attribute #

Whether the plugin is blacklisted.

bundled = False instance-attribute #

Whether this plugin is bundled with OctoPrint.

check property #

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

Returns:

  • callable –

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

control_properties property #

The control properties recognized in the plugin's AST.

description property #

Description of the plugin.

Will be taken from the description attribute of the plugin module if available, otherwise from the description supplied during construction. May be None.

Returns:

  • str | None –

    Description of the plugin.

disable property #

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

Returns:

  • callable –

    Disable method for the plugin module.

disabling_discouraged property #

Reason why disabling this plugin is discouraged.

Only evaluated for bundled plugins!

Will be taken from the disabling_discouraged attribute of the plugin module if available. False if unset or plugin not bundled.

Returns:

  • str | bool –

    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 if available, otherwise a no-operation lambda will be returned.

Returns:

  • callable –

    Enable method for the plugin module.

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.

helpers property #

Helpers provided by the plugin.

Will be taken from the helpers attribute of the plugin module if available, otherwise an empty dictionary is returned.

Returns:

  • dict –

    Helpers provided by the plugin, mapping from helper name to helper callable.

hidden property #

Hidden flag.

Will be taken from the hidden attribute of the plugin module if available, otherwise defaults to False.

Returns:

  • 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 if available, otherwise an empty dictionary is returned.

Returns:

  • dict –

    Hooks provided by the plugin, mapping from hook name to handler callable.

implementation property #

Implementation provided by the plugin.

Will be taken from the implementation attribute of the plugin module if available, otherwise None is returned.

Returns:

  • object | None –

    Implementation provided by the plugin.

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.

license property #

License of the plugin.

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

Returns:

  • str | None –

    License of the plugin.

load property #

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

Returns:

  • callable –

    Load method for the plugin module.

loaded = False instance-attribute #

Whether this plugin has been loaded.

looks_like_plugin property #

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

managable = True instance-attribute #

Whether this plugin can be managed by OctoPrint.

name property #

Human readable name of the plugin.

Will be taken from the name attribute of the plugin module if available, otherwise from the name supplied during construction with a fallback to key.

Returns:

  • str –

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

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 octoprint.plugin.core.EntryPointOrigin, octoprint.plugin.core.FolderOrigin or [octoprint.plugin.core.ModuleOrigin] instance. Set during loading, initially None.

parsed_metadata property #

The plugin metadata parsed from the plugin's AST.

privacypolicy property #

Privacy Policy URL of the plugin.

Will be taken from the privacy policy attribute of the plugin module if available. May be None.

Returns:

  • str | None –

    Privacy Policy URL of the plugin.

pythoncompat property #

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

Returns:

  • 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 if available, otherwise a no-operation lambda will be returned.

Returns:

  • 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 if available, otherwise from the url supplied during construction. May be None.

Returns:

  • str | None –

    Website URL for the plugin.

version property #

Version of the plugin.

Will be taken from the version attribute of the plugin module if available, otherwise from the version supplied during construction. May be None.

Returns:

  • str | None –

    Version of the plugin.

get_hook(hook) #

Parameters:

  • hook (str) –

    Hook to return.

Returns:

  • callable | None –

    Handler for the requested hook, or None if no handler is registered.

get_implementation(*types) #

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

Parameters:

Returns:

  • object | None –

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

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. They 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. Example: ("* ", " ", "X ", "C ")
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. Example: (" [B]", "")
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. Example: " - {location}"

Parameters:

  • show_enabled (boolean) –

    whether to show the enabled part

  • enabled_strs (tuple) –

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

  • show_bundled (boolean) –

    whether to show the bundled part

  • bundled_strs(tuple) –

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

  • show_location (boolean) –

    whether to show the location part

  • location_str (str) –

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

Returns:

  • str –

    The long string representation of the plugin as described above

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 octoprint.plugin.core.PluginManager, should not be used elsewhere.

Parameters:

  • phase (str) –

    Phase to validate for, one of before_import, before_load, after_load

  • additional_validators (list) –

    List of additional validator functions to call, each of which should accept two arguments, phase and plugin_info, and return a boolean indicating whether the plugin should be considered valid for the given phase.

Returns:

  • bool –

    Whether the plugin is valid for the given phase.

PluginLifecycleException(name, reason, message) #

Bases: Exception

General plugin lifecycle exception.

PluginManager(plugin_folders, plugin_bases, plugin_entry_points, logging_prefix = 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) #

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.

compatibility_ignored_list = compatibility_ignored_list instance-attribute #

A list of plugin keys that should be ignored when checking for compatibility.

disabled_plugins = {} instance-attribute #

A dictionary of disabled plugins, identifier mapped to plugin.

enabled_plugins = {} instance-attribute #

A dictionary of enabled plugins, identifier mapped to plugin.

logging_prefix = logging_prefix instance-attribute #

The logging prefix to use for all plugins.

plugin_bases = plugin_bases instance-attribute #

A list of base classes that plugins must inherit from.

plugin_blacklist = processed_blacklist instance-attribute #

A list of plugin keys that should not be loaded.

plugin_considered_bundled = plugin_considered_bundled instance-attribute #

A list of plugin keys that are considered bundled.

plugin_disabled_list = plugin_disabled_list instance-attribute #

A list of plugin keys that should not be enabled when loading.

plugin_entry_points = plugin_entry_points instance-attribute #

A list of entry points to search for plugins in.

plugin_folders = plugin_folders instance-attribute #

A list of folders to search for plugins in.

plugin_hooks property #

Returns:

  • –

    (dict) dictionary of registered hooks and their handlers

plugin_obsolete_hooks = plugin_obsolete_hooks instance-attribute #

A list of plugin hooks that are obsolete.

plugin_restart_needing_hooks = plugin_restart_needing_hooks instance-attribute #

A list of plugin hooks that need a restart to take effect.

plugin_sorting_order = plugin_sorting_order instance-attribute #

A dictionary of plugin keys and their sorting order definitions.

plugin_validators = plugin_validators instance-attribute #

A list of validator functions that will be called for each plugin to determine whether it is valid or not.

plugins property #

Returns:

  • –

    (list) list of enabled and disabled registered plugins

disable_plugin(name, plugin = None) #

Disables a plugin.

Parameters:

Raises:

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

Enables a plugin.

Parameters:

  • name (str) –

    plugin identifier

  • plugin (octoprint.plugin.core.Plugin) –

    plugin instance

  • initialize_implementation (bool) –

    whether plugin implementations should be initialized

  • startup (bool) –

    whether this is called during startup of the platform

Returns:

  • bool –

    True if the plugin was enabled, False otherwise

Raises:

find_plugins(existing = None, ignore_uninstalled = True, incl_all_found = False) #

Run the plugin discovery process and return the added plugins.

Parameters:

  • existing (dict) –

    Existing plugins to check against

  • ignore_uninstalled (bool) –

    Ignore plugins marked as uninstalled

  • incl_all_found (bool) –

    Return all found plugins, not just the added ones

Returns:

  • dict | tuple –

    Dictionary of added plugins or tuple of added (dict) and all found (list) plugins

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

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

Parameters:

  • f (callable) –

    A filter function returning True for implementations to return and False for those to exclude. Gets passed each implementation as its only argument.

  • types (type) –

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

Returns:

  • 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 (str) –

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

  • helpers (str) –

    Identifiers of the helpers of plugin name to return.

Returns:

  • dict –

    A dictionary of all resolved helper callables, 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:

  • hook (str) –

    The hook for which to retrieve the handlers.

Returns:

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

  • types (type) –

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

Returns:

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

  • identifier (str) –

    The identifier of the plugin to retrieve.

  • require_enabled (bool) –

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

Returns:

  • module –

    The requested plugin module or None

get_plugin_info(identifier, require_enabled = True) #

Retrieves the octoprint.plugin.core.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:

  • identifier (str) –

    The identifier of the plugin to retrieve.

  • require_enabled (bool) –

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

Returns:

has_any_of_hooks(plugin, *hooks) staticmethod #

Tests if the plugin contains any of the provided hooks.

Uses octoprint.plugin.core.PluginManager.hook_matches_hooks.

Parameters:

Returns:

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

Returns:

  • 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 of the defined obsolete hooks.

Parameters:

Returns:

  • bool –

    True if the plugin uses any of the defined obsolete hooks, False otherwise

has_restart_needing_hooks(plugin) #

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

Parameters:

Returns:

  • bool –

    True if the plugin has any hooks that need a server restart on changes, False otherwise

has_restart_needing_implementation(plugin) #

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

Parameters:

Returns:

  • bool –

    True if the plugin's implementation needs a server restart on changes, False otherwise

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 [fnmatch.fnmatch] pattern.

Parameters:

  • hook (str) –

    the hook to test

  • hooks (str) –

    the hook name patterns to test against

Returns:

  • bool –

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

initialize_implementation(name, plugin, implementation, additional_injects = None, additional_inject_factories = None, additional_pre_inits = None, additional_post_inits = None) #

Initializes the given implementation.

Parameters:

  • name (str) –

    name of the plugin

  • plugin (octoprint.plugin.core.Plugin) –

    plugin to initialize the implementation for

  • implementation (tuple) –

    implementation to initialize

  • additional_injects (dict) –

    additional injects to inject into the implementation, a dict mapping inject names to inject objects

  • additional_inject_factories (list) –

    additional inject factories to use to generate injections into the implementation, each included callable will be called with the plugin's identifier and the implementation as parameters and is expected to return a dict of injections mapping inject names to inject objects

  • additional_pre_inits (list) –

    additional pre-initialization hooks to call, each included callable will be called with the plugin's identifier and the implementation as parameters

  • additional_post_inits (list) –

    additional post-initialization hooks to call, each included callable will be called with the plugin's identifier and the implementation as parameters

initialize_implementation_of_plugin(name, plugin, additional_injects = None, additional_inject_factories = None, additional_pre_inits = None, additional_post_inits = None) #

Initializes the implementation of the given plugin.

Parameters:

  • name (str) –

    name of the plugin

  • plugin (octoprint.plugin.core.Plugin) –

    plugin to initialize the implementation for

  • additional_injects (dict) –

    additional injects to inject into the implementation, a dict mapping inject names to inject objects

  • additional_inject_factories (list) –

    additional inject factories to use to generate injections into the implementation, each included callable will be called with the plugin's identifier and the implementation as parameters and is expected to return a dict of injections mapping inject names to inject objects

  • additional_pre_inits (list) –

    additional pre-initialization hooks to call, each included callable will be called with the plugin's identifier and implementation as arguments

  • additional_post_inits (list) –

    additional post-initialization hooks to call, each included callable will be called with the plugin's identifier and implementation as arguments

Returns:

  • bool –

    True if the plugin's implementation was initialized, False otherwise.

initialize_implementations(additional_injects = None, additional_inject_factories = None, additional_pre_inits = None, additional_post_inits = None) #

Initializes all plugin implementations.

Parameters:

  • additional_injects (dict) –

    additional injects to inject into the implementation, a dict mapping inject names to inject objects

  • additional_inject_factories (list) –

    additional inject factories to use to generate injections into implementations, each included callable will be called with the plugin's identifier and implementation as arguments and is expected to return a dict of injections mapping inject names to inject objects

  • additional_pre_inits (list) –

    additional pre-initialization hooks to call, will be called with the plugin's identifier and implementation as arguments

  • additional_post_inits (list) –

    additional post-initialization hooks to call, will be called with the plugin's identifier and implementation as arguments

is_obsolete_hook(hook) #

Checks whether a hook is defined obsolete.

Parameters:

  • hook (str) –

    hook to check

Returns:

  • bool –

    True if the hook is defined obsolete, False otherwise

is_plugin_marked(name, flag) #

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

Parameters:

  • name (str) –

    the plugin's identifier

  • flag (str) –

    the flag to check

Returns:

  • bool –

    True if the plugin has been flagged, False otherwise

is_restart_needing_hook(hook) #

Checks whether a hook needs a restart on changes.

Parameters:

  • hook (str) –

    hook to check

Returns:

  • bool –

    True if the hook needs a server restart on changes, False otherwise

is_restart_needing_plugin(plugin) #

Checks whether the plugin needs a restart on changes.

Parameters:

Returns:

  • bool –

    True if the plugin needs a server restart on changes, False otherwise

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

Loads plugin name, triggering all lifecycle events as needed.

Parameters:

  • name (str) –

    plugin identifier

  • plugin (octoprint.plugin.core.Plugin) –

    plugin instance

  • startup (bool) –

    whether this is called during startup of the platform

  • initialize_implementation (bool) –

    whether plugin implementations should be initialized

Raises:

log_all_plugins(show_bundled = True, bundled_str = (' (bundled)', ''), show_location = True, location_str = ' = {location}', show_enabled = True, enabled_str = (' ', '!', '#', '*'), only_to_handler = None) #

Logs all plugins to the logger.

Parameters:

  • show_bundled (bool) –

    whether to show if plugins are bundled

  • bundled_str (tuple) –

    strings to use for bundled plugins, first string is used if the plugin is bundled, second string if it is not

  • show_location (bool) –

    whether to show the location of the plugin

  • location_str (str) –

    string to use for the location of the plugin, will be formatted with the location

  • show_enabled (bool) –

    whether to show if plugins are enabled

  • enabled_str (tuple) –

    strings to use for enabled plugins, first string is used if the plugin is enabled, second string if it is not

  • only_to_handler (logging.handler.Handler) –

    if given, only log to the given handler, otherwise log to the logger

mark_plugin(name, **flags) #

Mark plugin name with an arbitrary number of flags.

Parameters:

  • name (str) –

    plugin identifier

  • flags (dict) –

    dictionary of flag names and values

mixins_matching_bases(klass, *bases) staticmethod #

Returns a set of all mixins of the given klass that match any of the provided bases.

Parameters:

  • klass (type) –

    the class to check for mixins

  • bases (type) –

    the base classes to check against

Returns:

  • set –

    a set of all mixins of the given klass that match any of the provided bases.

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

Parameters:

  • client (callable) –

    The client to register for receiving plugin messages.

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

Reloads plugins, detecting newly added ones in the process.

Logs the currently detected plugins and their status.

Parameters:

  • startup (boolean) –

    whether this is called during startup of the platform

  • initialize_implementations (boolean) –

    whether plugin implementations should be initialized

  • force_reload (list) –

    list of plugin identifiers which should be force reloaded

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:

  • plugin (str) –

    The sending plugin's identifier.

  • data (dict) –

    The message.

  • permissions (list) –

    A list of permissions to test against in the client.

unload_plugin(name) #

Unloads plugin name, triggering all lifecycle events as needed.

Parameters:

  • name (str) –

    plugin identifier

Raises:

unregister_message_receiver(client) #

Unregisters a client for receiving plugin messages.

Parameters:

  • client (callable) –

    The client to unregister for receiving plugin messages.

PluginNeedsRestart(name) #

Bases: Exception

Thrown by plugins that need a restart after enabling/disabling them.

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:

  • context (str) –

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

Returns:

  • int | None –

    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_editable_install(install_dir, package, module, location) #

Tests if a package is installed in editable mode.

Checks if a file <install_dir>/<package>.egg-link exists and if it contains a line that points to <location>/<module>.

Parameters:

  • install_dir (str) –

    The directory in which the package is installed.

  • package (str) –

    The name of the package.

  • module (str) –

    The name of the module.

  • location (str) –

    The location of the module.

is_sub_path_of(path, parent) #

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

Examples:

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

Parameters:

  • path (str) –

    The path to test.

  • parent (str) –

    The parent path to test against.

parse_plugin_metadata(path) #

Parses the plugin metadata from the plugin at the given path.

If the provided path is a dictionary, it is assumed to be the path to a Python module with a contained __init__.py.

The metadata is parsed from the AST of the plugin's Python source. If the plugin could not be parsed due to a syntax error in its Python source, a SyntaxError is raised.

Only the following control properties are attempted to be parsed from the AST:

  • __plugin_name__
  • __plugin_version__
  • __plugin_author__
  • __plugin_description__
  • __plugin_url__
  • __plugin_license__
  • __plugin_pythoncompatibility__

This is also the list of plugin metadata available even for disabled/unloaded plugins. For all other control properties to be available, the plugin must be loaded by OctoPrint.

Parameters:

  • path (str) –

    The path to the plugin to parse the metadata from.

Returns:

  • dict –

    The parsed metadata. If no metadata could be parsed, an empty dictionary is returned.

Raises:

  • SyntaxError –

    If the plugin could not be parsed due to a syntax error in its Python source.