docs: Improve documentation

Author: 1st1

asyncpg/connection.py

@@ -23,7 +23,7 @@
 class Connection:
     """A representation of a database session.
 
-    Connections are created by calling :func:`~asyncpg.connect`.
+    Connections are created by calling :func:`~asyncpg.connection.connect`.
     """
 
     __slots__ = ('_protocol', '_transport', '_loop', '_types_stmt',
@@ -361,7 +361,54 @@ async def connect(dsn=None, *,
                   statement_cache_size=100,
                   command_timeout=None,
                   **opts):
+    """A coroutine to establish a connection to a PostgreSQL server.
 
+    Returns a new :class:`~asyncpg.connection.Connection` object.
+
+    :param dsn: Connection arguments specified using as a single string in the
+                following format:
+                ``postgres://user:pass@host:port/database?option=value``
+
+    :param host: database host address or a path to the directory containing
+                 database server UNIX socket (defaults to the default UNIX
+                 socket, or the value of the ``PGHOST`` environment variable,
+                 if set).
+
+    :param port: connection port number (defaults to ``5432``, or the value of
+                 the ``PGPORT`` environment variable, if set)
+
+    :param user: the name of the database role used for authentication
+                 (defaults to the name of the effective user of the process
+                 making the connection, or the value of ``PGUSER`` environment
+                 variable, if set)
+
+    :param password: password used for authentication
+
+    :param loop: An asyncio event loop instance.  If ``None``, the default
+                 event loop will be used.
+
+    :param float timeout: connection timeout in seconds.
+
+    :param float command_timeout: the default timeout for operations on
+                          this connection (the default is no timeout).
+
+    :param int statement_cache_size: the size of prepared statement LRU cache.
+
+    :return: A :class:`~asyncpg.connection.Connection` instance.
+
+    Example:
+
+    .. code-block:: pycon
+
+        >>> import asyncpg
+        >>> import asyncio
+        >>> async def run():
+        ...     con = await asyncpg.connect(user='postgres')
+        ...     types = await con.fetch('SELECT * FROM pg_type')
+        ...     print(types)
+        >>> asyncio.get_event_loop().run_until_complete(run())
+        [<Record typname='bool' typnamespace=11 ...
+    """
     if loop is None:
         loop = asyncio.get_event_loop()
 

asyncpg/transaction.py

@@ -24,8 +24,9 @@ class TransactionState(enum.Enum):
 class Transaction:
     """Represents a transaction or savepoint block.
 
-    Transactions are created by calling
-    :meth:`Connection.transaction`.
+    Transactions are created by calling the
+    :meth:`Connection.transaction() <connection.Connection.transaction>`
+    function.
     """
 
     __slots__ = ('_connection', '_isolation', '_readonly', '_deferrable',

bench.py

@@ -0,0 +1,68 @@
+import asyncio
+import aiopg
+import asyncpg
+import time
+import uvloop
+
+
+async def bench_asyncpg(iters, size, query):
+    con = await asyncpg.connect(user='postgres', host='127.0.0.1',
+                                command_timeout=60)
+
+    started = time.monotonic()
+    for _ in range(iters):
+        await con.fetch(query)
+    print('-> asyncpg: {:.3} seconds'.format(time.monotonic() - started))
+
+
+async def bench_asyncpg_execute(iters, size, query):
+    con = await asyncpg.connect(user='postgres', host='127.0.0.1')
+
+    started = time.monotonic()
+    for _ in range(iters):
+        await con.execute(query)
+    print('-> asyncpg execute: {:.3} seconds'.format(
+        time.monotonic() - started))
+
+
+async def bench_aiopg(iters, size, query):
+    con = await aiopg.connect(user='postgres', host='127.0.0.1')
+
+    started = time.monotonic()
+    for _ in range(iters):
+        cur = await con.cursor(timeout=60)
+        await cur.execute(query)
+        await cur.fetchall()
+
+    print('-> aiopg: {:.3} seconds'.format(time.monotonic() - started))
+
+    con.close()
+
+
+async def print_debug(loop):
+    while True:
+        print(chr(27) + "[2J")  # clear screen
+        loop.print_debug_info()
+        await asyncio.sleep(0.5, loop=loop)
+
+
+if __name__ == '__main__':
+    iters = 10000
+    size = 1000
+
+    asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
+    loop = asyncio.get_event_loop()
+
+    # loop.create_task(print_debug(loop))
+
+    query = 'select generate_series(0,{})'.format(size)
+    query = '''select typname, typnamespace, typowner, typlen, typbyval,
+                      typcategory, typispreferred, typisdefined,
+                      typdelim, typrelid, typelem, typarray from pg_type'''
+
+    print(loop)
+    print('iters: {}; \nquery: {}'.format(iters, query))
+
+    loop.run_until_complete(bench_aiopg(iters, size, query))
+    loop.run_until_complete(bench_asyncpg(iters, size, query))
+    # loop.run_until_complete(bench_asyncpg_execute(iters, size, query))

docs/api/index.rst

@@ -15,51 +15,10 @@ API Reference
 Connection
 ==========
 
-.. coroutinefunction:: connect(dsn=None, *, host=None, port=None, \
-                        user=None, password=None, \
-                        database=None, loop=None, timeout=60, \
-                        statement_cache_size=100, \
-                        command_timeout=None, \
-                        **opts)
+.. autofunction:: asyncpg.connection.connect
 
-   Establish a connection to a PostgreSQL server and return a new
-   :class:`~asyncpg.connection.Connection` object.
 
-   :param dsn: Connection arguments specified using as a single string in the
-               following format:
-               ``postgres://user:pass@host:port/database?option=value``
-
-   :param host: database host address or a path to the directory containing
-                database server UNIX socket (defaults to the default UNIX
-                socket, or the value of the ``PGHOST`` environment variable,
-                if set).
-
-   :param port: connection port number (defaults to ``5432``, or the value of
-                the ``PGPORT`` environment variable, if set)
-
-   :param user: the name of the database role used for authentication
-                (defaults to the name of the effective user of the process
-                making the connection, or the value of ``PGUSER`` environment
-                variable, if set)
-
-   :param password: password used for authentication
-
-   :param loop: An asyncio event loop instance.  If ``None``, the default
-                event loop will be used.
-
-   :param float timeout: connection timeout (in seconds, defaults to 60
-                         seconds).
-
-   :param float statement_timeout: the default timeout for operations on
-                         this connection (the default is no timeout).
-
-   :param int statement_cache_size: the size of prepared statement LRU cache
-                         (defaults to 100).
-
-   :returns: :class:`~asyncpg.connection.Connection` instance.
-
-
-.. autoclass:: asyncpg.connection.Connection()
+.. autoclass:: asyncpg.connection.Connection
    :members:
 
 
@@ -149,6 +108,10 @@ Alternatively, transactions can be used without an ``async with`` block:
         await tr.commit()
 
 
+See also the
+:meth:`Connection.transaction() <asyncpg.connection.Connection.transaction>`
+function.
+
 .. _savepoint: https://www.postgresql.org/docs/current/static/sql-savepoint.html
 
 
@@ -233,15 +196,15 @@ It's also possible to create cursors from prepared statements:
 .. note::
 
    Cursors created by a call to
-   :meth:`Conection.cursor() <asyncpg.connection.Connection.cursor>` or
+   :meth:`Connection.cursor() <asyncpg.connection.Connection.cursor>` or
    :meth:`PreparedStatement.cursor() <asyncpg.prepared_stmt.PreparedStatement.cursor>`
    are *non-scrollable*: they can only be read forwards.  To create a scrollable
    cursor, use the ``DECLARE ... SCROLL CURSOR`` SQL statement directly.
 
 .. warning::
 
    Cursors created by a call to
-   :meth:`Conection.cursor() <asyncpg.connection.Connection.cursor>` or
+   :meth:`Connection.cursor() <asyncpg.connection.Connection.cursor>` or
    :meth:`PreparedStatement.cursor() <asyncpg.prepared_stmt.PreparedStatement.cursor>`
    cannot be used outside of a transaction.  Any such attempt will result in
    :exc:`~asyncpg.exceptions.InterfaceError`.
@@ -268,6 +231,18 @@ It's also possible to create cursors from prepared statements:
    :members:
 
 
+.. _asyncpg-api-pool:
+
+Connection Pool
+===============
+
+.. autofunction:: asyncpg.pool.create_pool
+
+
+.. autoclass:: asyncpg.pool.Pool()
+   :members:
+
+
 .. _asyncpg-api-record:
 
 Record Objects
@@ -284,9 +259,14 @@ of values either by a numeric index or by a field name:
     >>> import asyncio
     >>> loop = asyncio.get_event_loop()
     >>> conn = loop.run_until_complete(asyncpg.connect())
-    >>> loop.run_until_complete(conn.fetchrow('''
+    >>> r = loop.run_until_complete(conn.fetchrow('''
     ...     SELECT oid, rolname, rolsuper FROM pg_roles WHERE rolname = user'''))
+    >>> r
     <Record oid=16388 rolname='elvis' rolsuper=True>
+    >>> r['oid']
+    16388
+    >>> r[0]
+    16388
 
 
 .. class:: Record()

docs/conf.py

@@ -24,6 +24,8 @@
     'sphinxcontrib.asyncio',
 ]
 
+add_module_names = False
+
 templates_path = ['_templates']
 source_suffix = '.rst'
 master_doc = 'index'