API reference

hedwig.consumer.listen_for_messages(num_messages=10, visibility_timeout_s=None, loop_count=None, shutdown_event=None)

Starts a Hedwig listener for message types provided and calls the callback handlers like so:

callback_fn(message).

The message is explicitly deleted only if callback function ran successfully. In case of an exception the message is kept on queue and processed again. If the callback keeps failing, SQS dead letter queue mechanism kicks in and the message is moved to the dead-letter queue.

This function is blocking by default. It may be run for specific number of loops by passing loop_count. It may also be stopped by passing a shut down event object which can be set to stop the function.

Parameters:

• num_messages (int) – Maximum number of messages to fetch in one SQS API call. Defaults to 10
• visibility_timeout_s (Optional[int]) – The number of seconds the message should remain invisible to other queue readers. Defaults to None, which is queue default
• loop_count (Optional[int]) – How many times to fetch messages from SQS. Default to None, which means loop forever.
• shutdown_event (Optional[Event]) – An event to signal that the process should shut down. This prevents more messages from being de-queued and function exits after the current messages have been processed.

Return type:

None

hedwig.consumer.process_messages_for_lambda_consumer(lambda_event)

Return type:None

class hedwig.models.Message(data)

Model for Hedwig messages. All properties of a message should be considered immutable. A Message object will always have known message format schema and message format schema version even if the data _may_ not be valid.

validate()

Validates a message using JSON schema.

Raise:hedwig.ValidationError if validation fails. Return type:None

classmethod new(msg_type, data_schema_version, data, msg_id=None, headers=None)

Creates Message object given type, data schema version and data. This is typically used by the publisher code.

Parameters:

• msg_type (MessageType) – MessageType instance
• data_schema_version (StrictVersion) – StrictVersion representing data schema
• data (dict) – The dict to pass in data field of Message.
• msg_id (Optional[str]) – Custom message identifier. If not passed, a randomly generated uuid will be used.
• headers (Optional[dict]) – Custom headers

Return type:

Message

publish()

Publish this message on Hedwig infra

extend_visibility_timeout(visibility_timeout_s)

Extends visibility timeout of a message for long running tasks.

Return type:None

data_schema_version

StrictVersion object representing data schema version. May be None if message can’t be validated.

Return type:StrictVersion

id

Message identifier

Return type:str

schema

Message schema

Return type:str

type

MessageType. May be none if message is invalid

Return type:MessageType

format_version

Message format version (this is different from data schema version)

Return type:StrictVersion

metadata

Message metadata

Return type:Metadata

timestamp

Timestamp of message creation in epoch milliseconds

Return type:int

headers

Custom headers sent with the message

Return type:dict

receipt

SQS receipt for the task. This may be used to extend message visibility if the task is running longer than expected using Message.extend_visibility_timeout()

Return type:Optional[str]

publisher

Publisher of message

Return type:Optional[str]

data

Message data

Return type:dict

topic

The SNS topic name for routing the message

Return type:str

class hedwig.models.Metadata(data)

timestamp

Timestamp of message creation in epoch milliseconds

Return type:int

publisher

Publisher of message

Return type:str

receipt

SQS receipt for the task. This may be used to extend message visibility if the task is running longer than expected using Message.extend_visibility_timeout()

Return type:Optional[str]

headers

Custom headers sent with the message

Return type:dict

class hedwig.models.MessageType

Enumeration representing the message types supported for this service. This is automatically created based on setting HEDWIG_MESSAGE_ROUTING

class hedwig.validator.MessageValidator(schema=None)

checker = <jsonschema._format.FormatChecker object>

FormatChecker that checks for format JSON-schema field. This may be customized by an app by overriding setting HEDWIG_DATA_VALIDATOR_CLASS and defining more format checkers.

validate(message)

Validates a message using JSON Schema

Return type:None

hedwig.commands.requeue_dead_letter(num_messages=10, visibility_timeout=None)

Re-queues everything in the Hedwig DLQ back into the Hedwig queue.

Parameters:

• num_messages (int) – Maximum number of messages to fetch in one SQS call. Defaults to 10.
• visibility_timeout (Optional[int]) – The number of seconds the message should remain invisible to other queue readers. Defaults to None, which is queue default

Return type:

None

Testing

hedwig.testing.pytest_plugin.mock_hedwig_publish()

A pytest fixture that mocks Hedwig publisher and lets you verify that your test publishes appropriate messages.

Return type:Generator[HedwigPublishMock, None, None]

class hedwig.testing.pytest_plugin.HedwigPublishMock(*args, **kw)

Custom mock class used by hedwig.testing.pytest_plugin.mock_hedwig_publish() to mock the publisher.

assert_message_not_published(msg_type, data=None, version=StrictVersion ('1.0'))

Helper function to check that a Hedwig message of given type, data and schema was NOT sent.

Return type:None

assert_message_published(msg_type, data=None, version=StrictVersion ('1.0'))

Helper function to check if a Hedwig message with given type, data and schema version was sent.

Return type:None

Exceptions

class hedwig.exceptions.RetryException(*args, **kwargs)

Special exception that does not log an exception when it is received. This is a retryable error.

class hedwig.exceptions.IgnoreException

Indicates that this task should be ignored.

class hedwig.exceptions.ValidationError

Message failed JSON schema validation

class hedwig.exceptions.ConfigurationError

There was some problem with settings

class hedwig.exceptions.CallbackNotFound

No callback found that can handle the given message. Check your CALLBACKS settings.