Initial schema support

Author: rtsisyk

doc/api/class-connection.rst

@@ -7,4 +7,4 @@ class :class:`Connection`
 .. autoclass:: Connection
    :members: close, ping, space
 
-   .. automethod:: call(func_name, *args [, field_types [, return_tuple]])
+   .. automethod:: call(func_name, *args [, return_tuple])

doc/api/class-schema.rst

@@ -0,0 +1,9 @@
+
+.. currentmodule:: tarantool.schema
+
+class :class:`Schema`
+--------------------
+
+.. autoclass:: Schema
+   :members:
+   :undoc-members:

doc/guide.en.rst

@@ -40,42 +40,58 @@ It is much easier to use native types for python developer:
 For raw binary data ``bytes`` should be used
 (in this case the type casting is not performed).
 
-Pass field types using argument ``field_types`` for automatic type casting::
+Tarantool data types corresponds to the following Python types:
+    • ``RAW`` - ``bytes``
+    • ``STR`` - ``unicode`` (``str`` for Python 3.x)
+    • ``NUM`` - ``int``
+    • ``NUM64`` - ``int`` or ``long`` (``int`` for Python 3.x)
 
-    >>> demo = connection.space(0, field_types=(int, unicode))
-    >>> demo.insert((0, u'this is unicode string'))
-    >>> demo.select(0)
-    [(0, u'this is unicode string')]
-
-As you can see, a tuple of types is passed with ``field_types``.
-Original "raw" fields will be casted to these native types.
-
-Tarantool's tuple can contain any number of fields.
+Please define spaces schema to enable automatic type casting:
 
-If the tuple contains more fields than types listed in ``field_types``,
-the latest type from ``field_types`` will be applied to all the remaining fields of the tuple.
-
-Example::
-
-    >>> demo = connection.space(0, field_types=(int, unicode))
-    >>> demo.insert((0, u'I am the Alpha (Α) and Omega (Ω)', b'AAAA', b'BBBB', b'CCCC', b'DDDD'))
+    >>> import tarantool
+    >>> schema = {
+            0: { # Space description
+                'name': 'users', # Space name
+                'default_type': tarantool.STR, # Type that used to decode fields that are not listed below
+                'fields': {
+                    0: ('numfield', tarantool.NUM), # (field name, field type)
+                    1: ('num64field', tarantool.NUM64),
+                    2: ('strfield', tarantool.STR),
+                    #2: { 'name': 'strfield', 'type': tarantool.STR }, # Alternative syntax
+                    #2: tarantool.STR # Alternative syntax
+                },
+                'indexes': {
+                    0: ('pk', [0]), # (name, [field_no])
+                    #0: { 'name': 'pk', 'fields': [0]}, # Alternative syntax
+                    #0: [0], # Alternative syntax
+                }
+            }
+        }
+    >>> connection = tarantool.connect(host = 'localhost', port=33013, schema = schema)
+    >>> demo = connection.space('users')
+    >>> demo.insert((0, 12, u'this is unicode string'))
     >>> demo.select(0)
-    [(0, u'I am the Α and Ω', u'AAAA', u'BBBB', u'CCCC', u'DDDD')]
+    [(0, 12, u'this is unicode string')]
 
-As you can see, all values was converted to unicode-strings.
-
-To prevent such implicit type casting it is enough to add ``bytes``
-as the last element of ``field_types`` tuple::
-
-    >>> demo = connection.space(0, field_types=(int, unicode, bytes))
-    >>> demo.insert((0, u'I am the Alpha (Α) and Omega (Ω)', b'AAAA', b'BBBB', b'CCCC', b'DDDD'))
-    >>> demo.select(0)
-    [(0, u'I am the Α and Ω', 'AAAA', 'BBBB', 'CCCC', 'DDDD')]
+As you can see, original "raw" fields were casted to native types as defined in the schema.
 
+Tarantool's tuple can contain any number of fields.
+If some fields are not defined then ``default_type`` will be used.
 
+To prevent implicit type casting for strings use ``RAW`` type.
 Raw byte fields should be used if the application uses binary data
 (eg, images or python objects packed with ``picke``).
 
+You can also specify schema for CALL results:
+
+    >>> ...
+    # Copy schema decription from 'users' space
+    >>> connection.call("box.select", '0', '0', 0L, space_name='users');
+    [(0, 12, u'this is unicode string')]
+    # Provide schema description explicitly
+    >>> field_defs = [('numfield', tarantool.NUM), ('num64field', tarantool.NUM)]
+    >>> connection.call("box.select", '0', '1', 184L, field_defs = field_defs, default_type = tarantool.STR);
+    [(0, 12, u'this is unicode string')]
 
 .. note::
 
@@ -250,16 +266,7 @@ Select data on cities in Texas::
 .. rubric:: Select records explicitly specifying field types
 
 Tarantool has no strict schema so all fields are raw binary byte arrays.
-You can specify field types in directly in
-:meth:`Space.select() <tarantool.space.Space.select>` method
-using ``field_types`` keyword argument::
-
-    >>> world.select(3800, field_types=(bytes, str, str, str, bytes))
-    [('\xd8\x0e\x00\x00', 'USA', 'Texas', 'Dallas', '\xe4"\x12\x00')]
-
-As you can see, ``3800`` returned
-as 4-byte array (string) instead of integer.
-
+You can specify field types in the ``schema`` parameter to a connection.
 
 Call server-side functions
 --------------------------

doc/guide.ru.rst

@@ -40,46 +40,60 @@ Tarantool поддерживает три типа полей: ``STR``, ``NUM``
 Для бинарных данных следует использовать тип ``bytes``
 (в этом случае приведение типов не производится).
 
-Для автоматического приведения типов необходимо передать типы полей в параметре ``field_types``::
+Типы данных Tarantool соответствуют следующим типам Python:
+    • ``RAW`` - ``bytes``
+    • ``STR`` - ``unicode`` (``str`` for Python 3.x)
+    • ``NUM`` - ``int``
+    • ``NUM64`` - ``int`` or ``long`` (``int`` for Python 3.x)
 
-    >>> demo = connection.space(0, field_types=(int, unicode))
-    >>> demo.insert((0, u'this is unicode string'))
-    >>> demo.select(0)
-    [(0, u'this is unicode string')]
-
-Как видно из примера, в аргументе ``field_types`` передается кортеж типов.
-Исходные "сырые" поля будут приводиться к этим типам.
-
-В Tarantool кортеж может содержать произвольное количество полей.
-
-Если полей в кортеже больше, чем перечислено типов в ``field_types``,
-то последний тип из ``field_types`` применяется ко всем оставшимся полям кортежа.
-
-Пример::
-
-    >>> demo = connection.space(0, field_types=(int, unicode))
-    >>> demo.insert((0, u'I am the Alpha (Α) and Omega (Ω)', b'AAAA', b'BBBB', b'CCCC', b'DDDD'))
+Для автоматического приведения типов необходимо объявить схему:
+    >>> import tarantool
+    >>> schema = {
+            0: { # Space description
+                'name': 'users', # Space name
+                'default_type': tarantool.STR, # Type that used to decode fields that are not listed below
+                'fields': {
+                    0: ('user_id', tarantool.NUM), # (field name, field type)
+                    1: ('num64field', tarantool.NUM64),
+                    2: ('strfield', tarantool.STR),
+                    #2: { 'name': 'strfield', 'type': tarantool.STR }, # Alternative syntax
+                    #2: tarantool.STR # Alternative syntax
+                },
+                'indexes': {
+                    0: ('pk', [0]), # (name, [field_no])
+                    #0: { 'name': 'pk', 'fields': [0]}, # Alternative syntax
+                    #0: [0], # Alternative syntax
+                }
+            }
+        }
+    >>> connection = tarantool.connect(host = 'localhost', port=33013, schema = schema)
+    >>> demo = connection.space('users')
+    >>> demo.insert((0, 12, u'this is unicode string'))
     >>> demo.select(0)
-    [(0, u'I am the Α and Ω', u'AAAA', u'BBBB', u'CCCC', u'DDDD')]
+    [(0, 12, u'this is unicode string')]
 
-Как видно из примера, все значения были преобразованы в unicode-строки.
-
-Чтобы запретить такое неявное преобразование, достаточно в кортеже типов ``field_types``
-последним указать тип ``bytes``::
-
-    >>> demo = connection.space(0, field_types=(int, unicode, bytes))
-    >>> demo.insert((0, u'I am the Alpha (Α) and Omega (Ω)', b'AAAA', b'BBBB', b'CCCC', b'DDDD'))
-    >>> demo.select(0)
-    [(0, u'I am the Α and Ω', 'AAAA', 'BBBB', 'CCCC', 'DDDD')]
+Как видно из примера, все значения были преобразованы в Python-типы в соответствии со схемой.
 
+Кортеж Tarantool может содержать произвольное количество полей.
+Если какие-то поля не объявлены в схеме, то ``default_type`` будет использован для конвертации.
 
 Поля с "сырыми" байтами следует использовать, если приложение работает с
 двоичными данными (например, изображения или python-объекты, сохраненные с помощью ``picke``).
 
+Возможно также указать тип для CALL запросов:
+
+    >>> ...
+    # Copy schema decription from 'users' space
+    >>> connection.call("box.select", '0', '0', 0L, space_name='users');
+    [(0, 12, u'this is unicode string')]
+    # Provide schema description explicitly
+    >>> field_defs = [('numfield', tarantool.NUM), ('num64field', tarantool.NUM)]
+    >>> connection.call("box.select", '0', '1', 184L, field_defs = field_defs, default_type = tarantool.STR);
+    [(0, 12, u'this is unicode string')]
 
 .. note::
 
-   Python 2.6 adds :class:`bytes` as a synonym for the :class:`str` type, and it also supports the ``b''`` notation.
+   Python 2.6 добавляет синоним :class:`bytes` к типу :class:`str` (также поддерживается синтаксис ``b''``).
 
 
 .. note:: Для преобразования между ``bytes`` и ``unicode`` всегда используется **utf-8**
@@ -250,16 +264,7 @@ Tarantool поддерживает следующие операции обно
 .. rubric:: Запрос с явным указанием типов полей
 
 Tarantool не имеет строгой схемы и поля кортежей являются просто байтовыми массивами.
-Можно указать типа полей непосредственно в
-методе :meth:`Space.select() <tarantool.space.Space.select>`
-при помощи ``field_types`` keyword argument::
-
-    >>> world.select(3800, field_types=(bytes, str, str, str, bytes))
-    [('\xd8\x0e\x00\x00', 'USA', 'Texas', 'Dallas', '\xe4"\x12\x00')]
-
-Как видно из примера, значение ``3800`` возвращается
-в виде 4-байтного массива (строки) вместо целого значения.
-
+Можно указать типа полей непосредственно в параметре ``schema`` для ```Connection``
 
 Вызов хранимых функций
 ----------------------

doc/index.rst

@@ -40,6 +40,7 @@ API Reference
 
    api/module-tarantool.rst
    api/class-connection.rst
+   api/class-schema.rst
    api/class-space.rst
    api/class-response.rst
 

doc/index.ru.rst

@@ -40,6 +40,7 @@
 
    api/module-tarantool.rst
    api/class-connection.rst
+   api/class-schema.rst
    api/class-space.rst
    api/class-response.rst
 

src/tarantool/__init__.py

@@ -6,14 +6,17 @@
 from tarantool.connection import Connection
 from tarantool.const import *
 from tarantool.error import *
+from tarantool.schema import *
 
-def connect(host="localhost", port=33013):
+def connect(host="localhost", port=33013, schema=None):
     '''\
     Create a connection to the Tarantool server.
     
     :param str host: Server hostname or IP-address
     :param int port: Server port
-    
+    :param schema: Data schema (see Developer guide and :class:`~tarantool.schema.Schema`)
+    :type schema: :class:`~tarantool.schema.Schema` or dict
+
     :rtype: :class:`~tarantool.connection.Connection`
     :raise: `NetworkError`
     '''
@@ -22,4 +25,5 @@ def connect(host="localhost", port=33013):
                       socket_timeout=SOCKET_TIMEOUT,
                       reconnect_max_attempts=RECONNECT_MAX_ATTEMPTS,
                       reconnect_delay=RECONNECT_DELAY,
-                      connect_now=True)
+                      connect_now=True,
+                      schema = schema)