API Documentation

aiorsmq

class AIORSMQ(*, client: aioredis.client.Redis, client_encoding: str = 'utf-8', namespace: str = 'rsmq', real_time: bool = False)[source]

Bases: object

Asynchronous Python implementation of the JavaScript rsmq (Redis Simple Message Queue) library.

The AIORSMQ class uses a connection to a Redis server to create and delete message queues, as well as send and receive messages. It is the main entry point of the aiorsmq package.

__init__(*, client: aioredis.client.Redis, client_encoding: str = 'utf-8', namespace: str = 'rsmq', real_time: bool = False) → None[source]

Initialize an AIORSMQ object.

Parameters

  • client – Redis client to use internally (create it using the aioredis package).

  • client_encoding – When the Redis client has been configured with decode_responses=True, please ensure that the value of this parameter matches the encoding used for the Redis client. When the Redis client has not been configured with decode_responses=True, you may safely ignore this parameter. The default encoding used by the Redis client is also utf-8, so in most cases setting this parameter manually will not be necessary.

  • namespace – Namespace to prefix keys with.

  • real_time – Enable real time mode. When enabled, a notification will be sent using Redis PUBLISH each time a message is added to a message queue.

async change_message_visibility(queue_name: str, id: str, vt: int) → None[source]

Change the visibility timer of a message.

Parameters

  • queue_name – Name of the message queue containing the message.

  • id – Message’s unique ID.

  • vt – New visibility timer value to set (in seconds). The message will be invisible to consumers until the visibility timer period has elapsed, starting from the moment this method was called.

Raises
async create_queue(queue_name: str, vt: int = 30, delay: int = 0, max_size: int = 65536) → None[source]

Create a new message queue.

Parameters

  • queue_name – Name of the new message queue.

  • vt – Default visibility delay (in seconds) to use when receiving messages from the queue.

  • delay – Default delay (in seconds) to apply when sending messages to the queue.

  • max_size – Maximum message size for the queue (in bytes).

Raises
async delete_message(queue_name: str, id: str) → None[source]

Delete a message from a message queue.

Parameters

  • queue_name – Name of the message queue containing the message.

  • id – Message’s unique ID.

Raises
async delete_queue(queue_name: str) → None[source]

Delete a message queue.

Parameters

queue_name – Name of the message queue to delete.

Raises
async get_queue_attributes(queue_name: str) → aiorsmq.aiorsmq.QueueAttributes[source]

Retrieve a message queue’s attributes.

Parameters

queue_name – Name of the message queue.

Raises
Returns

Object containing the queue’s attributes.

async list_queues() → List[str][source]

Retrieve a list of all existing queues.

Note: The namespace is not included in the queue names.

Returns

List of queue names.

async pop_message(queue_name: str) → Optional[aiorsmq.aiorsmq.Message][source]

Receive a message from a message queue and delete it from the queue.

Note: This method will return None immediately if the message queue is empty.

With this method, there is no need to call delete_message after receiving a message. However, if an error/exception/crash occurs in your application while processing the message, there is a risk of losing it forever, as it will no longer be stored in the message queue.

Parameters

queue_name – Name of the message queue.

Raises
Returns

Message received from the message queue if one was present, None otherwise.

async quit() → None[source]

Close the connection to the Redis server.

Internally, this methods just calls the close method of the Redis client object specified in the initializator.

async receive_message(queue_name: str, vt: Optional[int] = None) → Optional[aiorsmq.aiorsmq.Message][source]

Receive a message from a message queue.

Note: This method will return None immediately if the message queue is empty.

After receiving a message and successfully processing it, make sure to call delete_message to ensure you won’t receive it again in the future.

Parameters

  • queue_name – Name of the message queue.

  • vt – Visibility timer to use when receving the message (in seconds). If not specified, the queue’s visiblity timer value will be used. After the message has been received, it will be invisible to consumers until the duration visiblity timer period has elapsed.

Raises
Returns

Message received from the message queue if one was present, None otherwise.

async send_message(queue_name: str, contents: Union[str, bytes], delay: Optional[int] = None) → str[source]

Send a message to a message queue.

Parameters

  • queue_name – Name of the message queue.

  • contents – Contents of the message to send. Note: If the Redis client was configured with decode_responses=True, this parameter should be set to an instance of str. Otherwise, bytes should be used. This will also affect the contents of the message received when using receive_message or pop_message.

  • delay – Delay to apply when sending the message (in seconds). If not specified, the queue’s delay value will be used. The message will only be receivable after the delay period has elapsed.

Raises
Returns

Unique ID of the message sent.

async set_queue_attributes(queue_name: str, vt: Optional[int] = None, delay: Optional[int] = None, max_size: Optional[int] = None) → aiorsmq.aiorsmq.QueueAttributes[source]

Update one or more attributes of a message queue.

Parameters

  • queue_name – Name of the message queue.

  • vt – New default visibility delay (in seconds) to use when receiving messages from the queue.

  • delay – New default delay (in seconds) to apply when sending messages to the queue.

  • max_size – New maximum message size for the queue (in bytes).

Raises
Returns

Object containing the queue’s attributes, including the updated ones.

class Message(*, contents: Union[str, bytes], id: str, fr: int, rc: int, sent: float)[source]

Bases: object

Represents a message received from a message queue.

__init__(*, contents: Union[str, bytes], id: str, fr: int, rc: int, sent: float) → None[source]

Initialize a Message object.

Note: This description is provided only for documentation purposes - users of aiorsmq have no need for creating Message objects manually.

Parameters

  • contents – Contents of the message.

  • id – Message’s unique ID, consisting of 32 characters. Example: fzl7ufz2q5iX40Bm9uc0DjQCsqpbQfL3.

  • fr – UNIX timestamp indicating when the message was first receieved (in milliseconds).

  • rc – Number of times this message has been received by consumers. Will always be at least 1.

  • sent – UNIX timestamp indicating when the message was sent (in milliseconds).

class QueueAttributes(*, vt: int, delay: int, max_size: int, total_recv: int, total_sent: int, created: int, modified: int, messages: int, hidden_messages: int)[source]

Bases: object

Represents the attributes of a message queue.

__init__(*, vt: int, delay: int, max_size: int, total_recv: int, total_sent: int, created: int, modified: int, messages: int, hidden_messages: int) → None[source]

Initialize a QueueAttributes object.

Note: This description is provided only for documentation purposes - users of aiorsmq have no need for creating QueueAttributes objects manually.

Parameters

  • vt – Visibility timer for receiving messages (in seconds).

  • delay – Delay to apply when sending messages (in seconds).

  • max_size – Maximum message size (in bytes).

  • total_recv – Total number of times a message was received from this queue.

  • total_sent – Total number of messages sent to this queue.

  • created – UNIX timestamp indicating when the queue was created (in seconds).

  • modified – UNIX timestamp indicating the last time the queue’s attributes were modified (in seconds).

  • messages – Total number of messages currently in the queue, including hidden messages. A message may be hidden because a delay was applied to it when adding it to the queue, or because it was received and so a visibility timer was applied to it.

  • hidden_messages – Total number of hidden messages currently in the queue.

aiorsmq.exceptions

exception AIORSMQException[source]

Bases: Exception

Base class for all aiorsmq exceptions.

exception InvalidValueException[source]

Bases: aiorsmq.exceptions.AIORSMQException

Raised when an argument has the right type but its value is out of range.

exception MessageNotFoundException[source]

Bases: aiorsmq.exceptions.AIORSMQException

Exception raised when a message does not exist.

exception NoAttributesSpecified[source]

Bases: aiorsmq.exceptions.AIORSMQException

Exception raised when no queue attributes were specified.

exception QueueExistsException[source]

Bases: aiorsmq.exceptions.AIORSMQException

Exception raised when a queue name is already taken.

exception QueueNotFoundException[source]

Bases: aiorsmq.exceptions.AIORSMQException

Exception raised when a queue does not exist.