more doc updates

aioredis/commands/__init__.py

@@ -18,9 +18,13 @@
 from .geo import GeoCommandsMixin, GeoPoint, GeoMember
 
 __all__ = [
-    'create_redis', 'Redis',
-    'Pipeline', 'MultiExec',
-    'GeoPoint', 'GeoMember',
+    'create_redis',
+    'create_redis_pool',
+    'Redis',
+    'Pipeline',
+    'MultiExec',
+    'GeoPoint',
+    'GeoMember',
 ]
 
 
@@ -160,7 +164,3 @@ def create_redis_pool(address, *, db=0, password=None, ssl=None,
 #                          db=db, password=password, ssl=ssl,
 #                          encoding=encoding, loop=loop)
 #     return commands_factory(conn)
-
-
-# make pyflakes happy
-(Pipeline, MultiExec)

aioredis/pool.py

@@ -47,8 +47,7 @@ def create_pool(address, *, db=0, password=None, ssl=None, encoding=None,
 
 
 class ConnectionsPool:
-    """Redis connections pool.
-    """
+    """Redis connections pool."""
 
     def __init__(self, address, db=0, password=None, encoding=None,
                  *, minsize, maxsize, ssl=None, loop=None):

docs/api_reference.rst

@@ -208,7 +208,6 @@ The library provides connections pool. The basic usage is as follows:
 
 .. code:: python
 
-   import asyncio
    import aioredis
 
    async def sample_pool():
@@ -226,6 +225,7 @@ The library provides connections pool. The basic usage is as follows:
    :class:`~.RedisConnection`.
 
 
+   .. TODO: rewrite this text
    .. By default it creates pool of :class:`Redis` instances, but it is
       also possible to create plain connections pool by passing
       ``lambda conn: conn`` as *commands_factory*.
@@ -550,17 +550,23 @@ to Redis commands.
                              loop=None)
 
    This :ref:`coroutine<coroutine>` creates high-level Redis
-   interface instance.
+   interface instance bound to single Redis connection
+   (without auto-reconnect).
+
+   See also :class:`~aioredis.RedisConnection` for parameters description.
+
+   For commands reference ---
+   see :ref:`commands mixins reference <aioredis-commands>`.
 
    :param address: An address where to connect. Can be a (host, port) tuple or
                    unix domain socket path string.
    :type address: tuple or str
 
    :param int db: Redis database index to switch to when connected.
 
-   :param password: Password to use if redis server instance requires
+   :param password: Password to use if Redis server instance requires
                     authorization.
-   :type password: str or None
+   :type password: str or bytes or None
 
    :param ssl: SSL context that is passed through to
                :func:`asyncio.BaseEventLoop.create_connection`.
@@ -570,42 +576,64 @@ to Redis commands.
    :type encoding: str or None
 
    :param commands_factory: A factory accepting single parameter --
-    :class:`RedisConnection` instance and returning an object providing
+    object implementing :class:`~abc.AbcConnection`
+    and returning an instance providing
     high-level interface to Redis. :class:`Redis` by default.
    :type commands_factory: callable
 
    :param loop: An optional *event loop* instance
                 (uses :func:`asyncio.get_event_loop` if not specified).
    :type loop: :ref:`EventLoop<asyncio-event-loop>`
 
+   :returns: Redis client (result of ``commands_factory`` call),
+             :class:`Redis` by default.
 
-.. NOTE: mark as deprecated
-.. cofunction:: create_reconnecting_redis(address, \*, db=0, password=None,\
-                           ssl=None, encoding=None, commands_factory=Redis,\
-                           loop=None)
 
-   Like :func:`create_redis` this :ref:`coroutine<coroutine>` creates
-   high-level Redis interface instance that may reconnect to redis server
-   between requests.  Accepts same arguments as :func:`create_redis`.
+.. cofunction:: create_redis_pool(address, \*, db=0, password=None, ssl=None,\
+                                  encoding=None, commands_factory=Redis,\
+                                  minsize=1, maxsize=10,\
+                                  loop=None)
 
-   The reconnect process is done at most once, at the start of the request. So
-   if your request is broken in the middle of sending or receiving reply, it
-   will not be repeated but an exception is raised.
+   This :ref:`coroutine<coroutine>` create high-level Redis client instance
+   bound to connections pool (this allows auto-reconnect and simple pub/sub
+   use).
 
-   .. note:: There are two important differences between :func:`create_redis`
-      and :func:`create_reconnecting_redis`:
+   See also :class:`~aioredis.ConnectionsPool` for parameters description.
 
-      1. The :func:`create_reconnecting_redis` does not establish connection
-         "right now", it defers connection establishing to the first request.
+   For commands reference ---
+   see :ref:`commands mixins reference <aioredis-commands>`.
 
-      2. Methods of :func:`Redis` factory returned do not buffer commands
-         until you `yield from` it. I.e. they are real coroutines not the
-         functions returning future. It may impact your pipelining.
+   :param address: An address where to connect. Can be a (host, port) tuple or
+                   unix domain socket path string.
+   :type address: tuple or str
 
+   :param int db: Redis database index to switch to when connected.
+   :param password: Password to use if Redis server instance requires
+                    authorization.
+   :type password: str or bytes or None
 
-.. class:: Redis(connection)
-   :noindex:
+   :param ssl: SSL context that is passed through to
+               :func:`asyncio.BaseEventLoop.create_connection`.
+   :type ssl: :class:`ssl.SSLContext` or True or None
 
-   High-level Redis commands interface.
+   :param encoding: Codec to use for response decoding.
+   :type encoding: str or None
+
+   :param commands_factory: A factory accepting single parameter --
+    object implementing :class:`~abc.AbcConnection` interface
+    and returning an instance providing
+    high-level interface to Redis. :class:`Redis` by default.
+   :type commands_factory: callable
+
+   :param int minsize: Minimum number of connections to initialize
+                       and keep in pool. Default is 1.
+
+   :param int maxsize: Maximum number of connections that can be created
+                       in pool. Default is 10.
+
+   :param loop: An optional *event loop* instance
+                (uses :func:`asyncio.get_event_loop` if not specified).
+   :type loop: :ref:`EventLoop<asyncio-event-loop>`
 
-   For details see :ref:`mixins<aioredis-commands>` reference.
+   :returns: Redis client (result of ``commands_factory`` call),
+             :class:`Redis` by default.

docs/mixins.rst

@@ -13,6 +13,10 @@ Descriptions are taken from ``docstrings`` so may not contain proper markup.
 .. autoclass:: aioredis.Redis
    :members:
 
+   :param pool_or_conn: Can be either :class:`~aioredis.RedisConnection`
+      or :class:`~aioredis.ConnectionsPool`.
+   :type pool_or_conn: :class:`~aioredis.abc.AbcConnection`
+
 Generic commands
 ----------------