Add documentation on MeshConnection

Author: msiomkin

README.rst

@@ -65,7 +65,7 @@ Features
     * MsgPack data format and MsgPack based client-server protocol
     * Two data engines:
         * 100% in-memory with optional persistence
-        * 2-level disk-based B-tree, to use with large data sets (powered by `Sophia`_)
+        * LSM-tree based disk storage to use with large data sets
     * secondary key and index iterators support (can be non-unique and composite)
     * multiple index types: HASH, BITSET, TREE
     * asynchronous master-master replication
@@ -79,6 +79,26 @@ See More
  * `Tarantool User Guide`_
  * `Client-server Protocol Specification`_
 
+How to use the connector
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: lua
+
+    import tarantool
+    con = tarantool.Connection(host='localhost',
+                               port=3301,
+                               user='test',
+                               password='test',
+                               connect_now=True)
+
+
+    resp = con.eval('return "Hello Wrold!"')
+    if resp.data[0] == "Hello World!":
+        print('Ok')
+
+This will print 'Ok' assuming that there's a running Tarantool instance on port
+3301 on local machine and user test has execute privilege on universe.
+
 NOTE
 ^^^^
 

doc/api/class-mesh-connection.rst

@@ -0,0 +1,9 @@
+
+.. currentmodule:: tarantool.mesh_connection
+
+class :class:`MeshConnection`
+-----------------------------
+
+.. autoclass:: MeshConnection
+
+    .. automethod:: refresh_nodes(self, cur_time)

doc/index.rst

@@ -40,6 +40,7 @@ API Reference
 
    api/module-tarantool.rst
    api/class-connection.rst
+   api/class-mesh-connection.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-mesh-connection.rst
    api/class-space.rst
    api/class-response.rst
 

tarantool/mesh_connection.py

@@ -28,6 +28,65 @@ def getnext(self):
 
 
 class MeshConnection(Connection):
+    '''
+    Represents a connection to a cluster of Tarantool servers.
+
+    This class uses Connection to connect to one of the nodes of the cluster.
+    The initial list of nodes is passed to the constructor in 'addrs' parameter.
+    The class set in 'strategy_class' parameter is used to select a node from
+    the list and switch nodes in case of unavailability of the current node.
+
+    'get_nodes_function_name' param of the constructor sets the name of a stored
+    Lua function used to refresh the list of available nodes. A generic function
+    for getting the list of nodes looks like this:
+
+    .. code-block:: lua
+
+        function get_nodes()
+            return {
+                {
+                    host = '192.168.0.1',
+                    port = 3301
+                },
+                {
+                    host = '192.168.0.2',
+                    port = 3302
+                },
+
+                -- ...
+            }
+        end
+
+    You may put in this list whatever you need depending on your cluster
+    topology. Chances are you'll want to make the list of nodes from nodes'
+    replication config. So here is an example for it:
+
+    .. code-block:: lua
+
+        local uri_lib = require('uri')
+
+        function get_nodes()
+            local nodes = {}
+
+            local replicas = box.cfg.replication
+
+            for i = 1, #replicas do
+                local uri = uri_lib.parse(replicas[i])
+                local port = tonumber(uri.service)
+
+                if uri.host and port then
+                    table.insert(nodes, { host = uri.host, port = port })
+                end
+            end
+
+            -- if your replication config doesn't contain the current node
+            -- you have to add it manually like this:
+            table.insert(nodes, { host = '192.168.0.1', port = 3301 })
+
+            return nodes
+        end
+    '''
+
     def __init__(self, addrs,
                  user=None,
                  password=None,
@@ -46,7 +105,7 @@ def __init__(self, addrs,
         host = addr['host']
         port = addr['port']
         self.get_nodes_function_name = get_nodes_function_name
-        self.nodes_refresh_interval = nodes_refresh_interval
+        self.nodes_refresh_interval = nodes_refresh_interval >= 30 and nodes_refresh_interval or 30
         self.last_nodes_refresh = 0
         super(MeshConnection, self).__init__(host=host,
                                              port=port,
@@ -78,6 +137,13 @@ def _opt_reconnect(self):
                 self.refresh_nodes(now)
 
     def refresh_nodes(self, cur_time):
+        '''
+        Refreshes nodes list by calling Lua function with name
+        self.get_nodes_function_name on the current node. If this field is None
+        no refresh occurs. Usually you don't need to call this function manually
+        since it's called automatically during reconnect every
+        self.nodes_refresh_interval seconds.
+        '''
         resp = super(MeshConnection, self).call_ex(self.get_nodes_function_name,
                                                    [], reconnect=False)
 

unit/suites/test_reconnect.py

@@ -76,13 +76,13 @@ def test_03_mesh(self):
         # Start two servers
         self.srv.start()
         self.srv.admin("box.schema.user.create('test', { password = 'test', if_not_exists = true })")
-        self.srv.admin("box.schema.user.grant('test', 'read,write,execute', 'universe')")
+        self.srv.admin("box.schema.user.grant('test', 'execute', 'universe')")
 
         self.srv2 = TarantoolServer()
         self.srv2.script = 'unit/suites/box.lua'
         self.srv2.start()
         self.srv2.admin("box.schema.user.create('test', { password = 'test', if_not_exists = true })")
-        self.srv2.admin("box.schema.user.grant('test', 'read,write,execute', 'universe')")
+        self.srv2.admin("box.schema.user.grant('test', 'execute', 'universe')")
 
         # get_nodes function contains both servers' addresses
         get_nodes = " \
@@ -140,13 +140,13 @@ def test_04_mesh_exclude_node(self):
         # Start two servers
         self.srv.start()
         self.srv.admin("box.schema.user.create('test', { password = 'test', if_not_exists = true })")
-        self.srv.admin("box.schema.user.grant('test', 'read,write,execute', 'universe')")
+        self.srv.admin("box.schema.user.grant('test', 'execute', 'universe')")
 
         self.srv2 = TarantoolServer()
         self.srv2.script = 'unit/suites/box.lua'
         self.srv2.start()
         self.srv2.admin("box.schema.user.create('test', { password = 'test', if_not_exists = true })")
-        self.srv2.admin("box.schema.user.grant('test', 'read,write,execute', 'universe')")
+        self.srv2.admin("box.schema.user.grant('test', 'execute', 'universe')")
 
         # get_nodes function contains only the second server address
         get_nodes = " \