API Documentation¶

This part of the documentation covers the interfaces used to develop with hookee.

`hookee` Manager¶

class hookee.hookeemanager.HookeeManager(config=None, load_plugins=True)[source]¶

Bases: object

An object that manages the state of a hookee runtime. Reads app configuration, loads enabled plugins, and manages the long-lived state of hookee if a server and tunnel are started.

If instantiating for a custom integration, pass a Config with args that otherwise would have been passed to the CLI (see hookee --help). For example:

from hookee import HookeeManager
from hookee.conf import Config

config = Config(subdomain="my_domain",
                region="eu")
hookee_manager = HookeeManager(config=config)

A response_callback function can also be passed instead of defining a raw response and content-type (or needing to use plugins) when integrating with hookee:

from hookee import HookeeManager
from hookee.conf import Config

def response_callback(request, response):
    response.data = "<Response>Ok</Response>"
    response.headers["Content-Type"] = "application/xml"
    return response

config = Config(response_callback=response_callback)
hookee_manager = HookeeManager(config=config)

Variables:

ctx (click.Context) – The click context.
config (Config) – The hookee configuration.
plugin_manager (PluginManager) – Reference to the Plugin Manager.
print_util (PrintUtil) – Reference to the PrintUtil.
tunnel (Tunnel) – Reference to the Tunnel.
server (Server) – Reference to the Server.
alive (bool) – True when this object is managing an active tunnel and server.

fail(msg, e=None)[source]¶

Shutdown the current application with a failure. If a CLI Context exists, that will be used to invoke the failure, otherwise an exception will be thrown for failures to be caught.

Parameters:

msg (str) – The failure message.
e (HookeeError, optional) – The error being raised.

run()[source]¶: If one is not already running, start a managed server and tunnel and block until an interrupt is received (or alive is set to False).

stop()[source]¶: If running, shutdown the managed server and tunnel.

Plugin Manager¶

class hookee.pluginmanager.Plugin(module, plugin_type, name, has_setup, description=None)[source]¶

Bases: object

An object that represents a validated and loaded hookee plugin.

Variables:

module (types.ModuleType) – The underlying plugin module.
plugin_type (str) – The type of plugin.
name (str, optional) – The name of the plugin.
name – The description of the plugin.
has_setup (bool) – True if the plugin has a setup(hookee_manager) method.

static build_from_file(path)[source]¶

Import a Python script at the given path, then import it as a hookee plugin.

Parameters:: path (str) – The path to the script to import.
Returns:: The imported script as a plugin.
Return type:: Plugin

static build_from_module(module)[source]¶

Validate and build a hookee plugin for the given module. If the module is not a valid hookee plugin, an exception will be thrown.

Parameters:: module (types.ModuleType) – The module to validate as a valid plugin.
Returns:: An object representing the validated plugin.
Return type:: Plugin

run(*args)[source]¶

Passes through to the underlying module’s run(*args).

Parameters:: args (tuple) – The args to pass through.
Returns:: The value returned by the module’s function (or nothing if the module’s function returns nothing).
Return type:: object

setup(*args)[source]¶

Passes through to the underlying module’s setup(*args), if it exists.

Parameters:: args (tuple) – The args to pass through.
Returns:: The value returned by the module’s function (or nothing if the module’s function returns nothing).
Return type:: object

class hookee.pluginmanager.PluginManager(hookee_manager)[source]¶

Bases: object

An object that loads, validates, and manages available plugins.

Variables:

hookee_manager (HookeeManager) – Reference to the hookee Manager.
config (Config) – The hookee configuration.
source (pluginbase.PluginSource) – The hookee configuration.
request_script (Plugin) – A request plugin loaded from the script at --request_script, run last.
response_script (Plugin) – A response plugin loaded from the script at --response_script, run last.
response_callback – The response body loaded from either --response, or the lambda defined in the config’s response_callback. Overrides any body data from response plugins.
builtin_plugins_dir (str) – The directory where built-in plugins reside.
loaded_plugins (list[Plugin]) – A list of plugins that have been validated and imported.

available_plugins()[source]¶

Get a sorted list of available plugins.

Returns:: The list of available plugins.
Return type:: list[str]

enabled_plugins()[source]¶

Get a list of enabled plugins.

Returns:: The list of enabled plugins.
Return type:: list[str]

get_plugin(plugin_name, throw_error=False)[source]¶

Get the given plugin name from modules parsed by source_plugins.

Parameters:

plugin_name (str) – The name of the plugin to load.
throw_error – True if errors encountered should be thrown to the caller, False if fail should be called.

Returns:

The loaded plugin.

Return type:

Plugin

get_plugins_by_type(plugin_type)[source]¶

Get loaded plugins by the given plugin type.

Parameters:: plugin_type (str) – The plugin type for filtering.
Returns:: The filtered list of plugins.
Return type:: list[Plugin]

load_plugins()[source]¶: Load and validate all built-in plugins and custom plugins from sources in the plugin base.

run_request_plugins(request)[source]¶

Run all enabled request plugins.

Parameters:: request (flask.Request) – The request object being processed.
Returns:: The processed request.
Return type:: flask.Request

run_response_plugins(request=None, response=None)[source]¶

Run all enabled response plugins, running the response_info plugin (if enabled) last.

Parameters:

request (flask.Request, optional) – The request object being processed.
response (flask.Response, optional) – The response object being processed.

Returns:

The processed response.

Return type:

flask.Response

source_plugins()[source]¶: Source all paths to look for plugins (defined in the config) to prepare them for loading and validation.

Configuration¶

class hookee.conf.Config(click_logging=None, **kwargs)[source]¶

Bases: object

An object with accessor methods containing hookee’s configuration. Default configuration can be overridden by creating a custom config at ~/.config/hookee/config.yaml (when setting config values from the command line, this is where updated values are stored) which in turn can be overridden by passing args to the CLI.

If instantiating for a custom integration, args that would otherwise have been passed to and validated by the CLI (see hookee --help) can instead be passed as kwargs here to ensure the same validation is done. For example:

from hookee.conf import Config

config = Config(subdomain="my_domain",
                region="eu")

A callback function can also be passed instead of response and content-type (or needing to use plugins) when integrating with hookee’s APIs:

from hookee.conf import Config

def response_callback(request, response):
    response.data = "<Response>Ok</Response>"
    response.headers["Content-Type"] = "application/xml"
    return response

config = Config(response_callback=response_callback)

Variables:

config_obj (confuse.core.Configuration) – The templated config object.
config_dir (str) – The directory of the config being used.
config_path (str) – The full path to the config file being used.
config_data (confuse.templates.AttrDict) – The parsed and validated config data. Use get, set, and other accessors to interact with the data.
click_logging (bool) – True if click should be used for log output, which enables colors and formatting when logging to a console, False if a logger should be used. If not passed, True if a click.Context is found to be active. Not persisted to the config file.
response_callback (types.FunctionType, optional) – The response callback function, if defined. Not persisted to the config file.

append(key, value)[source]¶

Update the config key by appending to the list the given value, persisting to config.yaml.

Parameters:

key (str) – The key.
value (object) – The value to append.

get(key, default=None)[source]¶

Get the config value for the given key of persisted data.

Parameters:

key (str) – The key.
default – The default, if config not set.

Returns:

The config value.

Return type:

object

remove(key, value)[source]¶

Update the config key by removing from the list the given value from the list for the given key, persisting to config.yaml.

Parameters:

key (str) – The key.
value (object) – The value to remove.

set(key, value)[source]¶

Update the config key to the given value, persisting to config.yaml.

Parameters:

key (object) – The key.
value – The value to set.

Server Manager¶

class hookee.server.Server(hookee_manager)[source]¶

Bases: object

An object that manages a non-blocking Flask server and thread.

Variables:

hookee_manager (HookeeManager) – Reference to the hookee Manager.
plugin_manager (PluginManager) – Reference to the Plugin Manager.
print_util (PrintUtil) – Reference to the PrintUtil.
port (int) – The server’s port.
app (flask.Flask) – The Flask app.

_server_status()[source]¶

Get the response code of the server’s /status endpoint.

Returns:: The status code.
Return type:: http.HTTPStatus

create_app()[source]¶

Create a Flask app and register all Blueprints found in enabled plugins.

Returns:: The Flask app.
Return type:: flask.Flask

start()[source]¶: If one is not already running, start a server in a new thread.

stop()[source]¶: This method is only useful when the Flask version has been overriden to use asn older version (<2). With recent versions of Flask, the underlying server daemon will terminate when ``hookee` terminates.

Tunnel Manager¶

class hookee.tunnel.Tunnel(hookee_manager)[source]¶

Bases: object

An object that manages a non-blocking pyngrok tunnel and thread.

Variables:

hookee_manager (HookeeManager) – Reference to the hookee Manager.
plugin_manager (PluginManager) – Reference to the Plugin Manager.
print_util (PrintUtil) – Reference to the PrintUtil.
port (int) – The server’s port.
pyngrok_config (pyngrok.conf.PyngrokConfig) – The pyngrok config.
public_url (str) – The public URL of the tunnel.
ngrok_process (pyngrok.process.NgrokProcess) – The ngrok process.

start()[source]¶: If one is not already running, start a tunnel in a new thread.

stop()[source]¶: If running, kill the tunnel and cleanup its thread.

Utility¶

class hookee.util.PrintUtil(config)[source]¶

Bases: object

An object that provides helper methods for logging output. If Config’s click_logging is True (which will happen by default if a click.Context is found to be active), this logging will be done through click, otherwise the hookee logger will be used.

If click_logging is disabled, output sent through this utility can still be interacted with by ensuring the a logger is setup. For example, this would add a handler to the hookee logger that just logs output back to the console:

import logging

logger = logging.getLogger("hookee")
logger.setLevel(logging.INFO)
logging.getLogger().addHandler(logging.StreamHandler())

Variables:: config (Config) – The hookee configuration.

print_basic(msg='', color=None, bold=False, print_when_logging=False)[source]¶

Log a basic message. The message will be logged via click, if click_logging is enabled in Config, or appended to the logger.

Parameters:

msg (str, optional) – The update to print.
color (str, optional) – The color to make the text.
bold (bool, optional) – True if the output should be bold.
print_when_logging (bool, optional) – True if, when click_logging is False, msg should print to the console instead of appending to the logger.

print_close_header(delimiter='-', color=None, blank_line=True)[source]¶

Log a closing header with an optional new line before.

Parameters:

delimiter (str) – The title of the XML blob.
color (str, optional) – The color to make the text.
blank_line (bool) – True if a blank line should precede the closing header.

print_dict(title, data, color=None)[source]¶

Log formatted dictionary data.

Parameters:

title (str) – The title of the XML blob.
data (dict) – A dictionary.
color (str, optional) – The color to make the text.

print_open_header(title, delimiter='-', color=None)[source]¶

Log an opening header with a title and a new line before and after.

Parameters:

title (str) – The header title.
delimiter (str, optional) – The title of the XML blob.
color (str, optional) – The color to make the text.

print_xml(title, data, color=None)[source]¶

Log formatted XML.

Parameters:

title (str) – The title of the XML blob.
data (str) – An XML string.
color (str, optional) – The color to make the text.

hookee.util.get_args(func)[source]¶

Get a list of args for the given function.

Parameters:: func (types.FunctionType) – The function to inspect for args.
Returns:: The list of args.
Return type:: list[str]

hookee.util.get_functions(mod)[source]¶

Get a list of functions for the given module.

Parameters:: mod (types.ModuleType) – The module to inspect for functions.
Returns:: The list of functions.
Return type:: list[types.FunctionType]

hookee.util.get_module_name(module)[source]¶

Get the name of the module from the basename of its path.

Parameters:: module (types.ModuleType) – The module.
Returns:: The base name of the module.
Return type:: str

API Documentation¶

`hookee` Manager¶

Plugin Manager¶

Configuration¶

Server Manager¶

Tunnel Manager¶

Utility¶

Getting Around

Table of Contents

Useful Links

API Documentation¶

hookee Manager¶

Plugin Manager¶

Configuration¶

Server Manager¶

Tunnel Manager¶

Utility¶

`hookee` Manager¶