Expand usage documentation, add FAQ.

Author: elprans

asyncpg/connection.py

@@ -378,11 +378,25 @@ async def copy_from_table(self, table_name, *, output,
 
         :return: The status string of the COPY command.
 
-        .. versionadded:: 0.11.0
+        Example:
+
+        .. code-block:: pycon
+
+            >>> import asyncpg
+            >>> import asyncio
+            >>> async def run():
+            ...     con = await asyncpg.connect(user='postgres')
+            ...     result = await con.copy_from_table(
+            ...         'mytable', columns=('foo', 'bar'),
+            ...         output='file.csv', format='csv')
+            ...     print(result)
+            >>> asyncio.get_event_loop().run_until_complete(run())
+            'COPY 100'
 
         .. _`COPY statement documentation`: https://www.postgresql.org/docs/\
                                             current/static/sql-copy.html
 
+        .. versionadded:: 0.11.0
         """
         tabname = utils._quote_ident(table_name)
         if schema_name:
@@ -415,7 +429,7 @@ async def copy_from_query(self, query, *args, output,
         :param str query:
             The query to copy the results of.
 
-        :param *args:
+        :param \*args:
             Query arguments.
 
         :param output:
@@ -432,11 +446,25 @@ async def copy_from_query(self, query, *args, output,
 
         :return: The status string of the COPY command.
 
-        .. versionadded:: 0.11.0
+        Example:
+
+        .. code-block:: pycon
+
+            >>> import asyncpg
+            >>> import asyncio
+            >>> async def run():
+            ...     con = await asyncpg.connect(user='postgres')
+            ...     result = await con.copy_from_query(
+            ...         'SELECT foo, bar FROM mytable WHERE foo > $1', 10,
+            ...         output='file.csv', format='csv')
+            ...     print(result)
+            >>> asyncio.get_event_loop().run_until_complete(run())
+            'COPY 10'
 
         .. _`COPY statement documentation`: https://www.postgresql.org/docs/\
                                             current/static/sql-copy.html
 
+        .. versionadded:: 0.11.0
         """
         opts = self._format_copy_opts(
             format=format, oids=oids, delimiter=delimiter,
@@ -469,7 +497,7 @@ async def copy_to_table(self, table_name, *, source,
             or a :term:`file-like object <python:file-like object>`, or
             an :term:`asynchronous iterable <python:asynchronous iterable>`
             that returns ``bytes``, or an object supporting the
-            :term:`buffer protocol <python:buffer protocol>`.
+            :ref:`buffer protocol <python:bufferobjects>`.
 
         :param list columns:
             An optional list of column names to copy.
@@ -485,11 +513,24 @@ async def copy_to_table(self, table_name, *, source,
 
         :return: The status string of the COPY command.
 
-        .. versionadded:: 0.11.0
+        Example:
+
+        .. code-block:: pycon
+
+            >>> import asyncpg
+            >>> import asyncio
+            >>> async def run():
+            ...     con = await asyncpg.connect(user='postgres')
+            ...     result = await con.copy_to_table(
+            ...         'mytable', source='datafile.tbl')
+            ....    print(result)
+            >>> asyncio.get_event_loop().run_until_complete(run())
+            'COPY 140000'
 
         .. _`COPY statement documentation`: https://www.postgresql.org/docs/\
                                             current/static/sql-copy.html
 
+        .. versionadded:: 0.11.0
         """
         tabname = utils._quote_ident(table_name)
         if schema_name:
@@ -535,6 +576,22 @@ async def copy_records_to_table(self, table_name, *, records,
 
         :return: The status string of the COPY command.
 
+        Example:
+
+        .. code-block:: pycon
+
+            >>> import asyncpg
+            >>> import asyncio
+            >>> async def run():
+            ...     con = await asyncpg.connect(user='postgres')
+            ...     result = await con.copy_records_to_table(
+            ...         'mytable', records=[
+            ...             (1, 'foo', 'bar'),
+            ...             (2, 'ham', 'spam')])
+            ....    print(result)
+            >>> asyncio.get_event_loop().run_until_complete(run())
+            'COPY 2'
+
         .. versionadded:: 0.11.0
         """
         tabname = utils._quote_ident(table_name)

docs/api/index.rst

@@ -233,8 +233,8 @@ It's also possible to create cursors from prepared statements:
 
 .. _asyncpg-api-pool:
 
-Connection Pool
-===============
+Connection Pools
+================
 
 .. autofunction:: asyncpg.pool.create_pool
 
@@ -326,11 +326,8 @@ items either by a numeric index or by a field name:
            'UTF8'
 
 
-Introspection
-=============
-
-.. autoclass:: asyncpg.types.Type()
-   :members:
+Data Types
+==========
 
-.. autoclass:: asyncpg.types.Attribute()
+.. automodule:: asyncpg.types
    :members:

docs/examples.rst

@@ -0,0 +1,41 @@
+.. _asyncpg-faq:
+
+
+Frequently Asked Questions
+==========================
+
+Does asyncpg support DB-API?
+    No.  DB-API is a synchronous API, while asyncpg is based
+    around an asynchronous I/O model.  Thus, full drop-in compatibility
+    with DB-API is not possible and we decided to design asyncpg API
+    in a way that is better aligned with PostgreSQL architecture and
+    terminology.  We will release a synchronous DB-API-compatible version
+    of asyncpg at some point in the future.
+
+Can I use asyncpg with SQLAlchemy ORM?
+    Short answer: no.  asyncpg uses asynchronous execution model
+    and API, which is fundamentally incompatible with asyncpg.
+    However, it is possible to use asyncpg and SQLAlchemy Core
+    with the help of a third-party adapter, such as asyncpgsa_.
+
+Can I use dot-notation with :class:`asyncpg.Record`?  It looks cleaner.
+    We decided against making :class:`asyncpg.Record` a named tuple
+    because we want to keep the ``Record`` method namespace separate
+    from the column namespace.
+
+Why can't I use a :ref:`cursor <asyncpg-api-cursor>` outside of a transaction?
+    Cursors created by a call to
+    :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
+    ``InterfaceError``.
+    To create a cursor usable outside of a transaction, use the
+    ``DECLARE ... CURSOR WITH HOLD`` SQL statement directly.
+
+Why do I get ``PostgresSyntaxError`` when using ``expression IN $1``?
+    ``expression IN $1`` is not a valid PostgreSQL syntax.  To check
+    a value against a sequence use ``expression = any($1::mytype[])``,
+    where ``mytype`` is the array element type.
+
+.. _asyncpgsa: https://github.com/CanopyTax/asyncpgsa

docs/faq.rst

@@ -24,5 +24,6 @@ Contents
    :maxdepth: 2
 
    installation
-   examples
+   usage
    api/index
+   faq