Added documentation for scrollable cursors

NEWS

@@ -1,6 +1,10 @@
 What's new in psycopg 2.4.6
 ---------------------------
 
+  - Added support for backward scrollable cursors. Thanks to Jon Nelson
+    for the initial patch (ticket #108).
+  - connection.reset() implemented using DISCARD ALL on server versions
+    supporting it.
   - Fixed 'cursor()' arguments propagation in connection subclasses
     and overriding of the 'cursor_factory' argument.  Thanks to
     Corry Haines for the report and the initial patch (ticket #105).
@@ -9,8 +13,6 @@ What's new in psycopg 2.4.6
     Thanks to Manu Cupcic for the report (ticket #110).
   - 'register_hstore()', 'register_composite()', 'tpc_recover()' work with
     RealDictConnection and Cursor (ticket #114).
-  - connection.reset() implemented using DISCARD ALL on server versions
-    supporting it.
 
 
 What's new in psycopg 2.4.5

doc/src/connection.rst

@@ -21,16 +21,17 @@ The ``connection`` class
     Connections are thread safe and can be shared among many threads. See
     :ref:`thread-safety` for details.
 
-    .. method:: cursor([name] [, cursor_factory] [, withhold])
+    .. method:: cursor(name=None, cursor_factory=None, scrollable=None, withhold=False)
           
         Return a new `cursor` object using the connection.
 
         If *name* is specified, the returned cursor will be a :ref:`server
         side cursor <server-side-cursors>` (also known as *named cursor*).
-        Otherwise it will be a regular *client side* cursor. By default a
+        Otherwise it will be a regular *client side* cursor.  By default a
-        :sql:`WITHOUT HOLD` cursor is created; to create a :sql:`WITH HOLD`
+        named cursor is declared without :sql:`SCROLL` option and
-        cursor, pass a `!True` value as the *withhold* parameter.  See
+        :sql:`WITHOUT HOLD`: set the argument or property `~cursor.scrollable`
-        :ref:`server-side-cursors`.
+        to `!True`/`!False` and or `~cursor.withhold` to `!True` to change the
+        declaration.
 
         The name can be a string not valid as a PostgreSQL identifier: for
         example it may start with a digit and contain non-alphanumeric
@@ -46,14 +47,16 @@ The ``connection`` class
             Consider it as part of the query, not as a query parameter.
 
         The *cursor_factory* argument can be used to create non-standard
-        cursors. The class returned should be a subclass of
+        cursors. The class returned must be a subclass of
         `psycopg2.extensions.cursor`. See :ref:`subclassing-cursor` for
         details.
 
+        .. versionchanged:: 2.4.3 added the *withhold* argument.
+        .. versionchanged:: 2.4.6 added the *scrollable* argument.
+
         .. extension::
 
-            The `name` and `cursor_factory` parameters are Psycopg
+            All the function arguments are Psycopg extensions to the |DBAPI|.
-            extensions to the |DBAPI|.
 
 
     .. index::

doc/src/cursor.rst

@@ -114,20 +114,51 @@ The ``cursor`` class
             The `name` attribute is a Psycopg extension to the |DBAPI|.
 
 
+    .. attribute:: scrollable
+
+        Read/write attribute: specifies if a named cursor is declared
+        :sql:`SCROLL`, hence is capable to scroll backwards (using
+        `~cursor.scroll()`). If `!True`, the cursor can be scrolled backwards,
+        if `!False` it is never scrollable. If `!None` (default) the cursor
+        scroll option is not specified, usually but not always meaning no
+        backward scroll (see the |declare-notes|__).
+
+        .. |declare-notes| replace:: :sql:`DECLARE` notes
+        .. __: http://www.postgresql.org/docs/current/static/sql-declare.html#SQL-DECLARE-NOTES
+
+        .. note::
+
+            set the value before calling `~cursor.execute()` or use the
+            `connection.cursor()` *scrollable* parameter, otherwise the value
+            will have no effect.
+
+        .. versionadded:: 2.4.6
+
+        .. extension::
+
+            The `scrollable` attribute is a Psycopg extension to the |DBAPI|.
+
+
     .. attribute:: withhold
-    
+
         Read/write attribute: specifies if a named cursor lifetime should
         extend outside of the current transaction, i.e., it is possible to
-        fetch from the cursor even after a `commection.commit()` (but not after
+        fetch from the cursor even after a `connection.commit()` (but not after
         a `connection.rollback()`).  See :ref:`server-side-cursors`
 
+        .. note::
+
+            set the value before calling `~cursor.execute()` or use the
+            `connection.cursor()` *withhold* parameter, otherwise the value
+            will have no effect.
+
         .. versionadded:: 2.4.3
-        
+
         .. extension::
 
             The `withhold` attribute is a Psycopg extension to the |DBAPI|.
-    
+
-    
+
     .. |execute*| replace:: `execute*()`
 
     .. _execute*:
@@ -297,7 +328,8 @@ The ``cursor`` class
         not changed.
 
         The method can be used both for client-side cursors and
-        :ref:`server-side cursors <server-side-cursors>`.
+        :ref:`server-side cursors <server-side-cursors>`. Server-side cursors
+        can usually scroll backwards only if declared `~cursor.scrollable`.
 
         .. note:: 
 

doc/src/usage.rst

@@ -576,7 +576,9 @@ cursor is created using the `~connection.cursor()` method specifying the
 *name* parameter. Such cursor will behave mostly like a regular cursor,
 allowing the user to move in the dataset using the `~cursor.scroll()`
 method and to read the data using `~cursor.fetchone()` and
-`~cursor.fetchmany()` methods.
+`~cursor.fetchmany()` methods. Normally you can only scroll forward in a
+cursor: if you need to scroll backwards you should declare your cursor
+`~cursor.scrollable`.
 
 Named cursors are also :ref:`iterable <cursor-iterable>` like regular cursors.
 Note however that before Psycopg 2.4 iteration was performed fetching one