Developer Interface

This documentation covers the public interfaces fedora_messaging provides.

Note

Documented interfaces follow Semantic Versioning 2.0.0. Any interface not documented here may change at any time without warning.

Publishing

publish

Subscribing

twisted_consume

Consumer

consume

Signals

Signals sent by fedora_messaging APIs using blinker.base.Signal signals.

pre_publish_signal

publish_signal

publish_failed_signal

Message Schemas

Message

Message Severity

Each message can have a severity associated with it. The severity is used by applications like the notification service to determine what messages to send to users. The severity can be set at the class level, or on a message-by-message basis. The following are valid severity levels:

DEBUG

INFO

WARNING

ERROR

SEVERITIES

dumps

loads

SERIALIZED_MESSAGE_SCHEMA

Utilities

The schema_utils module contains utilities that may be useful when writing the Python API of your message schemas.

libravatar_url

fedora_messaging.schema_utils.libravatar_url(email=None, openid=None, size=64, default='retro')

Get the URL to an avatar from libravatar.

Either the user’s email or openid must be provided.

If you want to use Libravatar federation (through DNS), you should install and use the libravatar library instead. Check out the libravatar.libravatar_url() function.

Parameters

• email (str) – The user’s email

• openid (str) – The user’s OpenID

• size (int) – Size of the avatar in pixels (it’s a square).

• default (str) – Default avatar to return if not found.

Returns

The URL to the avatar image.

Return type

str

Raises

ValueError – If neither email nor openid are provided.

Exceptions

Exceptions raised by Fedora Messaging.

exception fedora_messaging.exceptions.BadDeclaration(obj_type=None, description=None, reason=None)

Raised when declaring an object in AMQP fails.

Parameters

• obj_type (str) – The type of object being declared. One of “binding”, “queue”, or “exchange”.

• description (dict) – The description of the object.

• reason (str) – The reason the server gave for rejecting the declaration.

exception fedora_messaging.exceptions.BaseException

The base class for all exceptions raised by fedora_messaging.

exception fedora_messaging.exceptions.ConfigurationException(message)

Raised when there’s an invalid configuration setting

Parameters

message (str) – A detailed description of the configuration problem which is presented to the user.

exception fedora_messaging.exceptions.ConnectionException(*args, **kwargs)

Raised if a general connection error occurred.

You may handle this exception by logging it and resending or discarding the message.

exception fedora_messaging.exceptions.ConsumeException

Base class for exceptions related to consuming.

exception fedora_messaging.exceptions.ConsumerCanceled

Raised when the server has canceled the consumer.

This can happen when the queue the consumer is subscribed to is deleted, or when the node the queue is located on fails.

exception fedora_messaging.exceptions.Drop

Consumer callbacks should raise this to indicate they wish the message they are currently processing to be dropped.

exception fedora_messaging.exceptions.HaltConsumer(exit_code=0, reason=None, requeue=False, **kwargs)

Consumer callbacks should raise this exception if they wish the consumer to be shut down.

Parameters

• exit_code (int) – The exit code to use when halting.

• reason (str) – A reason for halting, presented to the user.

• requeue (bool) – If true, the message is re-queued for later processing.

exception fedora_messaging.exceptions.Nack

Consumer callbacks should raise this to indicate they wish the message they are currently processing to be re-queued.

exception fedora_messaging.exceptions.NoFreeChannels

Raised when a connection has reached its channel limit

exception fedora_messaging.exceptions.PermissionException(obj_type=None, description=None, reason=None)

Generic permissions exception.

Parameters

• obj_type (str) – The type of object being accessed that caused the permission error. May be None if the cause is unknown.

• description (object) – The description of the object, if any. May be None.

• reason (str) – The reason the server gave for the permission error, if any. If no reason is supplied by the server, this should be the best guess for what caused the error.

exception fedora_messaging.exceptions.PublishException(reason=None, **kwargs)

Base class for exceptions related to publishing.

exception fedora_messaging.exceptions.PublishForbidden(reason=None, **kwargs)

Raised when the broker rejects the message due to permission errors.

You may handle this exception by logging it and discarding the message, as it is likely a permanent error.

exception fedora_messaging.exceptions.PublishReturned(reason=None, **kwargs)

Raised when the broker rejects and returns the message to the publisher.

You may handle this exception by logging it and resending or discarding the message.

exception fedora_messaging.exceptions.PublishTimeout(reason=None, **kwargs)

Raised when the message could not be published in the given timeout.

This means the message was either never delivered to the broker, or that it was delivered, but never acknowledged by the broker.

exception fedora_messaging.exceptions.ValidationError

This error is raised when a message fails validation with its JSON schema

This exception can be raised on an incoming or outgoing message. No need to catch this exception when publishing, it should warn you during development and testing that you’re trying to publish a message with a different format, and that you should either fix it or update the schema.

Configuration

conf

DEFAULTS