Usage Guide¶
Callbacks¶
Callbacks are simple python functions that accept a single argument of type hedwig.models.Message
-
def send_email(message: hedwig.models.Message) -> None:
# send email
You can access the data dict using message.data
as well as custom headers using message.headers
and other
metadata fields as described in the API docs: hedwig.models.Message()
.
Publisher¶
You can run publish messages like so:
models.Message.new("message.type", StrictVersion('1.0'), data).publish()
If you want to include a custom headers with the message (for example, you can include a request_id
field for
cross-application tracing), you can pass in additional parameter headers
.
Consumer¶
A consumer for AWS SQS/Google PubSub based workers can be started as following:
consumer.listen_for_messages()
This is a blocking function. Don’t use threads since this library is NOT guaranteed to be thread-safe.
A consumer for Lambda based workers can be started as following:
consumer.process_messages_for_lambda_consumer(lambda_event)
where lambda_event
is the event provided by AWS to your Lambda function as described in lambda sns format.
Schema¶
JSON-Schema¶
The schema file must be a JSON-Schema draft v4 schema. There’s a few more restrictions in addition to being a valid schema:
There must be a top-level key called
schemas
. The value must be an object.schemas
: The keys of this object must be message types. The value must be an object.schemas/<message_type>
: The keys of this object must be major version patterns for this message type. The value must be an object.schemas/<message_type>/<major_version>.*
: This object must represent the data schema for given message type, and major version. Any minor version updates must be applied in-place, and must be non-breaking per semantic versioning.
Note that the schema file only contains definitions for major versions. This is by design since minor version MUST be backwards compatible.
Optionally, a key x-versions
may be used to list full versions under a major version.
For an example, see example jsonschema schema.
Protobuf¶
The proto file must be a proto3 schema and must be pre-compiled by the application. There’s a few more restrictions in addition to being a valid schema:
<message_type>V<major_version>
: For every message type and every major version for that message type, a protobuf message with this name must be defined.Every protobuf message must include options
(hedwig.message_options).major_version
and(hedwig.message_options).minor_version
.Multiple protobuf files for organizing the schemas is fine, but the final compiled version must be present as a single python module.
Note that the schema file only contains definitions for major versions. This is by design since minor version MUST be backwards compatible.
For an example, see example protobuf schema.
Testing¶
Hedwig supports pytest by default and provides pytest testing utilities as part of the
hedwig.testing.pytest_plugin
module.