Initial documentation pass

Author: elprans

asyncpg/connection.py

@@ -104,16 +104,40 @@ def cursor(self, query, *args, prefetch=None, timeout=None):
         return cursor.CursorFactory(self, query, None, args, prefetch, timeout)
 
     async def prepare(self, query, *, timeout=None):
+        """Create a *prepared statement* for the specified query.
+
+        :param str query: Text of the query to create a prepared statement for.
+        :param int timeout: Optional timeout value in seconds.
+
+        :return: A :class:`PreparedStatement` instance.
+        """
         stmt = await self._get_statement(query, timeout)
         return prepared_stmt.PreparedStatement(self, query, stmt)
 
     async def fetch(self, query, *args, timeout=None):
+        """Run a query and return the results as a list of :class:`Record`.
+
+        :param str query: Query text
+        :param args: Query arguments
+        :param int timeout: Optional timeout value in seconds.
+
+        :return: A list of :class:`Record` instances.
+        """
         stmt = await self._get_statement(query, timeout)
         protocol = self._protocol
         data = await protocol.bind_execute(stmt, args, '', 0, False, timeout)
         return data
 
     async def fetchval(self, query, *args, column=0, timeout=None):
+        """Run a query and return the value of the specified column of the first row.
+
+        :param str query: Query text
+        :param args: Query arguments
+        :param int timeout: Optional column index (defaults to 0).
+        :param int timeout: Optional timeout value in seconds.
+
+        :return: The value of the specified column of the first record.
+        """
         stmt = await self._get_statement(query, timeout)
         protocol = self._protocol
         data = await protocol.bind_execute(stmt, args, '', 1, False, timeout)
@@ -122,6 +146,14 @@ async def fetchval(self, query, *args, column=0, timeout=None):
         return data[0][column]
 
     async def fetchrow(self, query, *args, timeout=None):
+        """Run a query and return the first row.
+
+        :param str query: Query text
+        :param args: Query arguments
+        :param int timeout: Optional timeout value in seconds.
+
+        :return: The first row as a :class:`Record` instance.
+        """
         stmt = await self._get_statement(query, timeout)
         protocol = self._protocol
         data = await protocol.bind_execute(stmt, args, '', 1, False, timeout)
@@ -191,9 +223,15 @@ async def set_builtin_type_codec(self, typename, *,
             oid, typename, schema, 'scalar', codec_name)
 
     def is_closed(self):
+        """Return ``True`` if the connection is closed, ``False`` otherwise.
+
+        :return bool: ``True`` if the connection is closed, ``False``
+                      otherwise.
+        """
         return not self._protocol.is_connected() or self._aborted
 
     async def close(self):
+        """Close the connection gracefully."""
         if self.is_closed():
             return
         self._close_stmts()
@@ -202,6 +240,7 @@ async def close(self):
         await protocol.close()
 
     def terminate(self):
+        """Terminate the connection without waiting for pending data."""
         self._close_stmts()
         self._aborted = True
         self._protocol.abort()

asyncpg/prepared_stmt.py

@@ -23,9 +23,11 @@ def __init__(self, connection, query, state):
         self._last_status = None
 
     def get_query(self):
+        """Return the text of the query for this prepared statement."""
         return self._query
 
     def get_statusmsg(self):
+        """Return the status of the executed command."""
         if self._last_status is None:
             return self._last_status
         return self._last_status.decode()
@@ -76,6 +78,14 @@ async def explain(self, *args, analyze=False):
         return json.loads(data)
 
     async def fetch(self, *args, timeout=None):
+        """Execute the statement and return the results as a list of :class:`Record`.
+
+        :param str query: Query text
+        :param args: Query arguments
+        :param int timeout: Optional timeout value in seconds.
+
+        :return: A list of :class:`Record` instances.
+        """
         self.__check_open()
         protocol = self._connection._protocol
         data, status, _ = await protocol.bind_execute(
@@ -84,6 +94,15 @@ async def fetch(self, *args, timeout=None):
         return data
 
     async def fetchval(self, *args, column=0, timeout=None):
+        r"""Execute the statement and return the value of the specified \
+        column of the first row.
+
+        :param args: Query arguments
+        :param int timeout: Optional column index (defaults to 0).
+        :param int timeout: Optional timeout value in seconds.
+
+        :return: The value of the specified column of the first record.
+        """
         self.__check_open()
         protocol = self._connection._protocol
         data, status, _ = await protocol.bind_execute(
@@ -94,6 +113,14 @@ async def fetchval(self, *args, column=0, timeout=None):
         return data[0][column]
 
     async def fetchrow(self, *args, timeout=None):
+        """Execute the statement and return the first row.
+
+        :param str query: Query text
+        :param args: Query arguments
+        :param int timeout: Optional timeout value in seconds.
+
+        :return: The first row as a :class:`Record` instance.
+        """
         self.__check_open()
         protocol = self._connection._protocol
         data, status, _ = await protocol.bind_execute(

docs/.gitignore

@@ -0,0 +1,3 @@
+_build
+_static
+_templates

docs/api/index.rst

@@ -0,0 +1,66 @@
+.. _asyncpg-api-reference:
+
+=============
+API Reference
+=============
+
+.. module:: asyncpg
+    :synopsis: A fast PostgreSQL Database Client Library for Python/asyncio
+.. currentmodule:: asyncpg
+
+
+.. _asyncpg-api-connection:
+
+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)
+
+   Establish a connection to a :term:`PostgreSQL` server and return a new
+   :class:`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:`Connection` instance.
+
+
+.. autoclass:: asyncpg.connection.Connection
+   :members:
+
+
+.. autoclass:: asyncpg.prepared_stmt.PreparedStatement
+  :members:

docs/conf.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+
+import alabaster
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.abspath('..'))
+
+with open(os.path.abspath('../setup.py'), 'rt') as f:
+    _m = re.search(r'''version=(?P<q>'|")(?P<ver>[\d\.]+)(?P=q)''', f.read())
+    if not _m:
+        raise RuntimeError('unable to read the version from setup.py')
+    version = _m.group('ver')
+
+
+# -- General configuration ------------------------------------------------
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinxcontrib.asyncio',
+    'alabaster',
+]
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+project = 'asyncpg'
+copyright = '2016-present, the ayncpg authors and contributors'
+author = '<See AUTHORS file>'
+release = version
+language = None
+exclude_patterns = ['_build']
+pygments_style = 'sphinx'
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+html_theme = 'alabaster'
+html_theme_options = {
+    'description': 'asyncpg is a fast PostgreSQL client library for the '
+                   'Python asyncio framework',
+    'show_powered_by': False,
+}
+html_theme_path = [alabaster.get_path()]
+html_title = 'asyncpg Documentation'
+html_short_title = 'asyncpg'
+html_static_path = []
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+    ]
+}
+html_show_sourcelink = False
+html_show_sphinx = False
+html_show_copyright = True
+htmlhelp_basename = 'asyncpgdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {}
+
+latex_documents = [
+    (master_doc, 'asyncpg.tex', 'asyncpg Documentation',
+     author, 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+man_pages = [
+    (master_doc, 'asyncpg', 'asyncpg Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+texinfo_documents = [
+    (master_doc, 'asyncpg', 'asyncpg Documentation',
+     author, 'asyncpg',
+     'asyncpg is a fast PostgreSQL client library for the '
+     'Python asyncio framework',
+     'Miscellaneous'),
+]

docs/index.rst

@@ -0,0 +1,23 @@
+.. image:: https://travis-ci.org/MagicStack/asyncpg.svg?branch=master
+    :target: https://travis-ci.org/MagicStack/asyncpg
+
+.. image:: https://img.shields.io/pypi/status/asyncpg.svg?maxAge=2592000?style=plastic
+    :target: https://pypi.python.org/pypi/asyncpg
+
+
+asyncpg
+=======
+
+**asyncpg** is a database interface library designed specifically for
+PostgreSQL and Python/asyncio.  asyncpg is an efficient, clean implementation
+of PostgreSQL server binary protocol for use with Python's ``asyncio``
+framework.
+
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   api/index

docs/requirements.txt

@@ -0,0 +1 @@
+sphinxcontrib-asyncio