better quickstart

docs/quickstart.rst

@@ -15,13 +15,27 @@ With pip_ (without pip see at then end of this document)::
 
     pip install tornadis
 
-First try
----------
+First try (coroutines)
+----------------------
 
 .. literalinclude:: ../examples/coroutines.py
     :language: python
     :linenos:
 
+Second try (callbacks)
+----------------------
+
+.. literalinclude:: ../examples/callbacks.py
+    :language: python
+    :linenos:
+
+Go further: Pipeline
+----------------------
+
+.. literalinclude:: ../examples/pipeline.py
+    :language: python
+    :linenos:
+
 Installation without pip
 ------------------------
 

examples/callbacks.py

@@ -1,20 +1,34 @@
+# Let's import tornado and tornadis
 import tornado
 import tornadis
-import logging
-logging.basicConfig(level=logging.CRITICAL)
 
 
 def ping_callback(result):
     if not isinstance(result, tornadis.TornadisException):
-        print result
+        # For specific reasons, tornadis nearly never raises any exception
+        # they are returned as result
+        print "got exception: %s" % result
+    else:
+        # result is already a python object (a string in this simple example)
+        print "Result: %s" % result
 
 
 @tornado.gen.coroutine
 def main():
+    # let's (re)connect (autoconnect mode), call the ping redis command
+    # and wait the reply without blocking the tornado ioloop
+    # Note: async_call() method on Client instance does not return anything
+    # but the callback will be called later with the result.
     client.async_call("PING", callback=ping_callback)
     yield tornado.gen.sleep(1)
 
 
+# Build a tornadis.Client object with some options as kwargs
+# host: redis host to connect
+# port: redis port to connect
+# autoconnect=True: put the Client object in auto(re)connect mode
+client = tornadis.Client(host="localhost", port=6379, autoconnect=True)
+
+# Start a tornado IOLoop, execute the coroutine and end the program
 loop = tornado.ioloop.IOLoop.instance()
-client = tornadis.Client()
 loop.run_sync(main)

examples/coroutines.py

@@ -7,6 +7,8 @@
 def talk_to_redis():
     # let's (re)connect (autoconnect mode), call the ping redis command
     # and wait the reply without blocking the tornado ioloop
+    # Note: call() method on Client instance returns a Future object (and
+    # should be used as a coroutine).
     result = yield client.call("PING")
     if isinstance(result, tornadis.TornadisException):
         # For specific reasons, tornadis nearly never raises any exception

examples/pipeline.py

@@ -1,29 +1,37 @@
+# Let's import tornado and tornadis
 import tornado
 import tornadis
 
 
 @tornado.gen.coroutine
 def pipeline_coroutine():
-    # Let's get a connected client
-    client = tornadis.Client()
-
     # Let's make a pipeline object to stack commands inside
     pipeline = tornadis.Pipeline()
     pipeline.stack_call("SET", "foo", "bar")
     pipeline.stack_call("GET", "foo")
 
     # At this point, nothing is sent to redis
 
-    # Let's submit the pipeline to redis and wait for replies
+    # let's (re)connect (autoconnect mode), send the pipeline of requests
+    # (atomic mode) and wait all replies without blocking the tornado ioloop.
     results = yield client.call(pipeline)
 
-    # The two replies are in the results array
-    print results
-    # >>> ['OK', 'bar']
+    if isinstance(results, tornadis.TornadisException):
+        # For specific reasons, tornadis nearly never raises any exception
+        # they are returned as result
+        print "got exception: %s" % result
+    else:
+        # The two replies are in the results array
+        print results
+        # >>> ['OK', 'bar']
 
-    # Let's disconnect
-    client.disconnect()
 
+# Build a tornadis.Client object with some options as kwargs
+# host: redis host to connect
+# port: redis port to connect
+# autoconnect=True: put the Client object in auto(re)connect mode
+client = tornadis.Client(host="localhost", port=6379, autoconnect=True)
 
+# Start a tornado IOLoop, execute the coroutine and end the program
 loop = tornado.ioloop.IOLoop.instance()
 loop.run_sync(pipeline_coroutine)

tornadis/connection.py

@@ -62,8 +62,10 @@ def __init__(self, read_callback, close_callback,
         """Constructor.
 
         Args:
-            read_callback: callback called when there is something to read.
-            close_callback: callback called when the connection is closed.
+            read_callback: callback called when there is something to read
+                (private, do not use from Client constructor).
+            close_callback: callback called when the connection is closed
+                (private, do not use from Client constructor).
             host (string): the host name to connect to.
             port (int): the port to connect to.
             unix_domain_socket (string): path to a unix socket to connect to