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
[Any
]) – An object with attributed-based settings.consumer (
Optional
[Consumer
]) – Any object that is an iterator or an iterable and yields instances of any type that is supported bycallback
. While this isn’t required, it must be provided before the application can be run.callback (
Optional
[Callable
[…,Awaitable
]]) – A callable object that takes two arguments, an instance ofdoozer.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 (
Callable
[…,Awaitable
]) – A callable object that takes three arguments: an instance ofdoozer.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.- Return type
- Returns
The callback.
- Raises
TypeError – If the callback isn’t a coroutine.
-
message_acknowledgement
(callback)[source]¶ Register a message acknowledgement callback.
- Parameters
callback (
Callable
[…,Awaitable
]) – A callable object that takes two arguments: an instance ofdoozer.base.Application
and the original incoming message as its only argument. It will be called once a message has been fully processed.- Return type
- Returns
The callback.
- Raises
TypeError – If the callback isn’t a coroutine.
-
message_preprocessor
(callback)[source]¶ Register a message preprocessing callback.
- Parameters
callback (
Callable
[…,Awaitable
]) – A callable object that takes two arguments: an instance ofdoozer.base.Application
and the incoming message. It will be called for each incoming message with its result being passed tocallback
.- Return type
- Returns
The callback.
- Raises
TypeError – If the callback isn’t a coroutine.
-
result_postprocessor
(callback)[source]¶ Register a result postprocessing callback.
- Parameters
callback (
Callable
[…,Awaitable
]) – A callable object that takes two arguments: an instance ofdoozer.base.Application
and a result of processing the incoming message. It will be called for each result returned fromcallback
.- Return type
- Returns
The callback.
- 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 (
int
) – The number of asynchronous tasks to use to process messages received through the consumer. Defaults to 1.loop (
Optional
[AbstractEventLoop
]) – 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 (
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.
- Return type
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 (
Sequence
[Callable
]) – A list of callables that are used to create subcommands. More details can be found in the documentation foradd_commands()
.
Note
This function is a wrapper around
add_commands()
. Please refer to its documentation for any arguments not explained here.- Return type
Configuration¶
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.
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.
-
property
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
{}
.- Return type
-
property
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
()
.- Return type
-
property
app
¶ Return the registered app.
- Return type
-
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 (
Application
) – An application instance that will be initialized.- Return type