Difference between revisions of "Python Client Library (Marconi)"
(→Claim Management: messages -> list, release() -> delete()) |
(→Working With a Connection: data -> json in requests body) |
||
Line 55: | Line 55: | ||
# Client ID set at the Client level | # Client ID set at the Client level | ||
>>> conn.request(Http.GET, headers={u'x-client-id': 100}, | >>> conn.request(Http.GET, headers={u'x-client-id': 100}, | ||
− | + | json={'my': 'message'}, | |
verify=True) | verify=True) | ||
<Response [200]> | <Response [200]> |
Revision as of 01:53, 20 July 2013
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!
Contents
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
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}, json={'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. >>> client = Client(conn, async=False) >>> client.queues(marker=..., limit=10, detailed=False) <generator object <genexpr> ar 0x7fd3ef1ed730> >>> client.create_queue(name='wot') <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.href u'/v1/queues/tacocat' >>> queue.stats # a dictionary derived from a JSON response >>> queue.list(include_claimed=False) <generator object <genexpr> ar 0x7fd3ef1ed742> >>> queue.list(ids=[50b68a50d6f5b8c8a7c62b01, 50b68a50d6f5b8c8a7c62b02], claim=a28ee94e-6cb4-11e2-b4d5-7703267a7926, limit=1) <generator object <genexpr> ar 0x7fd3ef1ed742> >>> queue.post(messages=...) >>> queue.metadata <Metadata ...> # fetches metadata from API, returns a Metadata controller >>> queue.claim(limit=10) <Claim size:8 ...> # size: actual number of messages received >>> queue.delete()
Queue Metadata Handling
>>> meta = queue.metadata >>> meta.put({'max_size': 1000}) # communicate with API, replaces >>> meta.reload() # gets most recent attributes from API
Message Handling
>>> message = next(queue.messages(...)) >>> message.age 90 >>> message.ttl 120 >>> message.href u'/v1/queues/darn_good_queue/messages/91wqe9bqwsbq98' >>> message.body {u'action': u'win'} >>> message.reload() >>> message.delete() >>> message.status <EnumValue: Message.Free [value=1]>
Claim Management
>>> claim = queue.claim(limit=10) >>> claim.list(...) <generator object <genexpr> ar 0x7fd3ef1ed742> >>> msg = next(claim.list(...)) >>> msg.status <EnumValue: Message.Claimed [value=2]> >>> claim.href u'/v1/queues/tacocat/claims/a28ee94e-6cb4-11e2-b4d5-7703267a7926' >>> claim.ttl 90 >>> claim.grace 30 >>> 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