Showing the points where Psycopg diverges from the DB API.

doc/connection.rst

@@ -26,6 +26,10 @@ The ``connection`` class
         cursors. The class returned should be a subclass of
         :class:`extensions.cursor`. See :ref:`subclassing-cursor` for details.
 
+        .. extension::
+
+            The :obj:`name` and :obj:`cursor_factory` parameters are Psycopg
+            extensions to the DB API.
 
     .. index::
         pair: Transaction; Commit
@@ -59,15 +63,28 @@ The ``connection`` class
         selected: see :meth:`connection.set_isolation_level()`).
 
 
+    .. index::
+        single: Exceptions; In the connection class
+
+    .. rubric:: Excetptions as connection class attributes
+
+    The :class:`connection` also exposes the same `Error` classes available in
+    the :mod:`psycopg2` module as attributes.
+
+
+    .. extension::
+
         The above methods are the only ones defined by the |DBAPI|_ protocol.
-    The Psycopg connection objects exports the following additional methods
+        The Psycopg connection objects exports the following additional
-    and attributes.
+        methods and attributes.
+
 
     .. attribute:: closed
 
         Read-only attribute reporting whether the database connection is open
         (0) or closed (1).
 
+
     .. attribute:: dsn
 
         Read-only string containing the connection string used by the
@@ -254,9 +271,3 @@ The ``connection`` class
         .. todo:: describe string_types
 
 
-    .. index::
-        single: Exceptions; In the connection class
-
-    The :class:`connection` also exposes the same `Error` classes available in
-    the :mod:`psycopg2` module as attributes.
-

doc/cursor.rst

@@ -47,6 +47,7 @@ The ``cursor`` class
         The type_code can be interpreted by comparing it to the Type Objects
         specified in the section :ref:`type-objects-and-constructors`.
 
+
     .. method:: close()
           
         Close the cursor now (rather than whenever ``__del__`` is called).
@@ -59,21 +60,37 @@ The ``cursor`` class
         Read-only boolean attribute: specifies if the cursor is closed
         (``True``) or not (``False``).
 
+        .. extension::
+
+            The :attr:`closed` attribute is a Psycopg extension to the
+            |DBAPI|.
+
+
     .. attribute:: connection
 
         Read-only attribute returning a reference to the :class:`connection`
         object on which the cursor was created.
 
+
     .. attribute:: name
 
         Read-only attribute containing the name of the cursor if it was
         creates as named cursor by :meth:`connection.cursor`, or ``None`` if
         it is a client side cursor.  See :ref:`server-side-cursors`.
 
+        .. extension::
+
+            The :attr:`name` attribute is a Psycopg extension to the |DBAPI|.
+
+
+    
     .. |execute*| replace:: :obj:`execute*()`
 
     .. _execute*:
 
+    .. rubric:: Commands execution methods
+
+
     .. method:: execute(operation [, parameters] [, async]) 
       
         Prepare and execute a database operation (query or command).
@@ -100,12 +117,22 @@ The ``cursor`` class
         ready for return via |fetch*|_ methods. See
         :ref:`asynchronous-queries`.
 
+        .. extension::
+
+            The :obj:`async` parameter is a Psycopg extension to the |DBAPI|.
+
+
     .. method:: mogrify(operation [, parameters)
 
         Return a query string after arguments binding. The string returned is
         exactly the one that would be sent to the database running the
         :meth:`execute()` method or similar.
 
+        .. extension::
+
+            The :meth:`mogrify` method is a Psycopg extension to the |DBAPI|.
+
+        
     .. method:: executemany(operation, seq_of_parameters)
       
         Prepare a database operation (query or command) and then execute it
@@ -118,6 +145,7 @@ The ``cursor`` class
         Parameters are bounded to the query using the same rules described in
         the :meth:`execute()` method.
 
+
     .. method:: callproc(procname [, parameters] [, async])
             
         Call a stored database procedure with the given name. The sequence of
@@ -135,42 +163,25 @@ The ``cursor`` class
         ready for return via |fetch*|_ methods. See
         :ref:`asynchronous-queries`.
 
-    .. attribute:: query
+        .. extension::
 
-        Read-only attribute containing the body of the last query sent to the
+            The :obj:`async` parameter is a Psycopg extension to the |DBAPI|.
-        backend (including bound arguments). ``None`` if no query has been
-        executed yet::
 
-            >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
-            >>> cur.query 
-            "INSERT INTO test (num, data) VALUES (42, E'bar')"
 
-    .. attribute:: statusmessage
+    .. method:: setinputsizes(sizes)
       
-        Return the message returned by the last command::
+        This method is exported in compliance with the |DBAPI|. It currently
+        does nothing but it is safe to call it.
 
-            >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
-            >>> cur.statusmessage 
-            'INSERT 0 1'
-
-    .. method:: isready()
-
-        Return ``False`` if the backend is still processing an asynchronous
-        query or ``True`` if data is ready to be fetched by one of the
-        |fetch*|_ methods.  See :ref:`asynchronous-queries`.
-
-    .. method:: fileno()
-
-        Return the file descriptor associated with the current connection and
-        make possible to use a cursor in a context where a file object would
-        be expected (like in a :func:`select()` call).  See
-        :ref:`asynchronous-queries`.
 
 
     .. |fetch*| replace:: :obj:`fetch*()`
 
     .. _fetch*:
 
+    .. rubric:: Results retrieval methods
+
+
     The following methods are used to read data from the database after an
     :meth:`execute()` call.
 
@@ -188,6 +199,7 @@ The ``cursor`` class
             (2, None, 'dada')
             (4, 42, 'bar')
 
+
     .. method:: fetchone()
 
         Fetch the next row of a query result set, returning a single tuple,
@@ -201,6 +213,7 @@ The ``cursor`` class
         to |execute*|_ did not produce any result set or no call was issued
         yet.
 
+
     .. method:: fetchmany([size=cursor.arraysize])
       
         Fetch the next set of rows of a query result, returning a list of
@@ -231,6 +244,7 @@ The ``cursor`` class
         is best for it to retain the same value from one :meth:`fetchmany()`
         call to the next.
 
+
     .. method:: fetchall()
 
         Fetch all (remaining) rows of a query result, returning them as a list
@@ -247,6 +261,7 @@ The ``cursor`` class
         to |execute*|_ did not produce any result set or no call was issued
         yet.
 
+
     .. method:: scroll(value[,mode='relative'])
 
         Scroll the cursor in the result set to a new position according
@@ -265,6 +280,7 @@ The ``cursor`` class
         The method can be used both for client-side cursors and server-side
         (named) cursors.
 
+
     .. attribute:: arraysize
           
         This read/write attribute specifies the number of rows to fetch at a
@@ -279,6 +295,7 @@ The ``cursor`` class
         .. todo:: copied from DB API: better specify what psycopg2 does with
             arraysize
 
+
     .. attribute:: rowcount 
           
         This read-only attribute specifies the number of rows that the last
@@ -294,6 +311,7 @@ The ``cursor`` class
             have the object return ``None`` instead of -1 in future versions
             of the specification.
         
+
     .. attribute:: rownumber
 
         This read-only attribute provides the current 0-based index of the
@@ -304,6 +322,7 @@ The ``cursor`` class
         set). The next fetch operation will fetch the row indexed by
         :attr:`rownumber` in that sequence.
 
+
     .. index:: oid
 
     .. attribute:: lastrowid
@@ -330,15 +349,72 @@ The ``cursor`` class
         This method is not supported (PostgreSQL does not have multiple data
         sets) and will raise a :exc:`NotSupportedError` exception.
 
-    .. method:: setinputsizes(sizes)
-      
-        This method currently does nothing but it is safe to call it.
 
     .. method:: setoutputsize(size [, column])
       
-        This method currently does nothing but it is safe to call it.
+        This method is exported in compliance with the |DBAPI|. It currently
+        does nothing but it is safe to call it.
 
 
+    .. attribute:: query
+
+        Read-only attribute containing the body of the last query sent to the
+        backend (including bound arguments). ``None`` if no query has been
+        executed yet::
+
+            >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
+            >>> cur.query 
+            "INSERT INTO test (num, data) VALUES (42, E'bar')"
+
+        .. extension::
+
+            The :attr:`query` attribute is a Psycopg extension to the |DBAPI|.
+
+
+    .. attribute:: statusmessage
+
+        Return the message returned by the last command::
+
+            >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
+            >>> cur.statusmessage 
+            'INSERT 0 1'
+
+        .. extension::
+
+            The :attr:`statusmessage` attribute is a Psycopg extension to the
+            |DBAPI|.
+
+
+    .. method:: isready()
+
+        Return ``False`` if the backend is still processing an asynchronous
+        query or ``True`` if data is ready to be fetched by one of the
+        |fetch*|_ methods.  See :ref:`asynchronous-queries`.
+
+        .. extension::
+
+            The :meth:`isready` method is a Psycopg extension to the |DBAPI|.
+
+
+    .. method:: fileno()
+
+        Return the file descriptor associated with the current connection and
+        make possible to use a cursor in a context where a file object would
+        be expected (like in a :func:`select()` call).  See
+        :ref:`asynchronous-queries`.
+
+        .. extension::
+
+            The :meth:`isready` method is a Psycopg extension to the |DBAPI|.
+
+
+
+    .. rubric:: COPY-related methods
+
+    .. extension::
+
+        The ``COPY`` support is a Psycopg extension to the |DBAPI|.
+
     .. method:: copy_from(file, table, sep='\\t', null='\\N', columns=None)
  
         Read data *from* the file-like object :obj:`file` appending them to
@@ -361,6 +437,7 @@ The ``cursor`` class
         .. versionchanged:: 2.0.6
             added the :obj:`columns` parameter.
 
+
     .. method:: copy_to(file, table, sep='\\t', null='\\N', columns=None)
 
         Write the content of the table named :obj:`table` *to* the file-like object :obj:`file`.  :obj:`file` must have a ``write()`` method. See
@@ -380,6 +457,7 @@ The ``cursor`` class
         .. versionchanged:: 2.0.6
             added the :obj:`columns` parameter.
 
+
     .. method:: copy_expert(sql, file [, size])
 
         Submit a user-composed ``COPY`` statement. The method is useful to
@@ -401,6 +479,9 @@ The ``cursor`` class
 
         .. versionadded:: 2.0.6
 
+
+    .. rubric:: Stuff to put elsewhere...
+
     .. attribute:: row_factory
 
         .. todo:: cursor.row_factory

doc/module.rst

@@ -45,6 +45,12 @@ The module interface respects the standard defined in the |DBAPI|_.
     taking a :obj:`dsn` argument. See :ref:`subclassing-connection` for
     details.
 
+    .. extension::
+
+        The :obj:`connection_factory` parameter is a Psycopg extension to the
+        |DBAPI|.
+
+
 .. data:: apilevel
 
     String constant stating the supported DB API level.  For :mod:`psycopg2` is
@@ -71,12 +77,6 @@ Exceptions
 In compliance with the |DBAPI|, the module makes informations about errors
 available through the following exceptions:
 
-.. todo::
-    There are actually a couple of extra extensions defined in _psycopg and
-    imported in the connection, but not in this module: shouldn't be there
-    them too?
-    
-
 .. exception:: Warning 
             
     Exception raised for important warnings like data truncations while