work in progress

docs/api_client.rst

@@ -5,6 +5,7 @@ Client API
 
  .. autoclass:: Client
      :members:
+     :inherited-members:
      :show-inheritance:
 
      .. automethod:: __init__

docs/api_pubsub.rst

@@ -5,6 +5,7 @@ PubSubClient API
 
  .. autoclass:: PubSubClient
      :members:
+     :inherited-members:
      :show-inheritance:
 
      .. automethod:: __init__

docs/conf.py

@@ -287,3 +287,14 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = False
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = True
+napoleon_use_param = False
+napoleon_use_rtype = True

docs/index.rst

@@ -1,10 +1,8 @@
-.. tornadis documentation master file, created by
-   sphinx-quickstart on Tue Sep  9 21:29:37 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. title:: Tornadis library
 
 .. toctree::
    :titlesonly:
 
+   quickstart
    introduction
    api

docs/introduction.rst

@@ -1,5 +1,5 @@
-Getting started
----------------
+Introduction
+------------
 
 Let's see how to get started with tornadis using the `Client` class: In
 the following example, we connect to Redis and terminate the program

docs/quickstart.rst

@@ -0,0 +1,39 @@
+Quickstart
+==========
+
+Requirements
+------------
+
+- Python 2.7 or Python >= 3.2
+- unix operating system (linux, osx...)
+- a running redis server (>= 2.0)
+
+Installation
+------------
+
+With pip_ (without pip see at then end of this document)::
+
+    pip install tornadis
+
+First try
+---------
+
+.. literalinclude:: ../examples/coroutines.py
+    :language: python
+    :linenos:
+
+Installation without pip
+------------------------
+
+- install tornado_ >= 4.2
+- install `python wrapper for hiredis`_
+- install six_
+- download and uncompress a `tornadis release`_
+- run ``python setup.py install`` in the tornadis directory
+
+
+.. _pip : https://pypi.python.org/pypi/pip 
+.. _tornado: http://www.tornadoweb.org/
+.. _python wrapper for hiredis: https://github.com/redis/hiredis-py
+.. _six: https://pythonhosted.org/six/
+.. _tornadis release: https://github.com/thefab/tornadis/releases

examples/coroutines.py

@@ -1,16 +1,28 @@
+# Let's import tornado and tornadis
 import tornado
 import tornadis
-import logging
-logging.basicConfig(level=logging.CRITICAL)
 
 
 @tornado.gen.coroutine
 def talk_to_redis():
+    # let's (re)connect (autoconnect mode), call the ping redis command
+    # and wait the reply without blocking the tornado ioloop
     result = yield client.call("PING")
-    if not isinstance(result, tornadis.TornadisException):
+    if isinstance(result, tornadis.TornadisException):
+        # 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
 
 
+# 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(talk_to_redis)

tornadis/client.py

@@ -26,31 +26,42 @@ def discard_reply_cb(reply):
 
 
 class Client(object):
-    """High level object to interact with redis."""
+    """High level object to interact with redis.
+
+    Attributes:
+        autoconnect (boolean): True if the client is in autoconnect mode
+            (and in autoreconnection mode) (default True).
+        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
+            (if set, overrides host/port parameters).
+        read_page_size (int): page size for reading.
+        write_page_size (int): page size for writing.
+        connect_timeout (int): timeout (in seconds) for connecting.
+        tcp_nodelay (boolean): set TCP_NODELAY on socket.
+        aggressive_write (boolean): try to minimize write latency over
+            global throughput (default False).
+    """
 
     def __init__(self, autoconnect=True, **connection_kwargs):
         """Constructor.
 
-        Valid keys for \**connection_kwargs:
-
-        * 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 (if set, overrides host/port parameters).
-        * read_page_size (int): page size for reading.
-        * write_page_size (int): page size for writing.
-        * connect_timeout (int): timeout (in seconds) for connecting.
-        * tcp_nodelay (boolean): set TCP_NODELAY on socket.
-        * aggressive_write (boolean): try to minimize write latency over
-          global throughput (default False).
-        * ioloop (IOLoop): the tornado ioloop to use.
-
         Args:
             autoconnect (boolean): True if the client is in autoconnect mode
                 (and in autoreconnection mode) (default True).
-            **connection_kwargs: Connection object kwargs (see above).
+            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
+                (if set, overrides host/port parameters).
+            read_page_size (int): page size for reading.
+            write_page_size (int): page size for writing.
+            connect_timeout (int): timeout (in seconds) for connecting.
+            tcp_nodelay (boolean): set TCP_NODELAY on socket.
+            aggressive_write (boolean): try to minimize write latency over
+                global throughput (default False).
+            ioloop (IOLoop): the tornado ioloop to use.
         """
-        self.connection_kwargs = connection_kwargs
+        self._connection_kwargs = connection_kwargs
         self.autoconnect = autoconnect
         self.__connection = None
         self.subscribed = False
@@ -90,7 +101,7 @@ def connect(self):
         self.__callback_queue = collections.deque()
         self._reply_list = []
         self.__reader = hiredis.Reader(replyError=ClientError)
-        kwargs = self.connection_kwargs
+        kwargs = self._connection_kwargs
         self.__connection = Connection(cb1, cb2, **kwargs)
         return self.__connection.connect()
 

tornadis/connection.py

@@ -37,7 +37,20 @@
 
 
 class Connection(object):
-    """Low level connection object."""
+    """Low level connection object.
+
+    Attributes:
+        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
+            (if set, overrides host/port parameters).
+        read_page_size (int): page size for reading.
+        write_page_size (int): page size for writing.
+        connect_timeout (int): timeout (in seconds) for connecting.
+        tcp_nodelay (boolean): set TCP_NODELAY on socket.
+        aggressive_write (boolean): try to minimize write latency over
+            global throughput (default False).
+    """
 
     def __init__(self, read_callback, close_callback,
                  host=tornadis.DEFAULT_HOST,

tornadis/pipeline.py

@@ -24,6 +24,7 @@ class Pipeline(object):
     """
 
     def __init__(self):
+        """Constructor."""
         self.pipelined_args = []
         self.number_of_stacked_calls = 0
 

tornadis/pubsub.py

@@ -17,12 +17,28 @@ class PubSubClient(Client):
     The call() method is forbidden with this object.
 
     More informations on the redis side: http://redis.io/topics/pubsub
+
+    Attributes:
+        autoconnect (boolean): True if the client is in autoconnect mode
+            (and in autoreconnection mode) (default True).
+        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
+            (if set, overrides host/port parameters).
+        read_page_size (int): page size for reading.
+        write_page_size (int): page size for writing.
+        connect_timeout (int): timeout (in seconds) for connecting.
+        tcp_nodelay (boolean): set TCP_NODELAY on socket.
+        aggressive_write (boolean): try to minimize write latency over
+            global throughput (default False).
     """
 
     def call(self, *args, **kwargs):
+        """Not allowed method with PubSubClient object."""
         raise ClientError("not allowed with PubSubClient object")
 
     def async_call(self, *args, **kwargs):
+        """Not allowed method with PubSubClient object."""
         raise ClientError("not allowed with PubSubClient object")
 
     def pubsub_subscribe(self, *args):