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_calback. 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_errorTrue 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)[source]

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

Parameters

key (str) – The key.

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]

If running, kill the server and cleanup its thread.

Tunnel Manager

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

Bases: object

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

Variables
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

hookee.util.python36_gte()[source]

Check if running on a Python 3.6 or higher interpreter.

Returns

True if Python 3.6 or higher.

Return type

bool