Document more of asyncpg public API

Author: elprans

asyncpg/connection.py

@@ -21,6 +21,10 @@
 
 
 class Connection:
+    """A representation of a database session.
+
+    Connections are created by calling :func:`~asyncpg.connect`.
+    """
 
     __slots__ = ('_protocol', '_transport', '_loop', '_types_stmt',
                  '_type_by_name_stmt', '_top_xact', '_uid', '_aborted',
@@ -52,7 +56,23 @@ def get_settings(self):
 
     def transaction(self, *, isolation='read_committed', readonly=False,
                     deferrable=False):
+        """Create a :class:`~transaction.Transaction` object.
+
+        Refer to `PostgreSQL documentation`_ on the meaning of transaction
+        parameters.
+
+        :param isolation: Transaction isolation mode, can be one of:
+                          `'serializable'`, `'repeatable_read'`,
+                          `'read_committed'`.
+
+        :param readonly: Specifies whether or not this transaction is
+                         read-only.
+
+        :param deferrable: Specifies whether or not this transaction is
+                           deferrable.
 
+        .. _`PostgreSQL documentation`: https://www.postgresql.org/docs/current/static/sql-set-transaction.html
+        """
         return transaction.Transaction(self, isolation, readonly, deferrable)
 
     async def execute(self, script: str, *, timeout: float=None) -> str:
@@ -110,32 +130,36 @@ async def prepare(self, query, *, timeout=None):
         :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.
+        :return: A :class:`~prepared_stmt.PreparedStatement` instance.
         """
         stmt = await self._get_statement(query, timeout)
         return prepared_stmt.PreparedStatement(self, query, stmt)
 
-    async def fetch(self, query, *args, timeout=None):
+    async def fetch(self, query, *args, timeout=None) -> list:
         """Run a query and return the results as a list of :class:`Record`.
 
-        :param str query: Query text
-        :param args: Query arguments
+        :param str query: Query text.
+        :param args: Query arguments.
         :param int timeout: Optional timeout value in seconds.
 
-        :return: A list of :class:`Record` instances.
+        :return list: 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.
+        """Run a query and return a value in the first row.
 
-        :param str query: Query text
-        :param args: Query arguments
-        :param int timeout: Optional column index (defaults to 0).
+        :param str query: Query text.
+        :param args: Query arguments.
+        :param int column: Numeric index within the record of the value to
+                           return (defaults to 0).
         :param int timeout: Optional timeout value in seconds.
+                            If not specified, defaults to the value of
+                            ``command_timeout`` argument to the ``Connection``
+                            instance constructor.
 
         :return: The value of the specified column of the first record.
         """

asyncpg/cursor.py

@@ -12,6 +12,11 @@
 
 
 class CursorInterface:
+    """A cursor interface for the results of a query.
+
+    A cursor interface can be used to initiate efficient traversal of the
+    results of a large query.
+    """
 
     __slots__ = ('_state', '_connection', '_args', '_prefetch',
                  '_query', '_timeout')
@@ -181,6 +186,7 @@ async def __anext__(self):
 
 
 class Cursor(BaseCursor):
+    """An open *portal* into the results of a query."""
 
     __slots__ = ()
 
@@ -194,6 +200,12 @@ async def _init(self, timeout):
         return self
 
     async def fetch(self, n, *, timeout=None):
+        r"""Return the next *n* rows as a list of :class:`Record` objects.
+
+        :param float timeout: Optional timeout value in seconds.
+
+        :return: A list of :class:`Record` instances.
+        """
         self._check_ready()
         if n <= 0:
             raise exceptions.InterfaceError('n must be greater than zero')
@@ -205,6 +217,12 @@ async def fetch(self, n, *, timeout=None):
         return recs
 
     async def fetchrow(self, *, timeout=None):
+        r"""Return the next row.
+
+        :param float timeout: Optional timeout value in seconds.
+
+        :return: A :class:`Record` instance.
+        """
         self._check_ready()
         if self._exhausted:
             return None
@@ -214,7 +232,13 @@ async def fetchrow(self, *, timeout=None):
             return None
         return recs[0]
 
-    async def forward(self, n, *, timeout=None):
+    async def forward(self, n, *, timeout=None) -> int:
+        r"""Skip over the next *n* rows.
+
+        :param float timeout: Optional timeout value in seconds.
+
+        :return: A number of rows actually skipped over (<= *n*).
+        """
         self._check_ready()
         if n <= 0:
             raise exceptions.InterfaceError('n must be greater than zero')

asyncpg/prepared_stmt.py

@@ -12,6 +12,7 @@
 
 
 class PreparedStatement:
+    """A representation of a prepared statement."""
 
     __slots__ = ('_connection', '_state', '_query', '_last_status')
 
@@ -22,11 +23,11 @@ def __init__(self, connection, query, state):
         state.attach()
         self._last_status = None
 
-    def get_query(self):
+    def get_query(self) -> str:
         """Return the text of the query for this prepared statement."""
         return self._query
 
-    def get_statusmsg(self):
+    def get_statusmsg(self) -> str:
         """Return the status of the executed command."""
         if self._last_status is None:
             return self._last_status
@@ -40,13 +41,33 @@ def get_attributes(self):
         self.__check_open()
         return self._state._get_attributes()
 
-    def cursor(self, *args, prefetch=None, timeout=None):
+    def cursor(self, *args, prefetch=50,
+               timeout=None) -> cursor.CursorInterface:
+        """Return a *cursor interface* for the prepared statement.
+
+        :param args: Query arguments.
+        :param int prefetch: The number of rows the *cursor iterator*
+                             will prefetch (defaults to ``50``.)
+        :param float timeout: Optional timeout in seconds.
+
+        :return: A :class:`~cursor.CursorInterface` object.
+        """
         self.__check_open()
         return cursor.CursorInterface(self._connection, self._query,
                                       self._state, args, prefetch,
                                       timeout)
 
     async def explain(self, *args, analyze=False):
+        """Return the execution plan of the statement.
+
+        :param args: Query arguments.
+        :param analyze: If ``True``, the statement will be executed and
+                        the run time statitics added to the return value.
+
+        :return: An object representing the execution plan.  This value
+                 is actually a deserialized JSON output of the SQL
+                 ``EXPLAIN`` command.
+        """
         query = 'EXPLAIN (FORMAT JSON, VERBOSE'
         if analyze:
             query += ', ANALYZE) '
@@ -78,7 +99,8 @@ 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`.
+        r"""Execute the statement and return the results as a list \
+            of :class:`Record` objects.
 
         :param str query: Query text
         :param args: Query arguments
@@ -94,12 +116,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.
+        """Execute the statement and return a value in the first row.
 
-        :param args: Query arguments
-        :param int timeout: Optional column index (defaults to 0).
+        :param args: Query arguments.
+        :param int column: Numeric index within the record of the value to
+                           return (defaults to 0).
         :param int timeout: Optional timeout value in seconds.
+                            If not specified, defaults to the value of
+                            ``command_timeout`` argument to the ``Connection``
+                            instance constructor.
 
         :return: The value of the specified column of the first record.
         """

asyncpg/transaction.py

@@ -22,6 +22,11 @@ class TransactionState(enum.Enum):
 
 
 class Transaction:
+    """Represents a transaction or savepoint block.
+
+    Transactions are created by calling
+    :meth:`Connection.transaction`.
+    """
 
     __slots__ = ('_connection', '_isolation', '_readonly', '_deferrable',
                  '_state', '_nested', '_id', '_managed')
@@ -69,6 +74,7 @@ async def __aexit__(self, extype, ex, tb):
             self._managed = False
 
     async def start(self):
+        """Enter the transaction or savepoint block."""
         self.__check_state_base('start')
         if self._state is TransactionState.STARTED:
             raise apg_errors.InterfaceError(
@@ -173,12 +179,14 @@ async def __rollback(self):
             self._state = TransactionState.ROLLEDBACK
 
     async def commit(self):
+        """Exit the transaction or savepoint block and commit changes."""
         if self._managed:
             raise apg_errors.InterfaceError(
                 'cannot manually commit from within an `async with` block')
         await self.__commit()
 
     async def rollback(self):
+        """Exit the transaction or savepoint block and rollback changes."""
         if self._managed:
             raise apg_errors.InterfaceError(
                 'cannot manually rollback from within an `async with` block')