API

Here’s the public API for Henson.

Application

class henson.base.Application(name, settings=None, *, consumer=None, callback=None)[source]

A service application.

Each message received from the consumer will be passed to the callback.

Parameters:
  • name (str) – The name of the application.
  • settings (Optional[object]) – An object with attributed-based settings.
  • consumer (optional) – Any object that is an iterator or an iterable and yields instances of any type that is supported by callback. While this isn’t required, it must be provided before the application can be run.
  • callback (Optional[asyncio.coroutine]) – A callable object that takes two arguments, an instance of henson.base.Application and the (possibly) preprocessed incoming message. While this isn’t required, it must be provided before the application can be run.
error(callback)[source]

Register an error callback.

Parameters:callback (asyncio.coroutine) – A callable object that takes three arguments: an instance of henson.base.Application, the incoming message, and the exception that was raised. It will be called any time there is an exception while reading a message from the queue.
Returns:The callback.
Return type:asyncio.coroutine
Raises:TypeError – If the callback isn’t a coroutine.
message_acknowledgement(callback)[source]

Register a message acknowledgement callback.

Parameters:callback (asyncio.coroutine) – A callable object that takes two arguments: an instance of henson.base.Application and the original incoming message as its only argument. It will be called once a message has been fully processed.
Returns:The callback.
Return type:asyncio.coroutine
Raises:TypeError – If the callback isn’t a coroutine.
message_preprocessor(callback)[source]

Register a message preprocessing callback.

Parameters:callback (asyncio.coroutine) – A callable object that takes two arguments: an instance of henson.base.Application and the incoming message. It will be called for each incoming message with its result being passed to callback.
Returns:The callback.
Return type:asyncio.coroutine
Raises:TypeError – If the callback isn’t a coroutine.
result_postprocessor(callback)[source]

Register a result postprocessing callback.

Parameters:callback (asyncio.coroutine) – A callable object that takes two arguments: an instance of henson.base.Application and a result of processing the incoming message. It will be called for each result returned from callback.
Returns:The callback.
Return type:asyncio.coroutine
Raises:TypeError – If the callback isn’t a coroutine.
run_forever(num_workers=1, loop=None, debug=False)[source]

Consume from the consumer until interrupted.

Parameters:
  • num_workers (Optional[int]) – The number of asynchronous tasks to use to process messages received through the consumer. Defaults to 1.
  • loop (Optional[asyncio.asyncio.BaseEventLoop]) – An event loop that, if provided, will be used for running the application. If none is provided, the default event loop will be used.
  • debug (Optional[bool]) – Whether or not to run with debug mode enabled. Defaults to True.
Raises:

TypeError – If the consumer is None or the callback isn’t a coroutine.

startup(callback)[source]

Register a startup callback.

Parameters:callback (asyncio.coroutine) – A callable object that takes an instance of Application as its only argument. It will be called once when the application first starts up.
Returns:The callback.
Return type:asyncio.coroutine
Raises:TypeError – If the callback isn’t a coroutine.
teardown(callback)[source]

Register a teardown callback.

Parameters:callback (asyncio.coroutine) – A callable object that takes an instance of Application as its only argument. It will be called once when the application is shutting down.
Returns:The callback.
Return type:asyncio.coroutine
Raises:TypeError – If the callback isn’t a coroutine.

Configuration

class henson.config.Config[source]

Custom mapping used to extend and override an app’s settings.

from_mapping(mapping)[source]

Convert a mapping into settings.

Uppercase keys of the specified mapping will be used to extend and update the existing settings.

Parameters:mapping (dict) – A mapping encapsulating settings.
from_object(obj)[source]

Convert an object into settings.

Uppercase attributes of the specified object will be used to extend and update the existing settings.

Parameters:obj – An object encapsulating settings. This will typically be a module or class.

Exceptions

Custom exceptions used by Henson.

exception henson.exceptions.Abort(reason, message)[source]

An exception that signals to Henson to stop processing a message.

When this exception is caught by Henson it will immediately stop processing the message. None of the remaining callbacks will be called.

If the exception is caught while processing a result, that result will no longer be processed. Any other results generated by the same message will still be processed.

Parameters:
  • reason (str) – The reason the message is being aborted. It should be in the form of “noun.verb” (e.g., “provider.ignored”).
  • message – The message that is being aborted. Usually this will be the incoming message, but it can also be the result.

Extensions

class henson.extensions.Extension(app=None)[source]

A base class for Hension extensions.

Parameters:app (Optional[henson.base.Application]) – An application instance that has an attribute named settings that contains a mapping of settings to interact with a database.
DEFAULT_SETTINGS

A dict of default settings for the extension.

When a setting is not specified by the application instance and has a default specified, the default value will be used. Extensions should define this where appropriate. Defaults to {}.

REQUIRED_SETTINGS

An iterable of required settings for the extension.

When an extension has required settings that do not have default values, their keys may be specified here. Upon extension initialization, an exception will be raised if a value is not set for each key specified in this list. Extensions should define this where appropriate. Defaults to ().

app

Return the registered app.

init_app(app)[source]

Initialize the application.

In addition to associating the extension’s default settings with the application, this method will also check for the extension’s required settings.

Parameters:app (henson.base.Application) – An application instance that will be initialized.