Reverbrain wiki

Site Tools


elliptics:api-python

Python API

General usage

Initially you need to import Elliptics python module which calls elliptics. Then should create an elliptics.Logger instance. At next step, may to create an elliptics.Config instance to change default configuration. After that you can create an elliptics.Node instance and specify connections to Elliptics node. Only after all of the above you can create instance of elliptics.Session which allows to make work with the Elliptics. A more detailed description and features of the classes and the methods are presented below.

Elliptics classes

The API contains the following classes.

The name of the class Description
elliptics.Logger The elliptics.Logger class is file logger for elliptics client.
elliptics.Config The elliptics.Config class can be used to change the default settings in created elliptics.Node.
elliptics.Address The elliptics.Address class can used for the string representation of the address.
elliptics.Node The elliptics.Node class is responsible for the connection with the server part.
elliptics.Error The elliptics.Error class is the basic exception.
elliptics.ErrorInfo The elliptics.ErrorInfo class is the basic error.
elliptics.Id The elliptics.Id class is used as a key in Elliptics.
elliptics.IoAttr The elliptics.IoAttr class is designed to specify or get the attributes of the write/read operations.
elliptics.io_flags The elliptics.io_flags enum allows you to specify the scheme of the input/output operations.
elliptics.exceptions_policy The elliptics.exceptions_policy enum allows you to specify the scheme of how exceptions should be thrown by elliptics.Session operations.
elliptics.command_flags The elliptics.command_flags enum allows you to set flags that affects to the execution of operations.
elliptics.iterator_flags The elliptics.iterator_flags enum allows you to set flags that affects to the node iteration.
elliptics.iterator_types The elliptics.iterator_types enum allows you to set type of iteration.
elliptics.IteratorRange The elliptics.IteratorRange allows you to set key ranges for filtering keys while iteration.
elliptics.AsyncResult The elliptics.AsyncResult class produces an asynchronous execution of the operations.
elliptics.Time The elliptics.Time is used to specify a timestamp.
elliptics.Range The elliptics.Range is used for queries that need to access a selected part of the object based on the keys.
elliptics.RouteList The elliptics.RouteList class is used for representing elliptics route table.
elliptics.SessionStatus The elliptics.SessionStatus class is used for changing status on Elliptics node.
elliptics.Session:
lookup operations
read operations
write operations
remove operations
node iteration
index operation
statistics
The elliptics.Session class is an object to perform operations with Elliptics.
Operations for determining which node are responded for the key and/or requesting the key meta info.
Operations for retrieving data from Elliptics by the key and/or io attributes.
Operations for writing data to Elliptics.
Operations for removing datas and keys from Elliptics.
Allows to retrieve keys with or without meta data and make some filtering on it.
Operations for interact with Elliptics secondary indexes.
Operations for retrieving Elliptics node and/or cluster statistics.

elliptics.Logger

It is file logger for elliptics client.

__init__(filename, level)

Initializes file logger by parameters:
filename is a file path to logging (it may be a path at file system or stdout/stderr streams);
level is a level of verbosity.
All entries tagged less than or equal to a given level of logging will be sent to the log file.

Log level constant Description
data Very important data, practically nothing is written.
error Critical errors that substantially affect the work.
info Messages about the time of the various operations.
notice Cconsidered the first level of debugging.
debug Includes all sort of information about errors and work.

The Elliptics under load can create log files size of several gigabytes when is using the debug level.

log(level, string)

Writes a messages to the output file.
level is a level of verbosity;
string is a log message which should be written to log output.

log = elliptics.Logger("/dev/stderr", elliptics.log_level.debug)
log.log(elliptics.log_level.debug, "We've got a problem")

elliptics.Config

The elliptics.Config class can be used to change the default settings in created elliptics.Node.

Attribute Description
сookieThe parameter is specified on the servers and is designed to identify the other servers in the cluster, as well as, it parameter are using that projects from different clusters do not overlap.
wait_timeoutThe time to wait for the operation complete.
check_timeoutThe timeout for pinging node.
io_thread_numNumber of IO threads in processing pool.
nonblocking_io_thread_numNumber of IO threads in processing pool dedicated to nonblocking operations.
net_thread_numNumber of threads in network processing pool.
flags Bit set of elliptics.config_flags.
client_prio IP priority.

Bit flags which could be used at elliptics.Config.flags.

elliptics.config_flags Description
no_route_list Do not request route table from remote nodes.
mix_stats Mix states according to their weights before reading data.
no_csum Globally disable checksum verification and update.
randomize_states Randomize states for read requests.
cfg = elliptics.Config()
cfg.cookie = "0123456789012345678901234567890123456789"
cfg.wait_timeout = 60
cfg.check_timeout = 60
cfg.io_thread_num = 1
cfg.net_thread_num = 1
cfg.nonblocking_io_thread_num = 1

elliptics.Address

Address wrapper. Resolves host names into IP addresses. Also parses string representation of the address.

__init__(host, port, [family=0, [group_id=0]])

Initializes elliptics.Address transmitted by values of host, port and optional family, group_id.
host is a parameter that specifies a IP address or host name;
port is a parameter that specifies a port to connect;
family is a parameter which specifies the type version of IP, for IPv4 a setting of 2, for IPv6 - 10;
group_id is a parameter that indicates in which group contains in Elliptics.

address = elliptics.Address(host='host.com', port=1025,
                            family=2, group_id=0)

from_host_port(addr_str, [group_id=0])

This is a static method that initializes the instance elliptics.Address through transmitted addr_str string and optional parameter group_id.
addr_str is a string address in the format - “host:port”;
group_id is a parameter that indicates in which group contains in Elliptics.

address = elliptics.Address.from_host_port(addr_str='host.com:1025',
                                           group_id=0)

from_host_port_family(addr_str, [group_id=0])

This is a static method that initializes the instance elliptics.Address through transmitted addr_str string and optional parameter group_id.
addr_str is a string address in the format - “host:port:family”;
group_id is a parameter that indicates in which group contains in Elliptics.

address = elliptics.Address.from_host_port_family(addr_str='host.com:1025:2',
                                                  group_id=0)

elliptics.Node

The elliptics.Node class represents a connection with Elliptics. This class is responsible for checking timeouts, maintenance and checking of communication. To initialize the elliptics.Node class to be transmitted the elliptics.Logger and the elliptics.Config classes. Then you may add connections to servers and start to communicate with them.

__init__(logger)

The elliptics.Node will be created with default configuration.
logger is a logger object of elliptics.Logger.

log = elliptics.Logger("/dev/stderr", elliptics.log_level.error)
node = elliptics.Node(log)

__init__(logger, config)

The elliptics.Node initialization with using the logger object and configuration provided by config.
logger is a logger object of elliptics.Logger;
config is a configuration for future elliptitics.Node. Should be instance of the elliptics.Config class.

log = elliptics.Logger("/dev/stderr", elliptics.log_level.debug)
cfg = elliptics.Config()
cfg.cookie = "0123456789012345678901234567890123456789"
cfg.config.wait_timeout = 60
cfg.config.check_timeout = 60
 
node = elliptics.Node(log, cfg)

add_remote(host, port, [family=AF_INET])

This method is used to add connection with server by the host, the port and the family. It is necessary to specify several entry points for fault tolerance.
host is a parameter that specifies a IP address or host name;
port is a parameter that specifies a port to connect;
family is a parameter which specifies the type version of IP, for IPv4 a setting of 2, for IPv6 - 10.

try:
    node.add_remote(addr="localhost", port=1025)
except Exception as e:
    print "Couldn't connect: {0}".format(e)
try:
    node.add_remote(addr="localhost", port=1026, family=2)
except Exception as e:
    print "Couldn't connect: {0}".format(e)

add_remote(address)

This is used to add connection with server by the address. It is necessary to specify several entry points for fault tolerance.
address is a string in format: “host:port:family” or elliptics.Address object.

try:
    node.add_remote("some_host:1040:10")
except Exception as e:
    print "Couldn't connect: {0}".format(e)
try:
    address = elliptics.Address.from_host_port_family("some_host:1040:10:2")
    node.add_remote(address)
except Exception as e:
    print "Couldn't connect: {0}".format(e)

set_timeouts(wait_timeout, check_timeout)

The set_timeouts method allow you to override at runtime the previous values for timeouts. The set_timeouts method has the following parameters:
wait_timeout is the time to wait for the operation complete;
check_timeout sets the wait for a response from the host. If it stops responding then rebuild the routing table.

node.set_timeouts(wait_timeout=5, check_timeout=50)

elliptics.Error

The elliptics.Error class is the basic exception, which contains a message and a code of accident.

message()

It returns a description of the error. Besides this class, there are two types of specific errors:
– class elliptics.NotFoundError is reported about the operations on the non-existent object;
– class elliptics.TimeoutError means that the operation was not completed for the timeout.

Notes:
All of these exceptions can be thrown by any elliptics.Session methods, which perform read, write, and send the data to Elliptics.

elliptics.ErrorInfo

Basic error for Elliptics.

message()

Returns description of the error.

print error
print error.message()

code()

Returns code of the error.

print error.code()

elliptics.Id

The Elliptics is the key/value storage and the elliptics.Id class is used as these keys. The elliptics.Id class is used for the operation of writing, reading, working with indexes or queries statistics.

__init__(key)

Initializes elliptics.Id by a string key. In all operations will be taken hash sum of this string by the sha512 algorithm. By default, if the identifier is initialized with a string constant it need to be converted before comparation. To do this, run the Session.transform method. The Session.transform method converts embedded string constant in the elliptics.Id and saves it. Then you can compare the values ​​of elliptics.Id.

id = elliptics.Id(key='some key')

__init__(key, group_id)

It initialized with the key and the group.
key is a list of 64 integers from [0, 255], which represents 512 bit key;
group_id is the Elliptics group identificator from which key is considered.

id = elliptics.Id(key=[0] * 64, group_id = 1)

The __str__ and the __repr__ methods are using to get a different string representation of elliptics.Id.

elliptics.IoAttr

The elliptics.IoAttr class is designed to specify or get the IO attributes of the write/read operations. It can be used to replace the key for read operations.

Attribute Description
id elliptics.Id of object on which an operation is executed.
flags It is a bit flag set, which would be used to perform operation. It consists from elliptics.io_flags
offsetThis allows you to set an offset that you want to perform the operation
sizeIt is a size of data. For write operations it will be the size of data that must be written. For read operations it will be the size of data that must be read. The return value of size in the reading operations may differ from, as the actual size may be different
timestampIt is a timestamp of object creation, which is stored in Elliptics, it can indicate or initialize the parameter
user_flagsIt is a flags, definable by the user
io_attr = elliptics.IoAttr()
io_attr.parent = elliptics.Id('some key')
io_attr.id = elliptics.Id('some key2')
io_attr.timestamp = elliptics.Time.now()
io_attr.start = 200
io_attr.num = 5000
io_attr.user_flags = 123456789
io_attr.flags = elliptics.io_flags.cache | elliptics.io_flags.append
io_attr.offset = 10
io_attr.size = len('object data')

elliptics.io_flags

The elliptics.io_flags enum allows you to specify the scheme of the input/output operations.

The name of the flag Description
append Object will be written at the end of the object after the available data. If the specified key does not exist, then the data will be written to the beginning
cache The operation will be performed using the cache and the effect will be synced to backend after sync_timeout which is specified in server config
cache_only The operation will be performed only in the cache. You can specify the lifetime of the object, at the expiration of the lifetime it is removed
prepare, plain_write, commit Allows you to write the object under the scheme - allocate space for object, then write it in parts, and then commit
nosum Indicates that the file does not need to generate and store the hash sum of object
nodata The operation or the result of the operation should not contain data (for reading operation returns size)
overwrite It is used to overwrite the actual data
default The default value overwrites the data by specified offset and size
flags = elliptics.io_flags.cache | elliptics.io_flags.cache_only

elliptics.exceptions_policy

The elliptics.exceptions_policy enum allows you to specify the scheme of how exceptions should be thrown by elliptics.Session operations.

Exeption policy constant Description
no_exceptions No exception will be thrown
throw_at_start The exception will be thrown when the operation is started
throw_at_wait The exception will be thrown when all results of the operation is available
throw_at_get The exception will be thrown when the next result of the operation is available
throw_at_iterator_end The exception will be thrown after the iterator has reached last result
default_exceptions It is the union of follow flags: throw_at_wait, throw_at_get, throw_at_iterator_end
policy = elliptics.exceptions_policy.throw_at_start | elliptics.exceptions_policy.throw_at_wait

elliptics.command_flags

The elliptics.command_flags enum allows you to set flags that affects to the execution of operations.

The name of the flag Description
default The key is locked before performing an operation and unlocked when an operation will done
direct Request is sent to the specified Node bypassing the DHT ring
nolock Server will not check the key is locked and will not lock it during this transaction. The operation will be handled in separated io thread pool

elliptics.iterator_flags

The elliptics.iterator_flags enum allows you to set flags that affects to the node iteration.

The name of the flag Description
default There no filtering should be while iteration. All keys will be presented
data Iteration should also sends objects datas
key_range Key ranges should be used for filtering keys on the node while iteration
ts_range Time range should be used for filtering keys on the node while iteration
flags = elliptics.iterator_flags.key_range | elliptics.iterator_flags.ts_range

elliptics.iterator_types

The elliptics.iterator_types enum allows you to set type of iteration.

The name of the flag Description
disk Iterator saves data chunks (index/metadata + (optionally) data) locally on server to $root/iter/$id instead of sending chunks to client
network Iterator sends data chunks to client

elliptics.IteratorRange

The elliptics.IteratorRange allows to set key ranges for filtering keys while iteration.

elliptics.IteratorRange attribute Description
key_beging elliptics.Id which sets start of the key range
key_end elliptics.Id which sets end of the key range
range = elliptics.IteratorRange()
range.key_begin = elliptics.Id([0] * 64, 1)
range.key_end = elliptics.Id([255] * 64, 1)
 
range2 = elliptics.IteratorRange()
range2.key_begin = elliptics.Id("key A")
range2.key_end = elliptics.Id("key B")

elliptics.AsyncResult

The elliptics.AsyncResult class is a future, which is returned by most methods of the elliptics.Session and produces an asynchronous execution of these operations. This class is used to wait for the results of the operation, to verify successful completion of the operation and receive errors.

__iter__()

Used to iterate results from the elliptics.AsyncResult. For example, the __ iter__() allows you to go through the results of the asynchronous write operation in several groups. In this case, the result will be returned upon receipt and the data can come in any order.

for result in async_result:
    print 'The operation result: {0}'.format(result)

connect(result_handler, final_handler)

Allows you to assign two callbacks for operation results.
result_handler will be called for each individual result. This result will be passed to result_handler;
final_handler will be called when the operation has been completed. The error of execution will be passed to final_handler.

def rhandler(result):
    print 'The operation result:', result
 
def fhandler(error):
    if error.code == 0:
        print 'The operation successfully completed'
    else:
        print 'The operation failed: {0}'.format(error)
async_result.connect(rhandler, fhandler)

connect(handler)

Assigns all results callback.
handler will be called when the operation has been completed and all results are available. List of results and error of execution will be passed to the callback. It takes two parameters: the list of results and error information (elliptics.Error).

def handler(results, error):
    if error.code != 0:
        print 'The operation failed: {0}'.format(error)
    else:
        print 'The operation results: {0}'.format(results)
async_result.connect(handler)

elapsed_time()

Returns elliptics.Time spent executing the operation.

async_result.wait()
time = async_result.elapsed_time()
print 'The operation tooks {0} seconds and {1} nanoseconds'.format(time.tsec, time.tnsec)

get()

Performs waits for all results and returns a list of results.

results = async_result.get()
first_result = results[0]

ready()

Returns whether the operation has completed.

if async_result.read():
    print 'The operation has been completed'
else:
    print 'The operation hasn't been completed'

successful()

Returns whether the operation has been succeeded. Throws exception if the operation hasn't been completed.

try:
    print 'Operation successes:', async_result.successful
except:
    print 'Operation hasn't been completed'
    async_result.wait()
    print 'Operation successes:', async_result.successful

error()

Returns information about errors that occurred during the execution of operation. Throws exception if the operation hasn't been completed.

error = async_result.error()
if error.code != 0:
    print 'The operation failed: {0}'.format(error)
else:
    print 'The operation results: {0}.format(results)

wait()

Waits for the operation complete.

async_result.wait()
results = async_result.get()

elliptics.Time

The elliptics.Time is used to specify or to receive a timestamp. This class can be used for comparison of files, for example, to determine a newer or an older file. If the timestamp is not specified at the time of writing, its value will be set to the current time by default.

Attribute Description
tsec Number of seconds since January 1, 1970
tnsec Number of nanoseconds

now()

Class method which returns elliptics.Time for the current moment.
The basic operation is compare and initialization unixtime, dnettime. The return value is not zero at the reading operations in Elliptics since version 2.24.

print 'Now is:', elliptics.Time.now()
time = elliptics.Time.now()
print 'There are {0} seconds and {1} nanoseconds has been passed since January 1, 1970'
      .format(time.tsec, time.tnsec)

elliptics.Range

This class is used for queries the area of keys.

Attribute Description
start This is the key that represents the starting point of the area
offset This allows you to set an offset that you want to perform the operation
size It is a size of data
ioflags Sets the elliptics.io_flags
group_id Sets the group ID
limit_start Sets the number of object to be skipped
limit_num Sets the number of object to be transferred

elliptics.RouteList

This class is used for representing elliptics route table.

filter_by_address(address)

Returns route records filtered by address

routes = routes.filter_by_address(Address.from_host_port_family('host.com:1025:2'))

filter_by_group_id(group_id)

Returns route records filtered by group_id

routes = routes.filter_by_group_id(1)

groups()

Returns list of group_ids which are presented in Elliptics cluster

groups = routes.groups()

addresses()

Returns list of addresses which are exists in route table

addresses = routes.addresses()

addresses_with_id()

Returns list of tuples. Each tuple contains unique address and elliptics.Id of the address

addresses_with_id = routes.addresses_with_id()

get_address_group_id(address)

Returns group_id of address

group_id = routes.get_address_group_id(Address.from_host_port_family('host.com:1025:2'))

get_address_id(address)

Returns elliptics.Id of the address

id = routes.get_address_id(Address.from_host_port_family('host.com:1025:2'))

get_address_ranges(address)

Returns key ranges which are belonged to the address

ranges = routes.get_address_ranges(Address.from_host_port_family('host.com:1025:2'))

percentages()

Returns percentage distribution keys by key ranges between nodes

print routes.percentages()

elliptics.SessionStatus

This class is used for changing status on Elliptics node

elliptics.SessionStatus attribute Description
nflags nflags which should be set on the Elliptics node
status_flags status_flags which should be set on the Elliptics node
log_level Log level which should be set on the Elliptics node
elliptics.status_flags Description
change Elliptics node status - if set, status will be changed
exit Elliptics node should exit
ro Ellipitcs node goes ro/rw

elliptics.Session

This class is designed to perform different operations such as:
lookup operations,
read operations,
write operations,
remove operations,
node iteration,
index operation,
statistics.

__init__(node)

Initializes elliptics.Session for specified elliptics.Node.

session = elliptics.Session(node)

set_namespace(namespace)

You can specify the namespace for the elliptics.Session. This feature allows you to share a single storage between services. And each service which uses own namespace will have own independent space of keys.
namespace is a string namespace.

session.set_namespace("Hello, World! Application Namespace")

groups

Allows to specify or get Elliptics groups with which elliptics.Session should work. The groups are a replica in Elliptics. All transactions for the session will be executed by specified groups.

print session.groups #outputs current groups
session.groups = [1, 2, 3]

cflags

Allows to specify or get elliptics.command_flags.

session.cflags = elliptics.command_flags.default

ioflags

Allows to specify or get elliptics.io_flags.

session.ioflags = elliptics.io_flags.append | elliptics.io_flags.cache

user_flags

Allows to specify or get custom user-defined flags.

session.user_flags = 12345

set_direct_id(addr, port, family)

Makes elliptics.Session works with only specified node directly.
host is a parameter that specifies a IP address or host name;
port is a parameter that specifies a port to connect;
family is a parameter which specifies the type version of IP, for IPv4 a setting of 2, for IPv6 - 10.

session.set_direct_id(addr="host.com", port = 1025, family=2)

get_direct_id()

Returns elliptics.Id of the node that this session was directed to.

id = session.get_direct_id()

timestamp

You can specify a timestamp for the elliptics.Session. Then it will be used for all operations.

session.timestamp = elliptics.Time.now()

timeout

Allows to specify or get timeout value which overrides the wait timeout from elliptics.Node.

session.timeout = 10

exceptions_policy

Allows to specify or get scheme of how exceptions should be thrown. it should consist of elliptics.exceptions_policy.

session.exceptions_policy = elliptics.exceptions_policy.no_exceptions

transform(data)

Transforms data to elliptics.Id and also allow to transform internal string representation of elliptics.Id.
data - data which should be transformed. It could be string or elliptics.Id.

id = session.transform('some data')
new_id = elliptics.Id('some data')
new_id = session.transform(new_id)

routes

Return current route table as elliptics.RouteList

routes = session.routes
print routes

update_status(id, status)

Allow to change status of node. – id - elliptics.Id of the node which status should be changed – status - elliptics.SessionStatus which should be set on the node

id = session.routes.get_address_id(Address.from_host_port('host.com:1025'))
new_status = elliptics.SessionStatus()
new_status.nflags = elliptics.status_flags.change
new_status.log_level = elliptics.log_level.error
session.update_status(id, new_status)

update_status(address, status)

Allow to change status of node. – address - elliptics.Address of the node which status should be changed – status - elliptics.SessionStatus which should be set on the node

new_status = elliptics.SessionStatus()
new_status.nflags = elliptics.status_flags.change
new_status.log_level = elliptics.log_level.error
session.update_status(Address.from_host_port('host.com:1025'), new_status)

trace_id

Allows to specify debug number which would be printed in logs generated by executing operation by the elliptics.Session. This number will be printed in both logs server and client. If it has elliptics.trace_bit then all logs generated by the elliptics.Session operations will be printed with ignoring logger verbosity level.

session.trace_id = 123456
session.trace_id = 123456 | elliptics.trace_bit

Lookup operations

lookup(key)

Provides information of the key, for example, where it is stored. It returns the elliptics.AsyncResult, which in itself contains the elliptics.LookupResultEntry.
key is a value of elliptics.Id or a string representation of the ID.

result = session.lookup('looking up key')
lookups = []
try:
    lookups = result.get()
except Exception as e:
    print 'Lookup is failed: ', e
for lookup in lookups:
    print 'The \\'looking up key\\' exists on node:', lookup.address, '. It has:'
    print 'size:', lookup.size
    print 'offset', lookup.offset
    print 'timestamp:', lookup.timestamp
    print 'filepath:', lookup.filepath
    print 'checksum:', lookup.checksum
    print 'error:', lookup.error

lookup_address(key, group_id)

Returns address of node from specified group_id which is responsible for a specific key.
key is a value of elliptics.Id or a string representation of the ID;
group_id is a Elliptics group identificator where the node should be found.

address = session.lookup_address('looking up key', 1)
print '\'looking up key\' should lives on node:, address

Read operations

read_file(key, filename, [offset=0, [size=0]])

Reads object by key and writes it to the specified file. This operation is asynchronous with nothing returns. The input parameters are:
key - a value of elliptics.Id or a string representation of the ID;
filename - a string path to the file where read object will be written;
offset - an offset from which object data should be read;
size - a number of bytes to be read. If the size equal 0 then the full object will be read.

session.read_file('key', '/path/to/file', 0, 0)
session.read_file('key1', '/path/to/file1', 10, 100)

read_data(key, [offset=0, [size=0]])

This is the read data operation by key. Returns elliptics.AsyncResult which provides access to read object. The input parameters are:
key - a value of elliptics.Id or a string representation of the ID;
offset - an offset from which object data should be read;
size - a number of bytes to be read. If the size equal 0 then the full object will be read.

read_result = None
 
try:
   result = session.read_data('key', 0, 0)
   read_result = result.get()[0]
except Exception as e:
   print 'Read has been failed:', e
 
if read_result:
    print 'Read key: \'key\':'
    print 'data:', read_result.data
    print 'timestamp:', read_result.timestamp
    print 'size:', read_result.size
    print 'offset:', read_result.offset
    print 'user_flags:', read_result.user_flags
    print 'flags:', read_result.flags

read_data_from_groups(key, groups, [offset=0, [size=0]])

This is the read data operation with specifying of the groups. Returns elliptics.AsyncResult. The input parameters are:
key - a value of elliptics.Id or a string representation of the ID;
groups - groups from which object should be read (groups specified in the elliptics.Session class will be ignored);
offset - an offset from which object data should be read;
size - a number of bytes to be read. If the size equal 0 then the full object will be read.

read_result = None
 
try:
    result = session.read_data_from_groups('key', [1,2,3], 0, 0)
    read_result = result.get()[0]
except Exception as e:
    print 'Read has been failed:', e
 
if read_result:
    print 'Read key: \'key\':'
    print 'data:', read_result.data
    print 'timestamp:', read_result.timestamp
    print 'size:', read_result.size
    print 'offset:', read_result.offset
    print 'user_flags:', read_result.user_flags
    print 'flags:', read_result.flags

read_latest(key, [offset=0, [size=0]])

This operation is similar the read_data(), but the read_latest() requests a timestamp of the object in all groups and reads the newer object. Returns elliptics.AsyncResult. The input parameters are:
key - a value of elliptics.Id or a string representation of the ID;
offset - an offset from which object data should be read;
size - a number of bytes to be read. If the size equal 0 then the full object will be read.

read_result = None
try:
    result = session.read_latest('key', 0, 0)
    read_result = result.get()[0]
except Exception as e:
    print 'Read has been failed:', e
if read_result:
    print 'Read key: \'key\':'
    print 'data:', read_result.data
    print 'timestamp:', read_result.timestamp
    print 'size:', read_result.size
    print 'offset:', read_result.offset
    print 'user_flags:', read_result.user_flags
    print 'flags:', read_result.flags

read_data_range(range)

The operation to read all the keys from area. Returns elliptics.AsyncResult.
range - elliptics.Range which specifies keys area and IO attributes.

range = elliptics.Range()
range.group_id = 1
range.start = elliptics.Id([0] * 64, 1)
range.end = elliptics.Id([255]*64, 1)
result = session.read_data_range(range)
for read_result in result:
    print 'Read key:\'',  read_result.id, '\''
    print 'data:', read_result.data
    print 'timestamp:', read_result.timestamp
    print 'size:', read_result.size
    print 'offset:', read_result.offset
    print 'user_flags:', read_result.user_flags
    print 'flags:', read_result.flags

bulk_read(keys_or_io_attrs)

The operation for reading a several keys. The input parameters are the iterable object which contains string keys or elliptics.Id's or elliptics.IoAttr's which will be read. When using elliptics.IoAttr will be transferred to values of the parameters: key, offset, size. When using a string representation of the ID or elliptics.Id will be read all of the data. Returns elliptics.AsyncResult.

keys = []
 
keys.append('key')
keys.append(elliptics.Id('key1'))
 
io = elliptics.IoAttr()
io.id = elliptics.Id('key3')
io.offset = 10
keys.append(io)
 
result = session.bulk_read(keys)
for read_result in result:
    print 'Read key:\'',  read_result.id, '\''
    print 'data:', read_result.data
    print 'timestamp:', read_result.timestamp
    print 'size:', read_result.size
    print 'offset:', read_result.offset
    print 'user_flags:', read_result.user_flags
    print 'flags:', read_result.flags

All read operations returns elliptics.AsyncResult. AsyncResult for read operation provides elliptics.ReadResultEntry's as result of operation.

elliptics.ReadResultEntry attributes Description
data Data which has been read
id elliptics.Id of read object
timestamp The timestamp for read object
user_flags The user flags for read object
flags The internal flags
offset The offset from which the object was read
size The size of the data
address The Node address from which the data has been read
error elliptics.Error

Write operations

write_file(key, filename, [offset=0, [local_offset=0, [size=0]]])

Writes an object by the key and the data is read from the specified file. The input parameters are:
key - a value of elliptics.Id or a string representation of the ID or a value of elliptics.IoAttr;
filename - a string path to the file;
offset - an offset with which data should be written;
local_offset - an offset with which data should be read from filename;
size - a data size in bytes to be read from filename and to be written. If it equal to 0 then full size will be read and written.

session.write_file('key', '/path/to/file')

write_data(key, data, [offset=0])

Writes by the key and the offset. The input parameters are:
key - a value of elliptics.Id, a string representation of the ID or a value of elliptics.IoAttr;
data - a data to be written;
offset - an offset with which data should be written.

write_results = []
try:
    result = session.write_data('key', 'key_data')
    write_results = result.get()
except Exception as e:
    print 'Write data is failed:', e
 
for write_result in write_results:
    print 'The key:\'key\' has been written:'
    print 'node:', write_result.address
    print 'checksum:', write_result.checksum
    print 'offset:', write_result.offset
    print 'size:', write_result.size
    print 'timestamp:', write_result.tiemstamp
    print 'filepath:', write_result.filepath

write_data(key, data, [offset=0, [chunk_size=0]])

Writes data splitted to pieces of chunk_size. Used to write a large-volume data. Returns elliptics.AsyncResult. The input parameters are:
key - a value of elliptics.Id, a string representation of the ID or a value of elliptics.IoAttr;
data - a data to be written;
offset - an offset with which data should be written;
chunk_size - a size of a single piece of data to be written.

write_results = []
try:
    result = session.write_data('key', 'key_data', 0, 3)
    write_results = result.get()
except Exception as e:
    print 'Write data is failed:', e
 
for write_result in write_results:
    print 'The key:\'key\' has been written:'
    print 'node:', write_result.address
    print 'checksum:', write_result.checksum
    print 'offset:', write_result.offset
    print 'size:', write_result.size
    print 'timestamp:', write_result.tiemstamp
    print 'filepath:', write_result.filepath

write_cas(key, data, old_csum, [remote_offset=0])

The write operation with testing the hash sum on the server side. Returns elliptics.AsyncResult. The input parameters are:
key - a value of elliptics.Id, a string representation of the ID or a value of elliptics.IoAttr;
data - a data to be written;
old_csum - a hash sum as the elliptics.Id;
remote_offset - an offset that you want to perform the operation.

write_results = []
csum = elliptics.Id()
try:
    result = session.write_cas('key', 'key_data', csum, 0)
    write_results = result.get()
except Exception as e:
    print 'Write data is failed:', e
 
for write_result in write_results:
    print 'The key:\'key\' has been written:'
    print 'node:', write_result.address
    print 'checksum:', write_result.checksum
    print 'offset:', write_result.offset
    print 'size:', write_result.size
    print 'timestamp:', write_result.tiemstamp
    print 'filepath:', write_result.filepath

write_cas(key, converter, [remote_offset, [count]])

The write operation with the transfer callback, in which will be transferred to the current data stored on the key. The input parameters are:
key - a value of elliptics.Id, a string representation of the ID or a value of elliptics.IoAttr;
converter - a callback converter, which takes data of current object and returns data which should be written;
remote_offset - an offset with which data should be written;
count - a number of attempts.

write_results = []
csum = elliptics.Id()
try:
    result = session.write_cas('key', lambda x: '___' + x + '___')
    write_results = result.get()
except Exception as e:
    print 'Write data is failed:', e
 
for write_result in write_results:
    print 'The key:\'key\' has been written:'
    print 'node:', write_result.address
    print 'checksum:', write_result.checksum
    print 'offset:', write_result.offset
    print 'size:', write_result.size
    print 'timestamp:', write_result.tiemstamp
    print 'filepath:', write_result.filepath

write_prepare(key, data, remote_offset, psize)

Tells Elliptics to allocate space of psize for future object by key and to write part of object data by remote_offset. The write_prepare(key, data, remote_offset, psize) is a part of prepare-write-commit scheme where we allocate space at first then execute several writes in allocated space and then complete the object. The input parameters are:
key - a value of elliptics.Id, a string representation of the ID or a value of elliptics.IoAttr;
data - a data to be written;
remote_offset - an offset with which data should be written;
psize - amount of space to be reserved.

write_results = []
try:
    result = session.write_prepare('key', 'first_part', 0, 1024)
    write_results = result.get()
except Exception as e:
    print 'Write data is failed:', e
 
for write_result in write_results:
    print 'The key:\'key\' has been written:'
    print 'node:', write_result.address
    print 'checksum:', write_result.checksum
    print 'offset:', write_result.offset
    print 'size:', write_result.size
    print 'timestamp:', write_result.tiemstamp
    print 'filepath:', write_result.filepath

write_ plain(key, data, remote_offset)

Writes data to the space which was allocated earlier by write_prepare. The write_plain(key, data, remote_offset) is a part of prepare-write-commit scheme where we allocate space at first then execute several writes in allocated space and then complete the object. The input parameters are:
key - a value of elliptics.Id, a string representation of the ID or a value of elliptics.IoAttr;
data - a data to be written;
remote_offset - an offset with which data should be written.

write_results = []
try:
    offset = len('first_part')
    result = session.write_plain('key', 'second_part', offset)
    write_results += result.get()
 
    offset += len('second_part')
    result = session.write_plain('key', 'third_part', offset)
    write_results += result.get()
 
    offset += len('third_part')
    result = session.write_plain('key', 'fourth_part', offset)
    write_results += result.get()
except Exception as e:
    print 'Write data is failed:', e
 
for write_result in write_results:
    print 'The key:\'key\' has been written:'
    print 'node:', write_result.address
    print 'checksum:', write_result.checksum
    print 'offset:', write_result.offset
    print 'size:', write_result.size
    print 'timestamp:', write_result.tiemstamp
    print 'filepath:', write_result.filepath

write_commit(key, data, remote_offset, csize)

Makes final write to space which was allocated earlier by write_prepare and finalizes the object by truncating it by csize.The write_commit(key, data, remote_offset, csize) is a part of prepare-write-commit scheme where we allocate space at first then execute several writes in allocated space and then complete the object. The input parameters are:
key - a value of elliptics.Id, a string representation of the ID or a value of elliptics.IoAttr;
data - a data to be written;
remote_offset - an offset with which data should be written;
csize - a total size of the data by which the object should be truncated.

write_results = []
try:
    offset += len('first_part' + 'second_part' + 'third_part' + 'fourth_part')
    csize = len('first_part' + ... + 'last_part')
    result = session.write_commit('key', 'last_part', offset, csize)
    write_results += result.get()
except Exception as e:
    print 'Write data is failed:', e
 
for write_result in write_results:
    print 'The key:\'key\' has been written:'
    print 'node:', write_result.address
    print 'checksum:', write_result.checksum
    print 'offset:', write_result.offset
    print 'size:', write_result.size
    print 'timestamp:', write_result.tiemstamp
    print 'filepath:', write_result.filepath

write_cache(key, data, timeout)

Writes the data to the Elliptics cache and sets the object's lifetime to timeout. The input parameters are:
key - a value of elliptics.Id, a string representation of the ID or a value of elliptics.IoAttr;
data - a data to be written;
timeout - time after which the object could be removed from the Elliptics cache.

write_results = []
try:
    result = session.write_cache('key', 'key_data', 60)
    write_results = result.get()
except Exception as e:
    print 'Write data is failed:', e
 
for write_result in write_results:
    print 'The key:\'key\' has been written:'
    print 'node:', write_result.address
    print 'checksum:', write_result.checksum
    print 'offset:', write_result.offset
    print 'size:', write_result.size
    print 'timestamp:', write_result.tiemstamp
    print 'filepath:', write_result.filepath

bulk_write(datas)

Simultaneously writes several objects. Returns elliptics.AsyncResult. The input parameters is:
datas - iterable object which contains a tuple of key and data: key is a value from the elliptics.Id, or a string representation of the ID or a value from elliptics.IoAttr and data is elliptisc.Data.

data = []
datas.append(('key', 'key_data'))
datas.append((elliptics.Id('key1'), 'key1_data'))
 
io = elliptics.IoAttr()
io.id = elliptics.Id('key3')
io.offset = 10
datas.append(io, 'key3_data')
 
write_results = []
try:
    result = session.bulk_write(datas)
    write_results = result.get()
except Exception as e:
    print 'Write data is failed:', e
 
for write_result in write_results:
    print 'The data has been written:'
    print 'node:', write_result.address
    print 'checksum:', write_result.checksum
    print 'offset:', write_result.offset
    print 'size:', write_result.size
    print 'timestamp:', write_result.tiemstamp
    print 'filepath:', write_result.filepath

All write operations returns elliptics.AsyncResult which provides elliptics.LookupResultEntry as a result of write.

elliptics.LookupResultEntry attributes Description
size Size of the data which has been written
offset An offset with which the object has been written
timestamp The object timestamp
cheksum A hash sum of the object
filepath A path to the block where data is stored
address The Node address where the data has been written
error Message of errors in work

Remove operation

remove(key)

Removes object by the key. It returns elliptics.AsyncResult. The input parameter is:
key - a value of elliptics.Id, a string representation of the ID or a value of elliptics.IoAttr.

try:
    result = session.remove('key')
    remove_results = result.get()
    for remove_result in remove_results:
        print 'The key: \'key\' has been removed:'
        print 'node:', remove_result.address
        print 'status:', remove_result.status
        print 'size:', remove_result.size
        print 'data:', remove_result.data

remove_data_range(key_range)

Removes an area of the object for the given keys. It returns elliptics.AsyncResult. The input parameter is:
key_range - an area of keys - elliptics.Range.

try:
    range = elliptics.Range()
    range.start = elliptics.Id([0] * 64, 1)
    range.end = elliptics.Id([255] * 64, 1)
 
    result = session.remove_data_range(range)
    remove_results = result.get()
    for remove_result in remove_results:
        print 'The key has been removed:'
        print 'node:', remove_result.address
        print 'status:', remove_result.status
        print 'size:', remove_result.size
        print 'data:', remove_result.data

All remove operation reterns elliptics.AsyncResult which provides elliptics.CallbackResultEtry.

elliptics.CallbackResultEtry attributes Description
is_valid The validity status
status The current status
data Data of removed object
size The size of data
error The messages of errors in work;
address Elliptics node address where the object has been removed

Node iteration

The iteration operation is used to get all the keys with or without data from specified node. The keys can be filtered by key range and/or time range.

start_iterator(id, ranges, type, flags, time_begin, time_end)

Starts iterator on the Elliptics node by key. Returns elliptics.AsyncResult.
id - elliptics.Id of the node where iteration should be executed;
ranges - list of elliptics.IteratorRange by which keys on the node should be filtered;
type - elliptics.iterator_types;
flags - bit set of elliptics.iterator_flags;
time_begin - start of time range by which keys on the node should be filtered;
time_end - end of time range by which keys on the node should be filtered.

flags = elliptics.iterator_flags.key_range
type = elliptics.iterator_types.network
id = session.routes.get_address_id(Address.from_host_port('host.com:1025'))
range = elliptics.IteratorRange()
range.key_begin = elliptics.Id([0] * 64, 1)
range.key_end = elliptics.Id([255] * 64, 1)
iterator = session.start_iterator(id,
                                  [range],
                                  type,
                                  flags,
                                  elliptics.Time(0,0),
                                  elliptics.Time(0,0))
 
for result in iterator:
    if result.status != 0:
        raise AssertionError("Wrong status: {0}".format(result.status))
 
    print ('node: {0}, key: {1}, flags: {2}, ts: {3}/{4}, data: {5}'
           .format(node,
                   result.response.key,
                   result.response.user_flags,
                   result.response.timestamp.tsec,
                   result.response.timestamp.tnsec,
                   result.response_data))

pause_iterator(id, iterator_id)

Pauses iterator on the Elliptics node started by start_iterator(). Returns elliptics.AsyncResult.
id - elliptics.Id of the node where iteration should be paused;
iterator_id - integer ID of iterator which should be paused.

id = session.routes.get_address_id(Address.from_host_port('host.com:1025'))
iterator = session.pause_iterator(id, iterator_id)
iterator.wait()

continue_iterator(id, iterator_id)

Continues previously paused iterator on the Elliptics node. Returns elliptics.AsyncResult.
id - elliptics.Id of the node where iteration should be continued;
iterator_id - integer ID of iterator which should be continued.

id = session.routes.get_address_id(Address.from_host_port('host.com:1025'))
iterator = session.continue_iterator(id, iterator_id)
 
for result in iterator:
    if result.status != 0:
        raise AssertionError("Wrong status: {0}".format(result.status))
 
    print ('node: {0}, key: {1}, flags: {2}, ts: {3}/{4}, data: {5}'
           .format(node,
                   result.response.key,
                   result.response.user_flags,
                   result.response.timestamp.tsec,
                   result.response.timestamp.tnsec,
                   result.response_data))

cancel_iterator(id, iterator_id)

Cancels iterator on the Elliptics node. Returns elliptics.AsyncResult.
id - elliptics.Id of the node where iteration should be cancelled;
iterator_id - integer ID of iterator which should be cancelled.

id = session.routes.get_address_id(Address.from_host_port('host.com:1025'))
iterator = session.cancel_iterator(id, iterator_id)
iterator.wait()

All node iteration operation return elliptics.AsyncResult which provides elliptics.IteratorResultEntry as single result of iteration.

elliptics.IteratorResultEntry attributes Description
id Integer ID of iterator. Which can be used later for pausing and continuing iteration
status Status of iterated object if is 0 then should be skipped
response elliptics.IteratorResultResponse which provides meta information about iterated object
response_data Data of iterated object. May be empty if elliptics.iterator_flags.data hasn't been specified for iteration.
address elliptics.Address of the node from which result has been received
error elliptics.Error for iteration
elliptics.IteratorResultResponse attributes Description
key elliptics.Id of iterated object
timestamp elliptics.Time of iterated object
user_flags Custom user-defined flags of iterated object
size Size of iterated object data

Index operations

set_indexes(id, indexes, datas)

Resets id in specified indexes. The id will be removed from current indexes. Returns elliptics.AsyncResult. The input parameters are:
id - a value of elliptics.Id or a string representation of the ID;
indexes - iterable object which provides set of indexes;
datas - iterable object which provides data which will be associated with the id in the index.

indexes_result = []
try:
    result = session.set_indexes('key', ['index1', 'index2'], ['index1_key_data', 'index2_key_data'])
    indexes_result = result.get()
except Exception as e:
    print 'Set indexes has been failed:', e

set_indexes_raw(id, indexes)

Resets id in specified indexes. The id will be removed from current indexes. Returns elliptics.AsyncResult. The input parameters are:
id - a value of elliptics.Id or a string representation of the ID;
indexes - iterable object which consists of elliptics.IndexEntry.

indexes = []
indexes.append(elliptics.IndexEntry())
indexes[-1].index = elliptics.Id('index1')
indexes[-1].data = 'index1_key_data'
 
indexes.append(elliptics.IndexEntry())
indexes[-1].index = elliptics.Id('index2')
indexes[-1].data = 'index2_key_data'
 
indexes_result = []
try:
    result = session.set_indexes_raw('key', indexes)
    indexes_result = result.get()
except Exception as e:
    print 'Set indexes raw has been failed:', e

update_indexes(id, indexes, datas)

Adds the id to additional indexes and/or updates data for the id in the indexes. Returns elliptics.AsyncResult. The input parameters are:
id - a value of elliptics.Id or a string representation of the ID;
indexes - iterable object which provides set of indexes;
datas - iterable object which provides data which will be associated with the id in the index.

indexes_result = []
try:
    result = session.update_indexes('key', ['index1', 'index2'], ['index1_key_data', 'index2_key_data'])
    indexes_result = result.get()
except Exception as e:
    print 'Set indexes has been failed:', e

update_indexes_raw(id, indexes)

Adds the id to additional indexes and/or updates data for the id in the indexes. Returns elliptics.AsyncResult. The input parameters are:
id - a value of elliptics.Id or a string representation of the ID;
indexes - iterable object which consists of elliptics.IndexEntry.

indexes = []
indexes.append(elliptics.IndexEntry())
indexes[-1].index = elliptics.Id('index1')
indexes[-1].data = 'index1_key_data'
 
indexes.append(elliptics.IndexEntry())
indexes[-1].index = elliptics.Id('index2')
indexes[-1].data = 'index2_key_data'
 
indexes_result = []
try:
    result = session.update_indexes_raw('key', indexes)
    indexes_result = result.get()
except Exception as e:
    print 'Set indexes raw has been failed:', e

update_indexes_internal(id, indexes, datas)

Adds the id to additional indexes and/or updates data for the id in the indexes without updating index set for id. Returns elliptics.AsyncResult. The input parameters are:
id - a value of elliptics.Id or a string representation of the ID;
indexes - iterable object which provides set of indexes;
datas - iterable object which provides data which will be associated with the id in the index.

indexes_result = []
try:
    result = session.update_indexes_internal('key', ['index1', 'index2'], ['index1_key_data', 'index2_key_data'])
    indexes_result = result.get()
except Exception as e:
    print 'Set indexes has been failed:', e

update_indexes_internal_raw(id, indexes)

Adds the id to additional indexes and/or updates data for the id in the indexes without updating index set for id. Returns elliptics.AsyncResult. The input parameters are:
id - a value of elliptics.Id or a string representation of the ID;
indexes - iterable object which consists of elliptics.IndexEntry.

indexes = []
indexes.append(elliptics.IndexEntry())
indexes[-1].index = elliptics.Id('index1')
indexes[-1].data = 'index1_key_data'
 
indexes.append(elliptics.IndexEntry())
indexes[-1].index = elliptics.Id('index2')
indexes[-1].data = 'index2_key_data'
 
indexes_result = []
try:
    result = session.update_indexes_internal_raw('key', indexes)
    indexes_result = result.get()
except Exception as e:
    print 'Set indexes raw has been failed:', e

elliptics.AsyncResult for operations which updates indexes provides elliptics.CallbackResultEntry as a single result of the operation. Description of elliptics.CallbackResultEntry can be found right after remove operations.

find_all_indexes(indexes)

Search the intersection of indexes. Returns elliptics.AsyncResult. The input parameter is:
indexes - iterable object which provides set of string indexes.

try:
    result = session.find_all_indexes(['index1', 'index2'])
    id_results = result.get()
    for res in id_results:
        print 'Find id:', res.id
        for index in res.indexes:
            print 'index:', index.index
            print 'data:', index.data
except Exception as e:
    print 'Find all indexes has been failed:', e

find_all_indexes_raw(indexes)

Search the intersection of indexes. Returns elliptics.AsyncResult. The input parameter is:
indexes - iterable object which provides set indexes as elliptics.Id.

try:try:
    result = session.find_all_indexes_raw([elliptics.Id('index1'), elliptics.Id('index2')])
    id_results = result.get()
    for id_result in id_result:
        print 'Find id:', id_result.id
        for index in id_result.indexes:
            print 'index:', index.index
            print 'data:', index.data
except Exception as e:
    print 'Find all indexes has been failed:', e

find_any_indexes(indexes)

Searches for all the ids in all the indexes and make them join. Returns elliptics.AsyncResult. The input parameter is:
indexes - iterable object which provides set of string indexes.

elliptics.AsyncResult for find indexes operations provides elliptics.FindIndexesResultEntry as a single result of the operation.

elliptics.FindIndexesResultEntry attribute Description
id elliptics.Id
indexes List of indexes where the id is. It consists of elliptics.IndexEntry
try:
    result = session.find_any_indexes(['index1', 'index2'])
    id_results = result.get()
    for id_result in id_result:
        print 'Find id:', id_result.id
        for index in id_result.indexes:
            print 'index:', index.index
            print 'data:', index.data
except Exception as e:
    print 'Find all indexes has been failed:', e

find_any_indexes_raw(indexes)

Searches for all the ids in all the indexes and make them join. Returns elliptics.AsyncResult. The input parameter is:
indexes - iterable object which provides set of indexes as elliptics.Id.

elliptics.AsyncResult for find indexes operations provides elliptics.FindIndexesResultEntry as a single result of the operation.

elliptics.FindIndexesResultEntry attribute Description
id elliptics.Id
indexes List of indexes where the id is. It consists of elliptics.IndexEntry
try:
    result = session.find_any_indexes_raw([elliptics.Id('index1'), elliptics.Id('index2')])
    id_results = result.get()
    for id_result in id_result:
        print 'Find id:', id_result.id
        for index in id_result.indexes:
            print 'index:', index.index
            print 'data:', index.data
except Exception as e:
    print 'Find all indexes has been failed:', e

list_indexes(id)

The index list that contains the id. Returns elliptics.AsyncResult. The input parameter is:
id - a value of elliptics.Id or a string representation of the ID.

try:
    result = session.list_indexes('key')
    indexes = results.get()
    for index in indexes:
        print 'Index:', index.index
        print 'Data:', index.data
excep Exception as e:
    print 'List indexes failed:', e

elliptics.AsyncResult for list_indexes provides elliptics.IndexEntry as a single result of the operation.

elliptics.IndexEntry Description
index elliptics.Id of index
data Data of id in the index

Statistics

The group of methods which provides to get statistical information about Elliptics node or cluster.

stat_log_count()

Provides information about number executed and failed operations grouped by operation. It returns elliptics.AsyncResult which provides elliptics.StatCountResultEntry as a single result of operation.

elliptics.StatCountResultEntry attribute Description
statistics Operations statistics as elliptics.AddressStatistics
address elliptics.Address of the node which the statistics are belonged
error elliptics.Error information
elliptics.AddressStatistics attribute Description
address elliptics.Address of the client node from which the statistics was requested
counters Python dict of operations counters statistics
for stat in s.stat_log_count().get():
        print "Counters for node: {0}:".format(stat.address)
	print "Counters:"
	counters = stat.statistics.counters['counters']
	for counter in counters:
		print "Counter: {0}, val: {1}".format(counter, counters[counter][0])
 
	print "Proxy commands:"
	commands = stat.statistics.counters['proxy_commands']
	for command in commands:
		print "Command: {0}, successes: {1}, failures: {2}"
		      .format(command, commands[command][0], commands[command][1])
 
	commands = stat.statistics.counters['storage_commands']
	for command in commands:
		print "Command: {0}, successes: {1}, failures: {2}"
		      .format(command, commands[command][0], commands[command][1])

stat_log([key])

Provides statistics about virtual memory and file system on cluster or on the node. It returns elliptics.AsyncResult which provides elliptics.StatResultEntry as a single result of operation.
key - it specifies Elliptics node which statistics should be retrived. If it is not specified then the statistics of all cluster will be retrived.

elliptics.StatResultEntry attribute Description
statistics virtual memory and file system statistics as elliptics.Statisitics
address elliptics.Address of the node which the statistics are belong
error elliptics.Error information
elliptics.Statisitics attributeDescription
la Load average on the node
bsize Block size
frsize Fragment size
blocks Filesystem size in frsize units
bfree Free blocks
bavail Free blocks for non-root
files Inodes
ffree Free inodes
favail Free inodes for non-root
fsid File system ID
flag Mount flags
vm_active Virtual memory which is active
vm_inactive Virtual memory which is inactive
vm_total Total size of virtual memory
vm_free Size of free virtual memory
vm_cached Virtual memory which is cached
vm_buffers Virtual memory which is buffered
node_files Objects on the node
node_files_removed Objects on the node which marked as deleted
for stat in s.stat_log().get():
	print "Statistics for node: {0}:".format(stat.address)
	print "la: {0:3.02f} {1:3.02f} {2:3.02f}"
	      .format(stat.statistics.la[0] / 100.0, stat.statistics.la[1] / 100.0, stat.statistics.la[2] / 100.0)
	print "mem: total: {0} kB, free: {1} kB, cache: {2} kB, buffers: {3}, active: {4}, inactive: {5}"
	      .format(stat.statistics.vm_total,
	              stat.statistics.vm_free,
	              stat.statistics.vm_cached,
	              stat.statistics.vm_buffers,
	              stat.statistics.vm_active,
	              stat.statistics.vm_inactive)
	print "fs: total: {0} mB, avail: {1} / {2} mB"
	      .format(stat.statistics.frsize * stat.statistics.blocks / 1024 / 1024,
	              stat.statistics.bavail * stat.statistics.bsize / 1024 / 1024,
	              stat.statistics.bfree * stat.statistics.bsize / 1024 / 1024)

Quickstart

#imports elliptics python binding
import elliptics
 
#creates elliptics logger instance which will write all logs into /dev/stderr with loglevel = 0
elog = elliptics.Logger("/dev/stderr", 0)
 
#creates elliptics config instance
cfg = elliptics.Config()
 
#creates elliptics Node instance
node = elliptics.Node(elog, cfg)
 
#adds localhost:1025 to node remotes. Any host or IP can be used instead of localhost.
node.add_remote("localhost", 1025)
 
#creates instance of elliptics Session
s = elliptics.Session(node)
 
#sets [1, 2, 3] groups to elliptics Session
s.groups = [1, 2, 3]
 
try:
    #writes data "test_data" to key "test_key"
    s.write_data("test_key", "test_data").get()
except Exception as e:
    print "Write was failed: {0}".format(e)
 
try:
    #reads latest data from key "test_key"
    data = s.read_latest("test_key").get()[0].data
    print data
except Exception as e:
    print "Read latest was failed: {0}".format(e)

Disclaimer

Python binding is under development and will be updated soon. This doc/tutorial will be updated ASAP after that.

elliptics/api-python.txt · Last modified: 2014/02/11 23:30 by zbr