#1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods.

1 files changed, 31 insertions, 3 deletions

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index c42a1d7..6c6cf03 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -1,4 +1,3 @@
-
 :mod:`sqlite3` --- DB-API 2.0 interface for SQLite databases
 ============================================================
 
@@ -389,7 +388,7 @@ A :class:`Cursor` instance has the following attributes and methods:
 
 .. method:: Cursor.execute(sql, [parameters])
 
-   Executes a SQL statement. The SQL statement may be parametrized (i. e.
+   Executes an SQL statement. The SQL statement may be parametrized (i. e.
    placeholders instead of SQL literals). The :mod:`sqlite3` module supports two
    kinds of placeholders: question marks (qmark style) and named placeholders
    (named style).
@@ -410,7 +409,7 @@ A :class:`Cursor` instance has the following attributes and methods:
 
 .. method:: Cursor.executemany(sql, seq_of_parameters)
 
-   Executes a SQL command against all parameter sequences or mappings found in
+   Executes an SQL command against all parameter sequences or mappings found in
    the sequence *sql*.  The :mod:`sqlite3` module also allows using an
    :term:`iterator` yielding parameters instead of a sequence.
 
@@ -434,6 +433,35 @@ A :class:`Cursor` instance has the following attributes and methods:
    .. literalinclude:: ../includes/sqlite3/executescript.py
 
 
+.. method:: Cursor.fetchone() 
+          
+   Fetches the next row of a query result set, returning a single sequence,
+   or ``None`` when no more data is available.
+
+
+.. method:: Cursor.fetchmany([size=cursor.arraysize])
+          
+   Fetches the next set of rows of a query result, returning a list.  An empty
+   list is returned when no more rows are available.
+   
+   The number of rows to fetch per call is specified by the *size* parameter.
+   If it is not given, the cursor's arraysize determines the number of rows
+   to be fetched. The method should try to fetch as many rows as indicated by
+   the size parameter. If this is not possible due to the specified number of
+   rows not being available, fewer rows may be returned.
+   
+   Note there are performance considerations involved with the *size* parameter.
+   For optimal performance, it is usually best to use the arraysize attribute.
+   If the *size* parameter is used, then it is best for it to retain the same
+   value from one :meth:`fetchmany` call to the next.
+            
+.. method:: Cursor.fetchall() 
+
+   Fetches all (remaining) rows of a query result, returning a list.  Note that
+   the cursor's arraysize attribute can affect the performance of this operation.
+   An empty list is returned when no rows are available.
+
+
 .. attribute:: Cursor.rowcount
 
    Although the :class:`Cursor` class of the :mod:`sqlite3` module implements this