Welcome to Pyrakoon’s documentation!

Usage

Basic Usage

The pyrakoon library provides the building blocks to create an Arakoon client library in Python. It contains the required data types used in the client protocol, including serialization and parsing routines. It also includes descriptions of the available operations.

The code is not bound to a specific method of communicating with Arakoon nodes though. This is abstracted, and left up to the user to implement according to specific needs and communication mechanisms.

Socket Handling

To provide an implementation of the abstract communication mechanism, the AbstractClient interface must be fulfilled. A very basic implementation, which can be used to communicate with a single Arakoon node (i.e. no master failover or reconnection is provided) using blocking socket calls is provided by SocketClient.

Warning

SocketClient should only be used for (manual) testing purposes. Due to the lack of good exception handling, timeouts,... it should not be used in real-world code.

Mixins

When given an AbstractClient implementation, this doesn’t give access to actual client operations. Whilst it’s possible to create instances of the calls as defined in pyrakoon.protocol and related modules and pass these through _process(), this is rather clumsy.

To provide a uniform interface, not bound to a specific AbstractClient implementation, a couple of mixins are provided, which expose client operations in a user-friendly way. Several mixins are available:

These can be combined with an AbstractClient implementation and used as-is. Here’s an example using SocketClient, mixing in pyrakoon.client.ClientMixin and pyrakoon.client.admin.ClientMixin:

>>> from pyrakoon import client
>>> from pyrakoon.client import admin

>>> class Client(client.SocketClient, client.ClientMixin, admin.ClientMixin):
...     '''An Arakoon client'''

>>> c = Client(('localhost', 4000), 'ricky')
>>> c.connect()
>>> c.set('key', 'value') # from client.ClientMixin
>>> c.collapse_tlogs(4) # from admin.ClientMixin
[]

Twisted Support

pyrakoon comes with an AbstractClient implementation supporting the Twisted framework, provided as a Protocol in the pyrakoon.tx module.

Here’s a demonstration of how it could be used:

>>> from twisted.internet import defer, endpoints, reactor
>>> from pyrakoon import client, tx

>>> class Protocol(tx.ArakoonProtocol, client.ClientMixin): pass

>>> @defer.inlineCallbacks
... def connected(proto):
...     yield proto.set('key', 'value')
...     value = yield proto.get('key')
...     print 'Value:', value
...     yield proto.delete('key')
...     reactor.stop()

>>> endpoint = endpoints.TCP4ClientEndpoint(reactor, 'localhost', 4000)
>>> d = endpoints.connectProtocol(endpoint, Protocol('ricky'))
>>> d.addCallback(connected)
<Deferred at ...>
>>> reactor.run()
Value: value

API

pyrakoon pyrakoon, an Arakoon client for Python
pyrakoon.client Arakoon client interface
pyrakoon.client.admin Administrative client interface
pyrakoon.errors Exceptions raised by client operations, as returned by a node
pyrakoon.sequence Sequence implementation
pyrakoon.tx
pyrakoon.test Testing utilities
pyrakoon.utils Utility functions
pyrakoon.protocol Arakoon protocol implementation
pyrakoon.protocol.admin Arakoon administrative call implementations
pyrakoon.client.utils Utility functions for building client mixins

Indices and tables