Difference between revisions of "Python Client Library (Marconi)"
(Python client knowledge, round 1.) |
(Longer strings for IDs.) |
||
Line 92: | Line 92: | ||
>>> queue.get_messages() | >>> queue.get_messages() | ||
<generator object <genexpr> ar 0x7fd3ef1ed742> | <generator object <genexpr> ar 0x7fd3ef1ed742> | ||
− | >>> queue.get_messages(ids=[ | + | >>> queue.get_messages(ids=[50b68a50d6f5b8c8a7c62b01, 50b68a50d6f5b8c8a7c62b02], claim=a28ee94e-6cb4-11e2-b4d5-7703267a7926, limit=1) |
<generator object <genexpr> ar 0x7fd3ef1ed742> | <generator object <genexpr> ar 0x7fd3ef1ed742> | ||
>>> queue.post_messages(messages=...) | >>> queue.post_messages(messages=...) |
Revision as of 14:55, 17 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}, 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