Client

A Client is a high-level abstraction on top of Zaqar features. It exposes the server features with an object-oriented interface, which encourages dot notation and automatic, but lazy, resources allocation. A Client allows you to control everything, from public interfaces to admin endpoints.

To create a Client instance, you supply an url pointing to the server and a version number:

from zaqarclient.queues import client

cli = client.Client('http://zaqar.example.com:8888/', version=2)

which will load the appropriate client based on the specified version. Optionally, you can also supply a config dictionary:

from zaqarclient.queues import client

cli = client.Client('http://zaqar.example.com:8888/',
                    version=2, conf={})

The arguments passed to this function will be passed to the client instances as well.

It’s recommended to use Client instances instead of accessing the lower level API as it has been designed to ease the interaction with the server and it gives enough control for the most common cases.

A simple example for accessing an existing queue through a client instance - based on the API v2 - would look like:

from zaqarclient.queues import client

cli = client.Client('http://zaqar.example.com:8888/', version=2)
queue = cli.queue('my_queue')

Through the queue instance will be then possible to access all the features associated with the queue itself like posting messages, getting message and deleting messages.

As mentioned previously in this documentation, a client instance allows you to also access admin endpoints, for example:

from zaqarclient.queues import client

cli = client.Client('http://zaqar.example.com:8888/', version=2)
flavor = cli.flavor('tasty',
                    pool='my-pool-group',
                    auto_create=True)
flavor.delete()

Client uses the lower-level API to access the server, which means anything you can do with this client instance can be done by accessing the underlying API, although not recommended.

Client Object Reference

This is the reference documentation for all API version.

API v1 and v1.1:

class Client(url=None, version=1, conf=None, session=None)

Client base class

Parameters:
  • url (six.text_type) – Zaqar’s instance base url.
  • version (int) – API Version pointing to.
  • options (dict) –

    Extra options: - client_uuid: Custom client uuid. A new one will be generated, if not passed. - auth_opts: Authentication options:

    • backend
    • options
  • session – keystone session. But it’s just place holder, we wont’ support it in v1.
flavor(*args, **kwargs)

Returns a flavor instance

Parameters:ref (six.text_type) – Flavor’s reference name.
Returns:A flavor instance
Return type:flavor.Flavor
flavors(*args, **kwargs)

Gets a list of flavors from the server

Parameters:params (**kwargs dict.) – Filters to use for getting flavors
Returns:A list of flavors
Return type:list
follow(ref)

Follows ref.

This method instanciates a new request instance and requests ref. It is intended to be used to follow a reference href gotten from links sections in responses like queues’ lists.

Params ref:The reference path.
health()

Gets the health status of Zaqar server.

pool(ref, **kwargs)

Returns a pool instance

Parameters:ref (six.text_type) – Pool’s reference name.
Returns:A pool instance
Return type:pool.Pool
pools(**params)

Gets a list of pools from the server

Parameters:params (**kwargs dict.) – Filters to use for getting pools
Returns:A list of pools
Return type:list
queue(ref, **kwargs)

Returns a queue instance

Parameters:ref (six.text_type) – Queue’s reference id.
Returns:A queue instance
Return type:queues.Queue
queues(**params)

Gets a list of queues from the server

Returns:A list of queues
Return type:list
transport()

Gets a transport based the api url and version.

Return type:zaqarclient.transport.base.Transport

API v2.0:

class Client(url=None, version=2, conf=None, session=None)

Client base class

Parameters:
  • url (six.text_type) – Zaqar’s instance base url.
  • version (int) – API Version pointing to.
  • options (dict) –

    Extra options: - client_uuid: Custom client uuid. A new one will be generated, if not passed. - auth_opts: Authentication options:

    • backend
    • options
health(*args, **kwargs)

Gets the detailed health status of Zaqar server.

ping()

Gets the health status of Zaqar server.

queue(ref, **kwargs)

Returns a queue instance

Parameters:ref (six.text_type) – Queue’s reference id.
Returns:A queue instance
Return type:queues.Queue
subscription(*args, **kwargs)

Returns a subscription instance

Parameters:queue_name (six.text_type) – Name of the queue to subscribe to.
Returns:A subscription instance
Return type:subscription.Subscription
subscriptions(*args, **kwargs)

Gets a list of subscriptions from the server

Parameters:params (**kwargs dict.) – Filters to use for getting subscriptions
Returns:A list of subscriptions
Return type:list