pyrakoon.client

Arakoon client interface

class pyrakoon.client.ClientMixin

Mixin providing client actions for standard cluster functionality

This can be mixed into any class implementing AbstractClient.

hello(client_id, cluster_id)

Send a “hello” command to the server

This method will return the string returned by the server when receiving a “hello” command.

Parameters:

• client_id (str) – Identifier of the client
• cluster_id (str) – Identifier of the cluster connecting to. This must match the cluster configuration.

Returns:

Message returned by the server

Return type:

str

exists(key, allow_dirty=False)

Send an “exists” command to the server

This method returns a boolean which tells whether the given key is set on the server.

Parameters:

• key (str) – Key to test
• allow_dirty (bool) – Allow reads from slave nodes

Returns:

Whether the given key is set on the server

Return type:

bool

who_master()

Send a “who_master” command to the server

This method returns the name of the current master node in the Arakoon cluster.

Returns:Name of cluster master node Return type:str

get(key, allow_dirty=False)

Send a “get” command to the server

This method returns the value of the requested key.

Parameters:

• key (str) – Key to retrieve
• allow_dirty (bool) – Allow reads from slave nodes

Returns:

Value for the given key

Return type:

str

set(key, value)

Send a “set” command to the server

This method sets a given key to a given value on the server.

Parameters:

• key (str) – Key to set
• value (str) – Value to set

delete(key)

Send a “delete” command to the server

This method deletes a given key from the cluster.

Parameters:key (str) – Key to delete

prefix(prefix, max_elements=-1, allow_dirty=False)

Send a “prefix_keys” command to the server

This method retrieves a list of keys from the cluster matching a given prefix. A maximum number of returned keys can be provided. If set to -1 (the default), all matching keys will be returned.

Parameters:

• prefix (str) – Prefix to match
• max_elements (int) – Maximum number of keys to return
• allow_dirty (bool) – Allow reads from slave nodes

Returns:

Keys matching the given prefix

Return type:

iterable of str

test_and_set(key, test_value, set_value)

Send a “test_and_set” command to the server

When test_value is not None, the value for key will only be modified if the existing value on the server is equal to test_value. When test_value is None, the key will only be set of there was no value set for the key before.

When set_value is None, the key will be deleted on the server.

The original value for key is returned.

Parameters:

• key (str) – Key to act on
• test_value (str or None) – Expected value to test for
• set_value (str or None) – New value to set

Returns:

Original value of key

Return type:

str

sequence(steps, sync=False)

Send a “sequence” or “synced_sequence” command to the server

The operations passed to the constructor should be instances of implementations of the pyrakoon.sequence.Step class. These operations will be executed in an all-or-nothing transaction.

Parameters:

• steps (iterable of pyrakoon.sequence.Step) – Steps to execute
• sync (bool) – Use synced_sequence

range(begin_key, begin_inclusive, end_key, end_inclusive, max_elements=-1, allow_dirty=False)

Send a “range” command to the server

The operation will return a list of keys, in the range between begin_key and end_key. The begin_inclusive and end_inclusive flags denote whether the delimiters should be included.

The max_elements flag can limit the number of returned keys. If it is negative, all matching keys are returned.

Parameters:

• begin_key (str) – Begin of range
• begin_inclusive (bool) – begin_key is in- or exclusive
• end_key (str) – End of range
• end_inclusive – end_key is in- or exclusive
• max_elements (int) – Maximum number of keys to return
• allow_dirty (bool) – Allow reads from slave nodes

Returns:

List of matching keys

Return type:

iterable of str

range_entries(begin_key, begin_inclusive, end_key, end_inclusive, max_elements=-1, allow_dirty=False)

Send a “range_entries” command to the server

The operation will return a list of (key, value) tuples, for keys in the range between begin_key and end_key. The begin_inclusive and end_inclusive flags denote whether the delimiters should be included.

The max_elements flag can limit the number of returned items. If it is negative, all matching items are returned.

Parameters:

• begin_key (str) – Begin of range
• begin_inclusive (bool) – begin_key is in- or exclusive
• end_key (str) – End of range
• end_inclusive (bool) – end_key is in- or exclusive
• max_elements (int) – Maximum number of items to return
• allow_dirty (bool) – Allow reads from slave nodes

Returns:

List of matching (key, value) pairs

Return type:

iterable of (str, str)

multi_get(keys, allow_dirty=False)

Send a “multi_get” command to the server

This method returns a list of the values for all requested keys.

Parameters:

• keys (iterable of str) – Keys to look up
• allow_dirty (bool) – Allow reads from slave nodes

Returns:

Requested values

Return type:

iterable of str

multi_get_option(keys, allow_dirty=False)

Send a “multi_get_option” command to the server

This method returns a list of value options for all requested keys.

Parameters:

• keys (iterable of str) – Keys to look up
• allow_dirty (bool) – Allow reads from slave nodes

Returns:

Requested values

Return type:

iterable of (str or None)

expect_progress_possible()

Send a “expect_progress_possible” command to the server

This method returns whether the master thinks progress is possible.

Returns:Whether the master thinks progress is possible Return type:bool

get_key_count()

Send a “get_key_count” command to the server

This method returns the number of items stored in Arakoon.

Returns:Number of items stored in the database Return type:int

user_function(function, argument)

Send a “user_function” command to the server

This method returns the result of the function invocation.

Parameters:

• function (str) – Name of the user function to invoke
• argument (str or None) – Argument to pass to the function

Returns:

Result of the function invocation

Return type:

str or None

confirm(key, value)

Send a “confirm” command to the server

This method sets a given key to a given value on the server, unless the value bound to the key is already equal to the provided value, in which case the action becomes a no-op.

Parameters:

• key (str) – Key to set
• value (str) – Value to set

assert_(key, value, allow_dirty=False)

Send an “assert” command to the server

assert key vo throws an exception if the value associated with the key is not what was expected.

Parameters:

• key (str) – Key to check
• value (str or None) – Optional value to compare
• allow_dirty (bool) – Allow reads from slave nodes

rev_range_entries(begin_key, begin_inclusive, end_key, end_inclusive, max_elements=-1, allow_dirty=False)

Send a “rev_range_entries” command to the server

The operation will return a list of (key, value) tuples, for keys in the reverse range between begin_key and end_key. The begin_inclusive and end_inclusive flags denote whether the delimiters should be included.

The max_elements flag can limit the number of returned items. If it is negative, all matching items are returned.

Parameters:

• begin_key (str) – Begin of range
• begin_inclusive (bool) – begin_key is in- or exclusive
• end_key (str) – End of range
• end_inclusive (bool) – end_key is in- or exclusive
• max_elements (int) – Maximum number of items to return
• allow_dirty (bool) – Allow reads from slave nodes

Returns:

List of matching (key, value) pairs

Return type:

iterable of (str, str)

statistics()

Send a “statistics” command to the server

This method returns some server statistics.

Returns:Server statistics Return type:Statistics

version()

Send a “version” command to the server

This method returns the server version.

Returns:Server version Return type:(int, int, int, str)

assert_exists(key, allow_dirty=False)

Send an “assert_exists” command to the server

assert_exists key throws an exception if the key doesn’t exist in the database.

Parameters:

• key (str) – Key to check
• allow_dirty (bool) – Allow reads from slave nodes

delete_prefix(prefix)

Send a “delete_prefix” command to the server

delete_prefix prefix will delete all key/value-pairs from the database where given prefix is a prefix of key.

Parameters:prefix (str) – Prefix of binding keys to delete Returns:Number of deleted bindings Return type:int

replace(key, value)

Send a “replace” command to the server

replace key value will replace the value bound to the given key with the provided value, and return the old value bound to the key. If value is None, the key is deleted. If the key was not present in the database, None is returned.

Parameters:

• key (str) – Key to replace
• value (str or None) – Value to set

Returns:

Original value bound to the key

Return type:

str or None

nop()

Send a “nop” command to the server

This enforces consensus throughout a cluster, but has no further effects.

get_current_state()

Send a “get_current_state” command to the server

This call returns a string representing the current state of the node, and can be used for troubleshooting purposes.

Returns:State of the server Return type:str

exception pyrakoon.client.NotConnectedError

Bases: exceptions.RuntimeError

Error used when a call on a not-connected client is made

class pyrakoon.client.AbstractClient

Abstract base class for implementations of Arakoon clients

connected = False

Flag to denote whether the client is connected

If this is False, a NotConnectedError will be raised when a call is issued.

Type:bool

_process(message)

Submit a message to the server, parse the result and return it

The given message should be serialized using its serialize() method and submitted to the server. Then the receive() coroutine of the message should be used to retrieve and parse a result from the server. The result value should be returned by this method, or any exceptions should be rethrown if caught.

Parameters:message (pyrakoon.protocol.Message) – Message to handle Returns:Server result value Return type:object See:pyrakoon.utils.process_blocking()

class pyrakoon.client.SocketClient(address, cluster_id)

Bases: object, pyrakoon.client.AbstractClient

Arakoon client using TCP to contact a cluster node

Warning:

Due to the lack of resource and exception management, this is not intended to be used in real-world code.

Parameters:

• address ((str, int)) – Node address (host & port)
• cluster_id (str) – Identifier of the cluster

connect()

Create client socket and connect to server

connected

Check whether a connection is available

_process(message)