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¶
-
fedora_messaging.api.
publish
(message, exchange=None)[source]¶ Publish a message to an exchange.
This is a synchronous call, meaning that when this function returns, an acknowledgment has been received from the message broker and you can be certain the message was published successfully.
There are some cases where an error occurs despite your message being successfully published. For example, if a network partition occurs after the message is received by the broker. Therefore, you may publish duplicate messages. For complete details, see the Publishing documentation.
>>> from fedora_messaging import api >>> message = api.Message(body={'Hello': 'world'}, topic='Hi') >>> api.publish(message)
If an attempt to publish fails because the broker rejects the message, it is not retried. Connection attempts to the broker can be configured using the “connection_attempts” and “retry_delay” options in the broker URL. See
pika.connection.URLParameters
for details.Parameters: - message (message.Message) – The message to publish.
- exchange (str) – The name of the AMQP exchange to publish to; defaults to publish_exchange
Raises: fedora_messaging.exceptions.PublishReturned
– Raised if the broker rejects the message.fedora_messaging.exceptions.ConnectionException
– Raised if a connection error occurred before the publish confirmation arrived.fedora_messaging.exceptions.ValidationError
– Raised if the message fails validation with its JSON schema. This only depends on the message you are trying to send, the AMQP server is not involved.
Subscribing¶
-
fedora_messaging.api.
consume
(callback, bindings=None)[source]¶ Start a message consumer that executes the provided callback when messages are received.
This API is blocking and will not return until the process receives a signal from the operating system.
The callback receives a single positional argument, the message:
>>> from fedora_messaging import api >>> def my_callback(message): ... print(message) >>> bindings = [{'exchange': 'amq.topic', 'queue': 'demo', 'routing_keys': ['#']}] >>> api.consume(my_callback, bindings=bindings)
For complete documentation on writing consumers, see the Consumers documentation.
Parameters: - callback (callable) – A callable object that accepts one positional argument,
a
Message
. - bindings (dict or list of dict) – The bindings to use when consuming. This should be the same format as the bindings configuration.
Raises: fedora_messaging.exceptions.HaltConsumer
– If the consumer requests that it be stopped.ValueError
– If the consumer provide callback that is not a class that implements __call__ and is not a function.
- callback (callable) – A callable object that accepts one positional argument,
a
Signals¶
Signals sent by fedora_messaging APIs using blinker.base.Signal
signals.
-
fedora_messaging.api.
pre_publish_signal
= <blinker.base.NamedSignal object at 0x7f258b1a8940; 'pre_publish'>¶ A signal triggered before the message is published. The signal handler should accept a single keyword argument,
message
, which is the instance of thefedora_messaging.message.Message
being sent. It is acceptable to mutate the message, but thevalidate
method will be called on it after this signal.
-
fedora_messaging.api.
publish_signal
= <blinker.base.NamedSignal object at 0x7f258a71df28; 'publish_success'>¶ A signal triggered after a message is published successfully. The signal handler should accept a single keyword argument,
message
, which is the instance of thefedora_messaging.message.Message
that was sent.
-
fedora_messaging.api.
publish_failed_signal
= <blinker.base.NamedSignal object at 0x7f258a71de80; 'publish_failed_signal'>¶ A signal triggered after a message fails to publish for some reason. The signal handler should accept two keyword argument,
message
, which is the instance of thefedora_messaging.message.Message
that failed to be sent, anderror
, the exception that was raised.
Message Schemas¶
This module defines the base class of message objects and keeps a registry of
known message implementations. This registry is populated from Python entry
points. The registry keys are Python paths and the values are sub-classes of
Message
.
When publishing, the API will add a header with the schema used so the consumer can locate the correct schema.
To implement your own message schema, simply create a class that inherits the
Message
class, and add an entry point in your Python package under the
“fedora.messages” group. For example, an entry point for the Message
schema would be:
entry_points = {
'fedora.messages': ['base.message=fedora_messaging.message:Message']
}
Since every client needs to have the message schema installed, you should define this class in a small Python package of its own. Note that at this time, the entry point name is unused.
-
class
fedora_messaging.message.
Message
(body=None, headers=None, topic=None, properties=None, severity=None)[source]¶ Messages are simply JSON-encoded objects. This allows message authors to define a schema and implement Python methods to abstract the raw message from the user. This allows the schema to change and evolve without breaking the user-facing API.
A message class includes a topic. This topic is used by message consumers to filter what messages they receive. Topics should be a string of words separated by ‘.’ characters, with a length limit of 255 bytes. Because of this limit, it is best to avoid non-ASCII characters as well as variable-length components where the total size of the topic would exceed 255 bytes.
-
id
¶ six.text_type – The message id as a unicode string.
-
topic
¶ six.text_type – The message topic as a unicode string.
-
headers_schema
¶ dict – A JSON schema to be used with
jsonschema.validate()
to validate the message headers.
-
body_schema
¶ dict – A JSON schema to be used with
jsonschema.validate()
to validate the message headers.
-
severity
¶ int – An integer that indicates the severity of the message. This is used to determine what messages to notify end users about and should be
DEBUG
,INFO
,WARNING
, orERROR
.
Parameters: - headers (dict) – A set of message headers. Consult the headers schema for expected keys and values.
- body (dict) – The message body. Consult the body schema for expected keys and values.
- topic (six.text_type) – The message topic as a unicode string. If this is not provided, the default topic for the class is used.
- properties (pika.BasicProperties) – The AMQP properties. If this is not provided, they will be generated.
-
agent_avatar
¶ An URL to the avatar of the user who caused the action.
Returns: The URL to the user’s avatar. Return type: str or None
-
app_icon
¶ An URL to the icon of the application that generated the message.
Returns: The URL to the app’s icon. Return type: str or None
-
packages
¶ List of packages affected by the action that generated this message.
Returns: A list of affected package names. Return type: list(str)
-
summary
¶ A short, human-readable representation of this message.
This should provide a short summary of the message, much like the subject line of an email.
The default implementation is to simply return the message topic.
-
url
¶ An URL to the action that caused this message to be emitted.
Returns: A relevant URL. Return type: str or None
-
usernames
¶ List of users affected by the action that generated this message.
Returns: A list of affected usernames. Return type: list(str)
-
validate
()[source]¶ Validate the headers and body with the message schema, if any.
In addition to the user-provided schema, all messages are checked against the base schema which requires certain message headers and the that body be a JSON object.
Warning
This method should not be overridden by sub-classes.
Raises: jsonschema.ValidationError
– If either the message headers or the message body are invalid.jsonschema.SchemaError
– If either the message header schema or the message body schema are invalid.
-
-
fedora_messaging.message.
get_class
(schema_name)[source]¶ Retrieve the message class associated with the schema name.
If no match is found, the default schema is returned and a warning is logged.
Parameters: schema_name (six.text_type) – The name of the Message
sub-class; this is typically the Python path.Returns: A sub-class of Message
to create the message from.Return type: 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:
-
fedora_messaging.message.
DEBUG
= 10¶ Indicates the message is for debugging or is otherwise very low priority. Users will not be notified unless they’ve explicitly requested DEBUG level messages.
-
fedora_messaging.message.
INFO
= 20¶ Indicates the message is informational. End users will not receive notifications for these messages by default. For example, automated tests passed for their package.
-
fedora_messaging.message.
WARNING
= 30¶ Indicates a problem or an otherwise important problem. Users are notified of these messages when they pertain to packages they are associated with by default. For example, one or more automated tests failed against their package.
-
fedora_messaging.message.
ERROR
= 40¶ Indicates a critically important message that users should act upon as soon as possible. For example, their package no longer builds.
Exceptions¶
Exceptions raised by Fedora Messaging.
-
exception
fedora_messaging.exceptions.
BaseException
[source]¶ The base class for all exceptions raised by fedora_messaging.
-
exception
fedora_messaging.exceptions.
ConfigurationException
(message)[source]¶ 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
(reason=None, **kwargs)[source]¶ 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
[source]¶ Base class for exceptions related to consuming.
-
exception
fedora_messaging.exceptions.
Drop
[source]¶ 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)[source]¶ 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
[source]¶ Consumer callbacks should raise this to indicate they wish the message they are currently processing to be re-queued.
-
exception
fedora_messaging.exceptions.
PublishException
(reason=None, **kwargs)[source]¶ Base class for exceptions related to publishing.
-
exception
fedora_messaging.exceptions.
PublishReturned
(reason=None, **kwargs)[source]¶ 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.
ValidationError
[source]¶ 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.
Twisted¶
Protocol¶
Twisted Protocol based on pika’s Twisted Protocol, and implementing the specificities of Fedora Messaging.
See https://twistedmatrix.com/documents/current/core/howto/clients.html#protocol
-
class
fedora_messaging.twisted.protocol.
FedoraMessagingProtocol
(parameters, confirms=True)[source]¶ A Twisted Protocol for the Fedora Messaging system.
This protocol builds on the generic pika AMQP protocol to add calls specific to the Fedora Messaging implementation.
-
pauseProducing
()[source]¶ Pause the reception of messages. Does not disconnect from the server.
Message reception can be resumed with
resumeProducing()
.Returns: fired when the production is paused. Return type: Deferred
-
publish
(message, exchange)[source]¶ Publish a
fedora_messaging.message.Message
to an exchange on the message broker.Parameters: - message (message.Message) – The message to publish.
- exchange (str) – The name of the AMQP exchange to publish to
-
resumeProducing
()[source]¶ Starts or resumes the retrieval of messages from the server queue.
This method starts receiving messages from the server, they will be passed to the consumer callback.
Returns: fired when the production is ready to start Return type: Deferred
-
Factory¶
Twisted Factory to create the Fedora Messaging Twisted Protocol instance.
See https://twistedmatrix.com/documents/current/core/howto/clients.html#clientfactory
-
class
fedora_messaging.twisted.factory.
FedoraMessagingFactory
(parameters, bindings)[source]¶ Reconnecting factory for the Fedora Messaging protocol.
-
buildProtocol
(addr)[source]¶ Create the Protocol instance.
See the documentation of twisted.internet.protocol.ReconnectingClientFactory for details.
-
clientConnectionFailed
(connector, reason)[source]¶ Called when the client has failed to connect to the broker.
See the documentation of twisted.internet.protocol.ReconnectingClientFactory for details.
-
clientConnectionLost
(connector, reason)[source]¶ Called when the connection to the broker has been lost.
See the documentation of twisted.internet.protocol.ReconnectingClientFactory for details.
-
consume
(message_callback)[source]¶ Pass incoming messages to the provided callback.
Parameters: message_callback (callable) – The callable to pass the message to when one arrives.
-
protocol
¶ alias of
fedora_messaging.twisted.protocol.FedoraMessagingProtocol
-
publish
(message, exchange=None)[source]¶ Publish a
fedora_messaging.message.Message
to an exchange on the message broker.Parameters: - message (message.Message) – The message to publish.
- exchange (str) – The name of the AMQP exchange to publish to; defaults to publish_exchange
Raises: PublishReturned
– If the published message is rejected by the broker.ConnectionException
– If a connection error occurs while publishing.
-
startedConnecting
(connector)[source]¶ Called when the connection to the broker has started.
See the documentation of twisted.internet.protocol.ReconnectingClientFactory for details.
-
Service¶
Twisted Service to start and stop the Fedora Messaging Twisted Factory.
This Service makes it easier to build a Twisted application that embeds a
Fedora Messaging component. See the verify_missing
service in
fedmsg-migration-tools for a use case.
See https://twistedmatrix.com/documents/current/core/howto/application.html
-
class
fedora_messaging.twisted.service.
FedoraMessagingService
(on_message, amqp_url=None, bindings=None)[source]¶ A Twisted service to connect to the Fedora Messaging broker.
-
factoryClass
¶ alias of
fedora_messaging.twisted.factory.FedoraMessagingFactory
-