Serena is a structurally concurrent AMQP 0-9-1 client library, for usage with the AnyIO library.
Serena requires at least Python 3.11.
Serena is primarily tested against RabbitMQ, but any broker that supports the errata version of AMQP is supported.
The AMQP server must support publisher confirms. (RabbitMQ does support this.)
Serena can be installed from PyPI:
$ poetry add serena
It can then be imported from the
Serena is a relatively thin wrapper around the AMQP 0-9-1 specification, and as such you should familiarise yourself with the AMQP Model before using this library.
First, you need to open a connection. You can do this with the
manager provided, like so:
from serena import open_connection async with open_connection( host="127.0.0.1", port=5672, username="guest", password="guest", virtual_host="/", ) as conn: ...
from serena import open_connection async with open_connection(...) as conn: async with conn.open_channel() as channel: ...
There are situations where you or someone else (usually, somebody else) makes a programming error that the server doesn’t like.
In these situations, the server will return a Close message that is handled by client machinery, and either the connection or the channel will close. Which one happens is specified in the AMQP specification.
Either way, a
UnexpectedCloseError will be raised:
If the channel is closed, then it will be raised by the method itself
If the connection is closed, then the entire connection will die and it will be raised by the
async withblock. In addition, all code inside the connection will be cancelled.
- class serena.UnexpectedCloseError(reply_code, reply_message, class_id, method_id)
Thrown when the connection or a channeel closes unexpectedly.
- classmethod of(payload)
Creates a new
UnexpectedCloseErrorfrom a close payload.
- Return type:
The server-provided error code.
Some other errors may be raised for programming errors, such as:
- class serena.MessageReturnedError(reply_code, reply_text, exchange, routing_key)
Thrown when a message is returned unexpectedly.
The server-provided error code.
The server-provided error text.
The exchange the message was returned from.
The routing key the message was using.
As AMQP is a multiplexed protocol, Serena internally uses several memory channels to distribute messages from the socket to individual channel objects. Memory channels apply backpressure, which means that new messages cannot be delivered when the channel is full.
To avoid this, Serena will automatically apply per-channel QoS to avoid buffering more items than
the channel can support. By default, this will be the floor division by three of the
channel_buffer_size (default: 48) passed when opening the connection, as every publish uses
three frames minimum (Basic.Publish|Get, headers, body). This is primarily a network optimisation
as it means the server can send N messages now potentially over less TCP packets instead of needing
to a full cycle each time.
However, messages with a large body size may be split across multiple body frames which has the potential to overflow the buffer. When this happens, *the entire connection will block*, as the socket cannot be read from until there is room to buffer new packets in memory.
To avoid this:
Increase the frame size by passing
Increase the frame size in the broker configuration.
Send smaller messages.
Serena negotiates the frame size using the smallest size requested, either on the client or on the server side. You need to change it on both.
New in version 0.7.1.
Serena has a built-in channel pooling mechanism, which simplifies error handling (no need to wrap
async with in a try/except). See
The primary protagonist of Bishōjo Senshi Sailor Moon is called Usagi Tsukino.
Usagi means “rabbit”.
Her name was changed to Serena Tsukino in the 1990s DIC English dub of Sailor Moon.
RabbitMQ is the most popular and well-known AMQP 0-9-1 broker.
Hence, the name Serena.