API¶
Here’s the public API for Doozer.
Application¶
-
class
doozer.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
doozer.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 doozer.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 doozer.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 doozer.base.Application
and the incoming message. It will be called for each incoming message with its result being passed tocallback
.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 doozer.base.Application
and a result of processing the incoming message. It will be called for each result returned fromcallback
.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.Changed in version 1.2: Unhandled exceptions resulting from processing a message while the consumer is still active will stop cause the application to shut down gracefully.
-
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.
Command Line Interface¶
Collection of Doozer CLI tasks.
-
doozer.cli.
register_commands
(namespace, functions, namespace_kwargs=None, func_kwargs=None)[source]¶ Register commands with the doozer CLI.
The signature of each function provided through
functions
will be mapped to its command’s interface. Any positional arguments in the function’s signature will become required positional arguments to the command. Keyword arguments in the signature will also become positional arguments, although they will use the default value from the signature when not specified on the command line. Keyword-only arguments in the signature will become optional arguments on the command line.Parameters: - namespace (str) – A name representing the group of commands. The namespace is required to access the commands being added.
- functions (List[callable]) – A list of callables that are used to
create subcommands. More details can be found in the
documentation for
add_commands()
.
Note
This function is a wrapper around
add_commands()
. Please refer to its documentation for any arguments not explained here.New in version 1.1.0.
Configuration¶
-
class
doozer.config.
Config
[source]¶ Custom mapping used to extend and override an app’s settings.
Exceptions¶
Custom exceptions used by Doozer.
-
exception
doozer.exceptions.
Abort
(reason, message)[source]¶ An exception that signals to Doozer to stop processing a message.
When this exception is caught by Doozer 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
doozer.extensions.
Extension
(app=None)[source]¶ A base class for Hension extensions.
Parameters: app (Optional[doozer.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 (doozer.base.Application) – An application instance that will be initialized.
-