API Documentation — hookee 2.0.0 documentation
Description: Command line webhooks, on demand! Dump request data to the console, customize responses, configurable in any number of ways through plugins.

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

  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)

    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`()

    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`()

    If running, shutdown the managed server and tunnel.

## Plugin Manager

class `hookee.pluginmanager.` `Plugin`(module, plugin_type, name, has_setup, description=None)

  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)

    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)

    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)

    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)

    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)

  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`()

    Get a sorted list of available plugins.

    Returns

      The list of available plugins.

    Return type

      list[str]

  `enabled_plugins`()

    Get a list of enabled plugins.

    Returns

      The list of enabled plugins.

    Return type

      list[str]

  `get_plugin`(plugin_name, throw_error=False)

    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)

    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`()

    Load and validate all built-in plugins and custom plugins from sources in the plugin base.

  `run_request_plugins`(request)

    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)

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

  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)

    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)

    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)

    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)

    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)

  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`()

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

    Returns

      The status code.

    Return type

      http.HTTPStatus

  `create_app`()

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

    Returns

      The Flask app.

    Return type

      flask.Flask

  `start`()

    If one is not already running, start a server in a new thread.

  `stop`()

    If running, kill the server and cleanup its thread.

## Tunnel Manager

class `hookee.tunnel.` `Tunnel`(hookee_manager)

  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`()

    If one is not already running, start a tunnel in a new thread.

  `stop`()

    If running, kill the tunnel and cleanup its thread.

## Utility

class `hookee.util.` `PrintUtil`(config)

  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)

    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)

    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)

    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)

    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)

    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)

  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)

  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)

  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`()

  Check if running on a Python 3.6 or higher interpreter.

  Returns

    `True` if Python 3.6 or higher.

  Return type

    bool