module tarantool

tarantool.connect(host='localhost', port=33013, schema=None)

Create a connection to the Tarantool server.

Parameters:

• host (str) – Server hostname or IP-address
• port (int) – Server port
• schema (Schema or dict) – Data schema (see Developer guide and Schema)

Return type:

Connection

Raise :

NetworkError

class tarantool.Connection(host, port, socket_timeout=None, reconnect_max_attempts=10, reconnect_delay=0.1, connect_now=True, schema=None, return_tuple=True)

Represents connection to the Tarantool server.

This class is responsible for connection and network exchange with the server. Also this class provides low-level interface to data manipulation (insert/delete/update/select).

Initialize a connection to the server.

Parameters:

• host (str) – Server hostname or IP-address
• port (int) – Server port
• connect_now (bool) – if True (default) than __init__() actually

creates network connection.

if False than you have to call connect() manualy.

Parameters:schema (Schema or dict) – Data schema (see Developer guide and Schema)

call(func_name, *args, **kwargs)

Execute CALL request. Call stored Lua function.

Parameters:

• func_name (str) – stored Lua function name
• args (list or tuple) – list of function arguments
• return_tuple (bool) – True indicates that it is required to return the inserted tuple back
• field_defs (None or [(name, type) or None]) – field definitions used for types conversion, e.g. [(‘field0’, tarantool.NUM), (‘field1’, tarantool.STR)]
• default_type (None or int) – None a default type used for result conversion, as defined in schema[space_no]['default_type']
• space_name (None or int or str) – space number or name. A schema for the space will be used for type conversion.

Return type:

Response instance

close()

Close connection to the server

connect()

Create connection to the host and port specified in __init__(). Usually there is no need to call this method directly, since it is called when you create an Connection instance.

Raise :NetworkError

delete(space_name, key, return_tuple=None)

Execute DELETE request. Delete single record identified by key (using primary index).

Parameters:

• space_name (int or name) – space number or name to delete a record
• key (int or str) – key that identifies a record
• return_tuple (bool) – indicates that it is required to return the deleted tuple back

Return type:

Response instance

insert(space_name, values, return_tuple=None)

Execute INSERT request. It will throw error if there’s tuple with same PK exists.

Parameters:

• space_name (int or str) – space id to insert a record
• values (tuple) – record to be inserted. The tuple must contain only scalar (integer or strings) values
• return_tuple (bool) – True indicates that it is required to return the inserted tuple back

Return type:

Response instance

ping(notime=False)

Execute PING request. Send empty request and receive empty response from server.

Returns:response time in seconds Return type:float

replace(space_name, values, return_tuple=None)

Execute REPLACE request. It will throw error if there’s no tuple with this PK exists

Parameters:

• space_name (int or str) – space id to insert a record
• values (tuple) – record to be inserted. The tuple must contain only scalar (integer or strings) values
• return_tuple (bool) – True indicates that it is required to return the inserted tuple back

Return type:

Response instance

select(space_name, values=None, **kwargs)

Execute SELECT request. Select and retrieve data from the database.

Parameters:

• space_name (int or str) – specifies which space to query
• values (list, tuple, set, frozenset of tuples) – values to search over the index
• index (int) – specifies which index to use (default is 0 which means that the primary index will be used)
• offset (int) – offset in the resulting tuple set
• limit (int) – limits the total number of returned tuples

Return type:

Response instance

Select one single record (from space=0 and using index=0) >>> select(0, 0, 1)

Select several records using single-valued index >>> select(0, 0, [1, 2, 3]) >>> select(0, 0, [(1,), (2,), (3,)]) # the same as above

Select serveral records using composite index >>> select(0, 1, [(1,‘2’), (2,‘3’), (3,‘4’)])

Select single record using composite index >>> select(0, 1, [(1,‘2’)]) This is incorrect >>> select(0, 1, (1,‘2’))

space(space_name)

Create Space instance for particular space

Space instance encapsulates the identifier of the space and provides more convenient syntax for accessing the database space.

Parameters:space_name (int or str) – identifier of the space Return type:Space instance

store(space_name, values, return_tuple=None)

Execute STORE request. It will overwrite tuple with the same PK, if it exists, or inserts if not

Parameters:

• space_name (int or str) – space id to insert a record
• values (tuple) – record to be inserted. The tuple must contain only scalar (integer or strings) values
• return_tuple (bool) – True indicates that it is required to return the inserted tuple back

Return type:

Response instance

update(space_name, key, op_list, return_tuple=None)

Execute UPDATE request. Update single record identified by key (using primary index).

List of operations allows to update individual fields.

Parameters:

• space_name (int or str) – space number or name to update a record
• key (int or str) – key that identifies a record
• op_list (a list of the form [(field_1, symbol_1, arg_1), (field_2, symbol_2, arg_2),...]) – list of operations. Each operation is tuple of three values
• return_tuple (bool) – indicates that it is required to return the updated tuple back

Return type:

Response instance

class tarantool.Schema(schema)

A class used to describe a data schema. Encapsulates the names and types and provides more convenient syntax for database operations.

Create Schema instance.

Parameters:

• connection (Connection instance) – Object representing connection to the server
• schema (dict) – schema description

Example schema description:

>>> schema = {
    0: { # Space description
        'name': 'users', # Space name
        # Type that used to decode fields that are not listed below
        'default_type': tarantool.STR,
        'fields': {
            0: ('user_id', tarantool.NUM), # (field name, field type)
            1: ('num64field', tarantool.NUM64),
            2: ('strfield', tarantool.STR),
            # Alternative syntax
            #2: { 'name': 'strfield', 'type': tarantool.STR },
            #2: tarantool.STR # Alternative syntax
        },
        'indexes': {
            0: ('pk', [0]), # (name, [field_no])
            #0: { 'name': 'pk', 'fields': [0]}, # Alternative syntax
            #0: [0], # Alternative syntax
        }
    }
}

index_no(space_name, index_name)

Return index number by space name and index name

Parameters:

• space_name (str) – Space name
• index_name (str) – Index name

pack_key(values, space_no, index_no)

Convert a list of keys from Python to Tarantool types using schema

Parameters:

• value (tuple of scalar values (bytes, str or int)) – key tuple to be packed
• space_no (int) – space number
• index_no (int) – index number

Returns:

packed values

Return type:

bytes

pack_value(value, cast_to=None)

Convert single field from Python type to Tarantol type

Parameters:

• value (bytes, int, unicode (str for py3k)) – value to be packed
• cast_to (int or a type object (one of bytes, int, unicode (str for py3k))) – data type

Returns:

packed value

Return type:

bytes

pack_values(values, space_no=None, field_defs=None, default_type=None)

Convert a list of fields from Python to Tarantool types using schema

Parameters:

• value (tuple of scalar values (bytes, str or int)) – tuple to be packed
• space_no (None or int) – space number
• field_defs (None or [(name, type) or None]) – field definitions used for types conversion, e.g. [(‘field0’, tarantool.NUM), (‘field1’, tarantool.STR)]
• default_type (None or int) – None a default type used for result conversion, as defined in schema[space_no]['default_type']

Returns:

packed tuple

Returns:

packed values

space_no(space_name)

Return space number by space name

Parameters:space_name (str) – Space name

unpack_value(packed_value, cast_to)

Convert field type from Tarantool type to Python type

Parameters:

• value (bytes) – raw value from the database
• cast_to (int or a type object (one of bytes, int, unicode (str for py3k))) – data type to cast to

Returns:

converted value

Return type:

value of native python type (one of bytes, int, unicode (str for py3k))

unpack_values(packed_values, space_no=None, field_defs=None, default_type=None)

Convert a list of fields from Tarantool to Python types using schema

Parameters:

• packed_values (tuple of bytes) – tuple of the raw database values
• space_no (None or int) – space number
• field_defs (None or [(name, type) or None]) – field definitions used for types conversion, e.g. [(‘field0’, tarantool.NUM), (‘field1’, tarantool.STR)]
• default_type (None or int) – None a default type used for result conversion, as defined in schema[space_no]['default_type']

Returns:

converted tuple value

Return type:

unpacked values of native python types (bytes, int, unicode (or str for py3k))

exception tarantool.Error

Base class for error exceptions

exception tarantool.DatabaseError

Error related to the database engine

exception tarantool.NetworkError(orig_exception=None, *args)

Error related to network

exception tarantool.NetworkWarning

Warning related to network

exception tarantool.RetryWarning

Warning is emited in case of server return completion_status == 1 (try again)