The api Module

The api module is the only module meant for use by users of the module, although that is not enforced. It exposes an interface for getting at all of the functionality provided by the RabbitMQ API. Where that is not true, it will be shortly ;-)

The api module houses the Client class, which provides the main interface developers will use to interact with RabbitMQ. It also contains errors and decorators used by the class.

exception pyrabbit.api.APIError[source]

Denotes a failure due to unexpected or invalid input/output between the client and the API

class pyrabbit.api.Client(api_url, user, passwd, timeout=5, scheme='http')[source]

Abstraction of the RabbitMQ Management HTTP API.

HTTP calls are delegated to the HTTPClient class for ease of testing, cleanliness, separation of duty, flexibility, etc.

create_binding(vhost, exchange, queue, rt_key=None, args=None)[source]

Creates a binding between an exchange and a queue on a given vhost.

Parameters:
  • vhost (string) – vhost housing the exchange/queue to bind
  • exchange (string) – the target exchange of the binding
  • queue (string) – the queue to bind to the exchange
  • rt_key (string) – the routing key to use for the binding
  • args (list) – extra arguments to associate w/ the binding.
Returns:

boolean

create_exchange(vhost, name, xtype, auto_delete=False, durable=True, internal=False, arguments=None)[source]

Creates an exchange in the given vhost with the given name. As per the RabbitMQ API documentation, a JSON body also needs to be included that “looks something like this”:

{“type”:”direct”, “auto_delete”:false, “durable”:true, “internal”:false, “arguments”:[]}

On success, the API returns a 204 with no content, in which case this function returns True. If any other response is received, it’s raised.

Parameters:
  • vhost (string) – Vhost to create the exchange in.
  • name (string) – Name of the proposed exchange.
  • type (string) – The AMQP exchange type.
  • auto_delete (bool) – Whether or not the exchange should be dropped when the no. of consumers drops to zero.
  • durable (bool) – Whether you want this exchange to persist a broker restart.
  • internal (bool) – Whether or not this is a queue for use by the broker only.
  • arguments (list) – If given, should be a list. If not given, an empty list is sent.
create_queue(vhost, name, **kwargs)[source]

Create a queue. The API documentation specifies that all of the body elements are optional, so this method only requires arguments needed to form the URI

Parameters:
  • vhost (string) – The vhost to create the queue in.
  • name (string) – The name of the queue

More on these operations can be found at: http://www.rabbitmq.com/amqp-0-9-1-reference.html

create_user(username, password, tags='')[source]

Creates a user.

Parameters:
  • username (string) – The name to give to the new user
  • password (string) – Password for the new user
  • tags (string) – Comma-separated list of tags for the user
Returns:

boolean

create_vhost(vname)[source]

Creates a vhost on the server to house exchanges.

Parameters:vname (string) – The name to give to the vhost on the server
Returns:boolean
delete_binding(vhost, exchange, queue, rt_key)[source]

Deletes a binding between an exchange and a queue on a given vhost.

Parameters:
  • vhost (string) – vhost housing the exchange/queue to bind
  • exchange (string) – the target exchange of the binding
  • queue (string) – the queue to bind to the exchange
  • rt_key (string) – the routing key to use for the binding
delete_connection(name)[source]

Close the named connection. The API returns a 204 on success, in which case this method returns True, otherwise the error is raised.

Parameters:name (string) – The name of the connection to delete.
Returns bool:True on success.
delete_exchange(vhost, name)[source]

Delete the named exchange from the named vhost. The API returns a 204 on success, in which case this method returns True, otherwise the error is raised.

Parameters:
  • vhost (string) – Vhost where target exchange was created
  • name (string) – The name of the exchange to delete.
Returns bool:

True on success.

delete_permission(vname, username)[source]

Delete permission for a given username on a given vhost. Both must already exist.

Parameters:
  • vname (string) – Name of the vhost to set perms on.
  • username (string) – User to set permissions for.
delete_queue(vhost, qname)[source]

Deletes the named queue from the named vhost.

Parameters:
  • vhost (string) – Vhost housing the queue to be deleted.
  • qname (string) – Name of the queue to delete.

Note that if you just want to delete the messages from a queue, you should use purge_queue instead of deleting/recreating a queue.

delete_user(username)[source]

Deletes a user from the server.

Parameters:username (string) – Name of the user to delete from the server.
delete_vhost(vname)[source]

Deletes a vhost from the server. Note that this also deletes any exchanges or queues that belong to this vhost.

Parameters:vname (string) – Name of the vhost to delete from the server.
get_all_vhosts()[source]

Lists the names of all RabbitMQ vhosts.

Returns:a list of dicts, each dict representing a vhost on the broker.
get_bindings()[source]
Returns:list of dicts
get_channel(name)[source]

Get a channel by name. To get the names, use get_channels.

Parameters:name (string) – Name of channel to get
Returns dict conn:
 A channel attribute dictionary.
get_channels()[source]

Return a list of dicts containing details about broker connections. :returns: list of dicts

get_connection(name)[source]

Get a connection by name. To get the names, use get_connections.

Parameters:name (string) – Name of connection to get
Returns dict conn:
 A connection attribute dictionary.
get_connections()[source]
Returns:list of dicts, or an empty list if there are no connections.
get_exchange(vhost, name)[source]

Gets a single exchange which requires a vhost and name.

Parameters:
  • vhost (string) – The vhost containing the target exchange
  • name (string) – The name of the exchange
Returns:

dict

get_exchanges(vhost=None)[source]
Returns:A list of dicts
Parameters:vhost (string) – A vhost to query for exchanges, or None (default), which triggers a query for all exchanges in all vhosts.
get_messages(vhost, qname, count=1, requeue=False, truncate=None, encoding='auto')[source]

Gets <count> messages from the queue.

Parameters:
  • vhost (string) – Name of vhost containing the queue
  • qname (string) – Name of the queue to consume from
  • count (int) – Number of messages to get.
  • requeue (bool) – Whether to requeue the message after getting it. This will cause the ‘redelivered’ flag to be set in the message on the queue.
  • truncate (int) – The length, in bytes, beyond which the server will truncate the message before returning it.
Returns:

list of dicts. messages[msg-index][‘payload’] will contain the message body.

get_nodes()[source]
Return type:dict

Returns a list of dictionaries, each containing the details of each node of the cluster.

get_overview()[source]
Return type:dict

Data in the ‘overview’ depends on the privileges of the creds used, but typically contains information about the management plugin version, some high-level message stats, and aggregate queue totals. Admin-level creds gets you information about the cluster node, listeners, etc.

get_permission(vname, username)[source]
Returns:

dicts of permissions.

Parameters:
  • vname (string) – Name of the vhost to set perms on.
  • username (string) – User to set permissions for.
get_permissions()[source]
Returns:list of dicts, or an empty list if there are no permissions.
get_queue(vhost, name)[source]

Get a single queue, which requires both vhost and name.

Parameters:
  • vhost (string) – The virtual host for the queue being requested. If the vhost is ‘/’, note that it will be translated to ‘%2F’ to conform to URL encoding requirements.
  • name (string) – The name of the queue being requested.
Returns:

A dictionary of queue properties.

Return type:

dict

get_queue_bindings(vhost, qname)[source]

Return a list of dicts, one dict per binding. The dict format coming from RabbitMQ for queue named ‘testq’ is:

{“source”:”sourceExch”,”vhost”:”/”,”destination”:”testq”,
“destination_type”:”queue”,”routing_key”:”.”,”arguments”:{}, “properties_key”:”%2A.%2A”}
get_queue_depth(vhost, name)[source]
Get the number of messages currently in a queue. This is a convenience
function that just calls Client.get_queue() and pulls out/returns the ‘messages’ field from the dictionary it returns.
Parameters:
  • vhost (string) – The vhost of the queue being queried.
  • name (string) – The name of the queue to query.
Returns:

Number of messages in the queue

Return type:

integer

get_queue_depths(vhost, names=None)[source]

Get the number of messages currently sitting in either the queue names listed in ‘names’, or all queues in ‘vhost’ if no ‘names’ are given.

Parameters:
  • vhost (str) – Vhost where queues in ‘names’ live.
  • names (list) – OPTIONAL - Specific queues to show depths for. If None, show depths for all queues in ‘vhost’.
get_queues(vhost=None)[source]

Get all queues, or all queues in a vhost if vhost is not None. Returns a list.

Parameters:vhost (string) – The virtual host to list queues for. If This is None (the default), all queues for the broker instance are returned.
Returns:A list of dicts, each representing a queue.
Return type:list of dicts
get_user_permissions(username)[source]
Returns:list of dicts, or an empty list if there are no permissions.
Parameters:username (string) – User to set permissions for.
get_users()[source]

Returns a list of dictionaries, each containing the attributes of a different RabbitMQ user.

Returns:a list of dictionaries, each representing a user.
get_vhost(vname)[source]

Returns the attributes of a single named vhost in a dict.

Parameters:vname (string) – Name of the vhost to get.
Returns dict vhost:
 Attribute dict for the named vhost
get_vhost_names()[source]

A convenience function for getting back only the vhost names instead of the larger vhost dicts.

Returns list vhost_names:
 A list of just the vhost names.
get_vhost_permissions(vname)[source]
Returns:list of dicts, or an empty list if there are no permissions.
Parameters:vname (string) – Name of the vhost to set perms on.
get_whoami()[source]

A convenience function used in the event that you need to confirm that the broker thinks you are who you think you are.

Returns dict whoami:
 Dict structure contains: * administrator: whether the user is has admin privileges * name: user name * auth_backend: backend used to determine admin rights
is_alive(vhost='%2F')[source]

Uses the aliveness-test API call to determine if the server is alive and the vhost is active. The broker (not this code) creates a queue and then sends/consumes a message from it.

Parameters:vhost (string) – There should be no real reason to ever change this from the default value, but it’s there if you need to.
Returns bool:True if alive, False otherwise
Raises:HTTPError if vhost doesn’t exist on the broker.
publish(vhost, xname, rt_key, payload, payload_enc='string', properties=None)[source]

Publish a message to an exchange.

Parameters:
  • vhost (string) – vhost housing the target exchange
  • xname (string) – name of the target exchange
  • rt_key (string) – routing key for message
  • payload (string) – the message body for publishing
  • payload_enc (string) – encoding of the payload. The only choices here are ‘string’ and ‘base64’.
  • properties (dict) – a dict of message properties
Returns:

boolean indicating success or failure.

purge_queue(vhost, name)[source]

Purge all messages from a single queue. This is a convenience method so you aren’t forced to supply a list containing a single tuple to the purge_queues method.

Parameters:
  • vhost (string) – The vhost of the queue being purged.
  • name (string) – The name of the queue being purged.
Return type:

None

purge_queues(queues)[source]

Purge all messages from one or more queues.

Parameters:queues (list) – A list of (‘qname’, ‘vhost’) tuples.
Returns:True on success
set_vhost_permissions(vname, username, config, rd, wr)[source]

Set permissions for a given username on a given vhost. Both must already exist.

Parameters:
  • vname (string) – Name of the vhost to set perms on.
  • username (string) – User to set permissions for.
  • config (string) – Permission pattern for configuration operations for this user in this vhost.
  • rd (string) – Permission pattern for read operations for this user in this vhost
  • wr (string) – Permission pattern for write operations for this user in this vhost.

Permission patterns are regex strings. If you’re unfamiliar with this, you should definitely check out this section of the RabbitMQ docs:

http://www.rabbitmq.com/admin-guide.html#access-control

exception pyrabbit.api.PermissionError[source]

Raised if the operation requires admin permissions, and the user used to instantiate the Client class does not have admin privileges.