Add upsert

Modify docstrings for tarantool.Connection methods
Modify docstrings for tarantool.Space methods
Add basic tests for upsert/eval.
Modify tarantool.Space for simplicity of code/understanding
Add tests for space, fix couple of errors in code

Author: bigbes

tarantool/connection.py

@@ -32,6 +32,7 @@
     RequestSelect,
     RequestSubscribe,
     RequestUpdate,
+    RequestUpsert,
     RequestAuthenticate)
 
 from tarantool.space import Space
@@ -331,7 +332,7 @@ def eval(self, expr, *args):
     def replace(self, space_name, values):
         '''
         Execute REPLACE request.
-        It will throw error if there's no tuple with this PK exists
+        It won't throw error if there's no tuple with this PK exists
 
         :param int space_name: space id to insert a record
         :type space_name: int or str
@@ -347,6 +348,14 @@ def replace(self, space_name, values):
         return self._send_request(request)
 
     def authenticate(self, user, password):
+        '''
+        Execute AUTHENTICATE request.
+
+        :param string user: user to authenticate with
+        :param string password: password for the user
+
+        :rtype: `Response` instance
+        '''
         self.user = user
         self.password = password
         if not self._socket:
@@ -408,7 +417,8 @@ def insert(self, space_name, values):
     def delete(self, space_name, key, **kwargs):
         '''
         Execute DELETE request.
-        Delete single record identified by `key` (using primary index).
+        Delete single record identified by `key`. If you're using secondary
+        index, it must be unique.
 
         :param space_name: space number or name to delete a record
         :type space_name: int or name
@@ -427,25 +437,139 @@ def delete(self, space_name, key, **kwargs):
         request = RequestDelete(self, space_name, index_name, key)
         return self._send_request(request)
 
+    def upsert(self, space_name, tuple_value, op_list, **kwargs):
+        '''
+        Execute UPSERT request.
+
+        If there is an existing tuple which matches the key fields of
+        `tuple_value`, then the request has the same effect as UPDATE
+        and the [(field_1, symbol_1, arg_1), ...] parameter is used.
+
+        If there is no existing tuple which matches the key fields of
+        `tuple_value`, then the request has the same effect as INSERT
+        and the `tuple_value` parameter is used. However, unlike insert
+        or update, upsert will not read a tuple and perform error checks
+        before returning -- this is a design feature which enhances
+        throughput but requires more caution on the part of the user.
+
+        If you're using secondary index, it must be unique.
+
+        List of operations allows to update individual fields.
+
+        *Allowed operations:*
+
+        (For every operation you must provide field number, to apply this
+        operation to)
+
+        * `+` for addition (values must be numeric)
+        * `-` for subtraction (values must be numeric)
+        * `&` for bitwise AND (values must be unsigned numeric)
+        * `|` for bitwise OR (values must be unsigned numeric)
+        * `^` for bitwise XOR (values must be unsigned numeric)
+        * `:` for string splice (you must provide `offset`, `count` and `value`
+          for this operation)
+        * `!` for insertion (provide any element to insert)
+        * `=` for assignment (provide any element to assign)
+        * `#` for deletion (provide count of fields to delete)
+
+        :param space_name: space number or name to update a record
+        :type space_name: int or str
+        :param index: index number or name to update a record
+        :type index: int or str
+        :param tuple_value: tuple, that
+        :type tuple_value:
+        :param op_list: list of operations. Each operation
+            is tuple of three (or more) values
+        :type op_list: a list of the form [(symbol_1, field_1, arg_1),
+            (symbol_2, field_2, arg_2_1, arg_2_2, arg_2_3),...]
+
+        :rtype: `Response` instance
+
+        Operation examples:
+
+        .. code-block:: python
+
+            # 'ADD' 55 to second field
+            # Assign 'x' to third field
+            [('+', 2, 55), ('=', 3, 'x')]
+            # 'OR' third field with '1'
+            # Cut three symbols starting from second and replace them with '!!'
+            # Insert 'hello, world' field before fifth element of tuple
+            [('|', 3, 1), (':', 2, 2, 3, '!!'), ('!', 5, 'hello, world')]
+            # Delete two fields starting with second field
+            [('#', 2, 2)]
+        '''
+        index_name = kwargs.get("index", 0)
+
+        if isinstance(space_name, six.string_types):
+            space_name = self.schema.get_space(space_name).sid
+        if isinstance(index_name, six.string_types):
+            index_name = self.schema.get_index(space_name, index_name).iid
+        request = RequestUpsert(self, space_name, index_name, tuple_value, op_list)
+        return self._send_request(request)
+
     def update(self, space_name, key, op_list, **kwargs):
         '''
         Execute UPDATE request.
-        Update single record identified by `key` (using primary index).
+
+        The `update` function supports operations on fields — assignment,
+        arithmetic (if the field is unsigned numeric), cutting and pasting
+        fragments of a field, deleting or inserting a field. Multiple
+        operations can be combined in a single update request, and in this
+        case they are performed atomically and sequentially. Each operation
+        requires specification of a field number. When multiple operations are
+        present, the field number for each operation is assumed to be relative
+        to the most recent state of the tuple, that is, as if all previous
+        operations in a multi-operation update have already been applied.
+        In other words, it is always safe to merge multiple update invocations
+        into a single invocation, with no change in semantics.
+
+        Update single record identified by `key`.
 
         List of operations allows to update individual fields.
 
+        *Allowed operations:*
+
+        (For every operation you must provide field number, to apply this
+        operation to)
+
+        * `+` for addition (values must be numeric)
+        * `-` for subtraction (values must be numeric)
+        * `&` for bitwise AND (values must be unsigned numeric)
+        * `|` for bitwise OR (values must be unsigned numeric)
+        * `^` for bitwise XOR (values must be unsigned numeric)
+        * `:` for string splice (you must provide `offset`, `count` and `value`
+          for this operation)
+        * `!` for insertion (before) (provide any element to insert)
+        * `=` for assignment (provide any element to assign)
+        * `#` for deletion (provide count of fields to delete)
+
         :param space_name: space number or name to update a record
         :type space_name: int or str
         :param index: index number or name to update a record
         :type index: int or str
         :param key: key that identifies a record
         :type key: int or str
         :param op_list: list of operations. Each operation
-            is tuple of three values
-        :type op_list: a list of the form
-            [(field_1, symbol_1, arg_1), (field_2, symbol_2, arg_2),...]
+            is tuple of three (or more) values
+        :type op_list: a list of the form [(symbol_1, field_1, arg_1),
+            (symbol_2, field_2, arg_2_1, arg_2_2, arg_2_3), ...]
 
-        :rtype: `Response` instance
+        :rtype: ``Response`` instance
+
+        Operation examples:
+
+        .. code-block:: python
+
+            # 'ADD' 55 to second field
+            # Assign 'x' to third field
+            [('+', 2, 55), ('=', 3, 'x')]
+            # 'OR' third field with '1'
+            # Cut three symbols starting from second and replace them with '!!'
+            # Insert 'hello, world' field before fifth element of tuple
+            [('|', 3, 1), (':', 2, 2, 3, '!!'), ('!', 5, 'hello, world')]
+            # Delete two fields starting with second field
+            [('#', 2, 2)]
         '''
         index_name = kwargs.get("index", 0)
 

tarantool/const.py

@@ -18,6 +18,7 @@
 IPROTO_CLUSTER_UUID = 0x25
 IPROTO_VCLOCK = 0x26
 IPROTO_EXPR = 0x27
+IPROTO_OPS = 0x28
 IPROTO_DATA = 0x30
 IPROTO_ERROR = 0x31
 
@@ -32,12 +33,12 @@
 REQUEST_TYPE_CALL = 6
 REQUEST_TYPE_AUTHENTICATE = 7
 REQUEST_TYPE_EVAL = 8
+REQUEST_TYPE_UPSERT = 9
 REQUEST_TYPE_PING = 64
 REQUEST_TYPE_JOIN = 65
 REQUEST_TYPE_SUBSCRIBE = 66
 REQUEST_TYPE_ERROR = 1 << 15
 
-
 SPACE_SCHEMA = 272
 SPACE_SPACE = 280
 SPACE_INDEX = 288

tarantool/request.py

@@ -24,13 +24,15 @@
     IPROTO_CLUSTER_UUID,
     IPROTO_VCLOCK,
     IPROTO_EXPR,
+    IPROTO_OPS,
     REQUEST_TYPE_OK,
     REQUEST_TYPE_PING,
     REQUEST_TYPE_SELECT,
     REQUEST_TYPE_INSERT,
     REQUEST_TYPE_REPLACE,
     REQUEST_TYPE_DELETE,
     REQUEST_TYPE_UPDATE,
+    REQUEST_TYPE_UPSERT,
     REQUEST_TYPE_CALL,
     REQUEST_TYPE_EVAL,
     REQUEST_TYPE_AUTHENTICATE,
@@ -248,6 +250,23 @@ def __init__(self, conn):
         super(RequestPing, self).__init__(conn)
         self._bytes = self.header(0)
 
+class RequestUpsert(Request):
+    '''
+    Represents UPSERT request
+    '''
+
+    request_type = REQUEST_TYPE_UPSERT
+
+    # pylint: disable=W0231
+    def __init__(self, conn, space_no, index_no, tuple_value, op_list):
+        super(RequestUpsert, self).__init__(conn)
+
+        request_body = msgpack.dumps({IPROTO_SPACE_ID: space_no,
+                                      IPROTO_INDEX_ID: index_no,
+                                      IPROTO_TUPLE: tuple_value,
+                                      IPROTO_OPS: op_list})
+
+        self._bytes = self.header(len(request_body)) + request_body
 
 class RequestJoin(Request):
     '''

tarantool/space.py

@@ -19,106 +19,65 @@ def __init__(self, connection, space_name):
 
         :param connection: Object representing connection to the server
         :type connection: :class:`~tarantool.connection.Connection` instance
-        :param int space_no: space no or name to insert a record
+        :param int space_name: space no or name to insert a record
         :type space_name: int or str
         '''
 
         self.connection = connection
         self.space_no = self.connection.schema.get_space(space_name).sid
 
-    def replace(self, values):
+    def insert(self, *args, **kwargs):
         '''
-        Execute REPLACE request.
-        It will throw error if there's no tuple with this PK exists
-
-        :param values: record to be inserted. The tuple must contain
-            only scalar (integer or strings) values
-        :type values: tuple
+        Execute INSERT request.
 
-        :rtype: :class:`~tarantool.response.Response` instance
+        See `~tarantool.connection.insert` for more information
         '''
-        self.connection.replace(self.space_no, values)
+        return self.connection.insert(self.space_no, *args, **kwargs)
 
-    def insert(self, values):
+    def replace(self, *args, **kwargs):
         '''
-        Execute INSERT request.
-        It will throw error if there's tuple with same PK exists.
-
-        :param values: record to be inserted. The tuple must contain
-            only scalar (integer or strings) values
-        :type values: tuple
+        Execute REPLACE request.
 
-        :rtype: :class:`~tarantool.response.Response` instance
+        See `~tarantool.connection.replace` for more information
         '''
-        self.connection.insert(self.space_no, values)
+        return self.connection.replace(self.space_no, *args, **kwargs)
 
-    def delete(self, key):
+    def delete(self, *args, **kwargs):
         '''
-        Delete records by its primary key.
+        Execute DELETE request.
 
-        :param key: key of records to be deleted
-        :type values: tuple or str or int or long
+        See `~tarantool.connection.delete` for more information
+        '''
+        return self.connection.delete(self.space_no, *args, **kwargs)
 
-        :rtype: :class:`~tarantool.response.Response` instance
+    def update(self, *args, **kwargs):
         '''
-        return self.connection.delete(self.space_no, key)
+        Execute UPDATE request.
 
-    def update(self, key, op_list):
+        See `~tarantool.connection.update` for more information
         '''
-        Update records by it's primary key with operations defined in op_list
+        return self.connection.update(self.space_no, *args, **kwargs)
 
-        :param key: key of records to be updated
-        :type values: tuple or str or int or long
+    def upsert(self, *args, **kwargs):
+        '''
+        Execute UPDATE request.
 
-        :rtype: :class:`~tarantool.response.Response` instance
+        See `~tarantool.connection.upsert` for more information
         '''
-        return self.connection.update(self.space_no, key, op_list)
+        return self.connection.upsert(self.space_no, *args, **kwargs)
 
-    def select(self, values, **kwargs):
+    def select(self, *args, **kwargs):
         '''
         Execute SELECT request.
-        Select and retrieve data from the database.
 
-        :param values: list of values to search over the index
-        :type values: list of tuples
-        :param index: specifies which index to use (default is **0** which
-            means that the **primary index** will be used)
-        :type index: int
-        :param offset: offset in the resulting tuple set
-        :type offset: int
-        :param limit: limits the total number of returned tuples
-        :type limit: int
-
-        :rtype: `Response` instance
+        See `~tarantool.connection.select` for more information
         '''
-        # Initialize arguments and its defaults from **kwargs
-        # I use the explicit argument initialization from the kwargs
-        # to make it impossible to pass positional arguments
-        index = kwargs.get("index", 0)
-        offset = kwargs.get("offset", 0)
-        limit = kwargs.get("limit", 0xffffffff)
-
-        return self.connection.select(
-            self.space_no, values, index=index, offset=offset, limit=limit)
+        return self.connection.select(self.space_no, *args, **kwargs)
 
-    def call(self, func_name, *args, **kwargs):
+    def call(self, *args, **kwargs):
         '''
         Execute CALL request. Call stored Lua function.
 
-        :param func_name: stored Lua function name
-        :type func_name: str
-        :param args: list of function arguments
-        :type args: list or tuple
-        :param field_defs: field definitions used for types conversion,
-               e.g. [('field0', tarantool.NUM), ('field1', tarantool.STR)]
-        :type field_defs: None or  [(name, type) or None]
-        :param default_type: None a default type used for result conversion,
-            as defined in ``schema[space_no]['default_type']``
-        :type default_type: None or int
-        :param space_name: space number or name. A schema for the space
-            will be used for type conversion.
-        :type space_name: None or int or str
-
-        :rtype: `Response` instance
+        It's deprecated, use `~tarantool.connection.call` instead
         '''
         return self.connection.call(func_name, *args, **kwargs)