[Python-checkins] r60103 - in python/trunk: Doc/library/sqlite3.rst Modules/_sqlite/cursor.c

Sat Jan 19 21:53:08 CET 2008

Author: georg.brandl
Date: Sat Jan 19 21:53:07 2008
New Revision: 60103
Modified:
 python/trunk/Doc/library/sqlite3.rst
 python/trunk/Modules/_sqlite/cursor.c
Log:
#1509: fix sqlite3 docstrings and docs w.r.t. cursor.fetchXXX methods.
Modified: python/trunk/Doc/library/sqlite3.rst
==============================================================================

--- python/trunk/Doc/library/sqlite3.rst	(original)
+++ python/trunk/Doc/library/sqlite3.rst	Sat Jan 19 21:53:07 2008
@@ -1,4 +1,3 @@
-
 :mod:`sqlite3` --- DB-API 2.0 interface for SQLite databases
 ============================================================
 
@@ -389,7 +388,7 @@
 
 .. 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 @@
 
 .. 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 @@
 .. 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
Modified: python/trunk/Modules/_sqlite/cursor.c
==============================================================================
--- python/trunk/Modules/_sqlite/cursor.c	(original)
+++ python/trunk/Modules/_sqlite/cursor.c	Sat Jan 19 21:53:07 2008
@@ -991,11 +991,11 @@
 {"executescript", (PyCFunction)pysqlite_cursor_executescript, METH_VARARGS,
 PyDoc_STR("Executes a multiple SQL statements at once. Non-standard.")},
 {"fetchone", (PyCFunction)pysqlite_cursor_fetchone, METH_NOARGS,
- PyDoc_STR("Fetches several rows from the resultset.")},
+ PyDoc_STR("Fetches one row from the resultset.")},
 {"fetchmany", (PyCFunction)pysqlite_cursor_fetchmany, METH_VARARGS,
- PyDoc_STR("Fetches all rows from the resultset.")},
+ PyDoc_STR("Fetches several rows from the resultset.")},
 {"fetchall", (PyCFunction)pysqlite_cursor_fetchall, METH_NOARGS,
- PyDoc_STR("Fetches one row from the resultset.")},
+ PyDoc_STR("Fetches all rows from the resultset.")},
 {"close", (PyCFunction)pysqlite_cursor_close, METH_NOARGS,
 PyDoc_STR("Closes the cursor.")},
 {"setinputsizes", (PyCFunction)pysqlite_noop, METH_VARARGS,
