Expand usage documentation, add FAQ.

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/faq.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/index.rst

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