Python Client Library (Marconi)

This document exists to establish the feel of working with the python Marconi client. It serves as both a vision and a direction for implementors. Check out the blueprints for more details.

If you have questions, reach us at freenode.irc.net #openstack-marconi!

Features

Certificate verification
Reauthentication on token expiration
Async operations
Full coverage of Marconi API

Classes

Controllers

Client: handles account-wide operations - queue retrieval, etc.
Queue: gives access to some metadata ops, as well as message handling
Message: gives access to properties of message, as well as deletion
Claim: Collection of claimed messages - handle querying, updating, and deleting

Core

Connection: handles authentication with Keystone, acquires Marconi endpoint, handles requests and networking logic

Utility

ErrorBase: the foundation for Marconi client specific errors

API Synopsis

See Marconi/specs/api/v1

Usage

Working With a Connection

    >>> from marconiclient.common.connection import Connection
    >>> conn = Connection('tacocat', apikey='my_awesome_key')
    >>> conn.tenant
    123456
    >>> conn.username
    u'tacocat'
    >>> conn.version
    u'1.0'
    >>> conn.token
    u'1234567654321234543hj2b34j54bj32'
    >>> conn.expires
    datetime.datetime(2013, 7, 10, 13, 29, 54, 702873)
    >>> conn.host
    u'https://marconi.example.com/v1.0'
    >>> conn.headers
    {u'x-auth-token': ..., u'host': ..., u'date': ..., u'accept': ...,
     u'accept-encoding': ..., u'content-length': ..., u'x-project-id': ...}
    # Client ID set at the Client level
    >>> conn.request(Http.GET, headers={u'x-client-id': 100},
                     data=json.dumps({'my': 'message'}),
                     verify=True)
    <Response [200]>
    >>> conn
    <MarconiConnection user:tacocat expires:2013-07-11T03:28:33.834-05:00>

Http.Get is a client-defined Python enumeration. See flufl.enum and PEP 435 for more information on Python enumerations.

Client Operation

    # Implement auth using common lib. Client calls to that.
    >>> from marconiclient.core.client import Client
    >>> client = Client(conn, async=False)
    >>> client.queues(marker=..., limit=10, detailed=False)
    <generator object <genexpr> ar 0x7fd3ef1ed730>
    >>> client.create_queue(name='wot', metadata=json.dumps({'game': 'd2'}))
    <MarconiQueue [wot]>
    >>> client.home
    <HomeDoc ...>
    # affects all operations for objects acquired from the client
    >>> client.async
    False

Queue Handling

    >>> queue = next(q for q in client.queues if q.name == 'tacocat')
    >>> queue.name
    u'tacocat'
    >>> queue.stats
    <QueueStats ...>
    >>> queue.get_messages()
    <generator object <genexpr> ar 0x7fd3ef1ed742>
    >>> queue.get_messages(ids=[50b68a50d6f5b8c8a7c62b01, 50b68a50d6f5b8c8a7c62b02],
                           claim=a28ee94e-6cb4-11e2-b4d5-7703267a7926, limit=1)
    <generator object <genexpr> ar 0x7fd3ef1ed742>
    >>> queue.post_messages(messages=...)
    >>> queue.metadata
    {'a': 1, 'b': 2}
    >>> queue.set_metadata({'a': 2, ...})
    >>> queue.claim(limit=10)
    <generator object <genexpr> ar 0x7fd3ef1ed742>
    >>> queue.delete()
    >>> queue.release_claim(...)
    >>> queue.update_claim(...)

Message Handling

    >>> message = next(queue.messages(...))
    >>> message.age
    90
    >>> message.ttl
    120
    >>> message.id
    u'9y22h21w2h'
    >>> message.body
    {u'action': u'win'}
    >>> message.delete()
    >>> message.status
    <EnumValue: Message.Free [value=1]>

Claim Management

>>> claim = queue.claim(limit=10)
# identical to queue message fetch API, with claim id pre-filled
>>> claim.messages(...)
<generator object <genexpr> ar 0x7fd3ef1ed742>
>>> msg = next(claim.messages(...))
>>> msg.status
<EnumValue: Message.Claimed [value=2]>
>>> claim.id
...
>>> claim.ttl
90
>>> claim.age
120
>>> claim.patch(ttl=..., grace=...)
>>> claim.delete()

Error Management

The wiki gives a thorough explanation of Marconi Errors. Error handling at the client-level is a matter of transforming responses returned by Marconi into exceptions that are meaningful to users.

Here's a quick mock up of error usage at the level of the client:

    >> error = marconi.error.ErrorBase()
    >>> error.title
    u'...'
    >>> error.description
    u'...'
    >>> error.code
    1092
    >>> raise error
    ErrorBase (error.code): error.title
    error.description