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 ofhookee
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 (seehookee --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 rawresponse
andcontent-type
(or needing to use plugins) when integrating withhookee
: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.
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.
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 asetup(hookee_manager)
method.
-
static
build_from_file
(path)[source]¶ Import a Python script at the given path, then import it as a
hookee
plugin.
-
static
build_from_module
(module)[source]¶ Validate and build a
hookee
plugin for the given module. If the module is not a validhookee
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
-
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’sresponse_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.
-
get_plugin
(plugin_name, throw_error=False)[source]¶ Get the given plugin name from modules parsed by
source_plugins
.
-
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
-
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
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 askwargs
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
andcontent-type
(or needing to use plugins) when integrating withhookee
’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
ifclick
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 aclick.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
.
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
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.
Utility¶
-
class
hookee.util.
PrintUtil
(config)[source]¶ Bases:
object
An object that provides helper methods for logging output. If
Config
’sclick_logging
isTrue
(which will happen by default if aclick.Context
is found to be active), this logging will be done throughclick
, otherwise thehookee
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 thehookee
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
, ifclick_logging
is enabled inConfig
, or appended to the logger.- Parameters
-
print_close_header
(delimiter='-', color=None, blank_line=True)[source]¶ Log a closing header with an optional new line before.
-
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