1.13. plugins

This module provides the core functionality necessary to support user provided plugins.

1.13.1. Functions

recursive_reload(module)[source]

Reload module and if it is a package, recursively find and reload it’s imported sub-modules.

Parameters:module (module) – The module to reload.
Returns:The reloaded module.

1.13.2. Classes

class OptionBase(name, description, default=None)[source]

Bases: object

A base class for options which can be configured for plugins.

__init__(name, description, default=None)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • default – The default value of this option.
class OptionBoolean(name, description, default=None)[source]

Bases: king_phisher.plugins.OptionBase

A plugin option which is represented with a boolean value.

__init__(name, description, default=None)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • default – The default value of this option.
class OptionEnum(name, description, choices, default=None)[source]

Bases: king_phisher.plugins.OptionBase

A plugin option which is represented with an enumerable value.

__init__(name, description, choices, default=None)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • choices (tuple) – The supported values for this option.
  • default – The default value of this option.
class OptionInteger(name, description, default=None)[source]

Bases: king_phisher.plugins.OptionBase

A plugin option which is represented with an integer value.

__init__(name, description, default=None)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • default – The default value of this option.
class OptionString(name, description, default=None)[source]

Bases: king_phisher.plugins.OptionBase

A plugin option which is represented with a string value.

__init__(name, description, default=None)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • default – The default value of this option.
class PluginBase[source]

Bases: king_phisher.plugins.PluginBaseMeta

A base class to be inherited by all plugins. Overriding or extending the standard __init__ method should be avoided to be compatible with future API changes. Instead the initialize() and finalize() methods should be overridden to provide plugin functionality.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

authors = ()[source]

The tuple of authors who have provided this plugin.

classifiers = ()[source]

An array containing optional classifier strings. These are free-formatted strings used to identify functionality.

config = None[source]

The plugins configuration dictionary for storing the values of it’s options.

description = None[source]

A description of the plugin and what it does.

finalize()[source]

This method can be overridden to perform any clean up action that the plugin needs such as closing files. It is called automatically by the manager when the plugin is disabled.

homepage = None[source]

An optional homepage for the plugin.

initialize()[source]

This method should be overridden to provide the primary functionality of the plugin. It is called automatically by the manager when the plugin is enabled.

Returns:Whether or not the plugin successfully initialized itself.
Return type:bool
options = [][source]

A list of configurable option definitions for the plugin.

reference_urls = ()[source]

An array containing optional reference URL strings.

req_min_py_version = None[source]

The required minimum Python version for compatibility.

req_min_version = '1.3.0b0'[source]

The required minimum version for compatibility.

req_packages = {}[source]

A dictionary of required packages, keyed by the package name and a boolean value of it’s availability.

req_platforms = ()[source]

A tuple of case-insensitive supported platform names.

title = None[source]

The title of the plugin.

version = '1.0'[source]

The version identifier of this plugin.

class PluginBaseMeta[source]

Bases: type

The meta class for PluginBase which provides additional class properties based on defined attributes.

compatibility[source]

A generator which yields tuples of compatibility information based on the classes defined attributes. Each tuple contains three elements, a string describing the requirement, the requirements value, and a boolean indicating whether or not the requirement is met.

Returns:Tuples of compatibility information.
is_compatible[source]

Whether or not this plugin is compatible with this version of King Phisher. This can only be checked after the module is imported, so any references to non-existent classes in older versions outside of the class methods will still cause a load error.

Returns:Whether or not this plugin class is compatible.
Return type:bool
class PluginManagerBase(path, args=None, library_path=AUTOMATIC)[source]

Bases: object

A managing object to control loading and enabling individual plugin objects.

__init__(path, args=None, library_path=AUTOMATIC)[source]
Parameters:
  • path (tuple) – A tuple of directories from which to load plugins.
  • args (tuple) – Arguments which should be passed to plugins when their class is initialized.
  • library_path (str) – A path to use for plugins library dependencies. This value will be added to sys.path if it is not already included.
available[source]

Return a tuple of all available plugins that can be loaded.

disable(name)[source]

Disable a plugin by it’s name. This call the plugins PluginBase.finalize() method to allow it to perform any clean up operations.

Parameters:name (str) – The name of the plugin to disable.
enable(name)[source]

Enable a plugin by it’s name. This will create a new instance of the plugin modules “Plugin” class, passing it the arguments defined in plugin_init_args. A reference to the plugin instance is kept in enabled_plugins. After the instance is created, the plugins initialize() method is called.

Parameters:name (str) – The name of the plugin to enable.
Returns:The newly created instance.
Return type:PluginBase
enabled_plugins = None[source]

A dictionary of the enabled plugins and their respective instances.

get_plugin_path(name)[source]

Get the path at which the plugin data resides. This is either the path to the single plugin file or a folder in the case that the plugin is a module. In either case, the path is an absolute path.

Parameters:name (str) – The name of the plugin to get the path for.
Returns:The path of the plugin data.
Return type:str
install_packages(packages)[source]

This function will take a list of Python packages and attempt to install them through pip to the library_path.

New in version 1.14.0.

Parameters:packages (list) – list of python packages to install using pip.
Returns:The process results from the command execution.
Return type:ProcessResults
library_path = None[source]

The path to a directory which is included for additional libraries. This path must be writable by the current user.

The default value is platform and Python-version (where X.Y is the major and minor versions of Python) dependant:

Linux:~/.local/lib/king-phisher/pythonX.Y/site-packages
Windows:%LOCALAPPDATA%\king-phisher\lib\pythonX.Y\site-packages
load(name, reload_module=False)[source]

Load a plugin into memory, this is effectively the Python equivalent of importing it. A reference to the plugin class is kept in loaded_plugins. If the plugin is already loaded, no changes are made.

Parameters:
  • name (str) – The name of the plugin to load.
  • reload_module (bool) – Reload the module to allow changes to take affect.
Returns:

The plugin class.

load_all(on_error=None)[source]

Load all available plugins. Exceptions while loading specific plugins are ignored. If on_error is specified, it will be called from within the exception handler when a plugin fails to load correctly. It will be called with two parameters, the name of the plugin and the exception instance.

Parameters:on_error (function) – A call back function to call when an error occurs while loading a plugin.
load_module(name, reload_module=False)[source]

Load the module which contains a plugin into memory and return the entire module object.

Parameters:
  • name (str) – The name of the plugin module to load.
  • reload_module (bool) – Reload the module to allow changes to take affect.
Returns:

The plugin module.

loaded_plugins = None[source]

A dictionary of the loaded plugins and their respective modules.

shutdown()[source]

Unload all plugins and perform additional clean up operations.

uninstall(name)[source]

Uninstall a plugin by first unloading it and then delete it’s data on disk. The plugin data on disk is found with the get_plugin_path() method.

Parameters:name (str) – The name of the plugin to uninstall.
Returns:Whether or not the plugin was successfully uninstalled.
Return type:bool
unload(name)[source]

Unload a plugin from memory. If the specified plugin is currently enabled, it will first be disabled before being unloaded. If the plugin is not already loaded, no changes are made.

Parameters:name (str) – The name of the plugin to unload.
unload_all()[source]

Unload all available plugins. Exceptions while unloading specific plugins are ignored.

class Requirements(items)[source]

Bases: collections.abc.Mapping

This object servers to map requirements specified as strings to their respective values. Once the requirements are defined, this class can then be used to evaluate them in an effort to determine which requirements are met and which are not.

__init__(items)[source]
Parameters:items (dict) – A dictionary or two-dimensional array mapping requirement names to their respective values.
compatibility_iter()[source]

Iterate over each of the requirements, evaluate them and yield a tuple regarding them.

is_compatible[source]

Whether or not all requirements are met.

to_dict()[source]

Return a dictionary representing the requirements.