[DB-SIG] Optional DB API Extensions
Tue, 23 Oct 2001 17:04:36 +0200
Here's some food for thought...
Title: Optional Database API Extensions
Version: $Revision: 1.0 $
Author: email@example.com (Marc-Andre=82 Lemburg)
Type: Standards Track
This pre-PEP should provide a discussion basis for an "Optional
Extensions" section in the DB API 2.0 standard PEP 249.
Feel free to add/change text as required.
Even though the DB API 2.0 standard already provides a multitude
of APIs, there are some common situations where a database package
writer will want to add features which are specific to the
database, but which could also be implemented for other databases
This pre-PEP will collect these common extensions for subsequent
inclusion in the DB API 2.0 standard. Note that all extensions
will be marked "optional", meaning that database writers are free
to implement them, but are not required to do so in order to have
a DB API 2.0 compatible package.
Proposed Common Extensions
Cursor Attribute .rownumber
This read-only attribute should provide the current 0-based
index of the cursor in the result set or -1 if the index cannot
The index can be seen as index of the cursor in a sequence (the
result set). The next fetch operation will fetch the row
indexed by .rownumber.
Connection Attributes .Error, .ProgrammingError, etc.
All exception classes defined by the DB API standard should be
exposed on the Connection objects are attributes (in addition
to being available at module scope).
These attributes simplify error handling in multi-connection
Cursor Attributes .connection
This read-only attribute return a reference to the Connection
object on which the cursor was created.
The attribute simplifies writing polymorph code in
Cursor Method .scroll(value[,mode=3D'relative'])
Scroll the cursor in the result set to a new position according
If mode is 'relative' (default), value is taken as offset to
the current position in the result set, if set to 'absolute',
value states an absolute target position.
An IndexError should be raised in case a scroll operation would
leave the result set. In this case, the cursor position is left
undefined (ideal would be to not move the cursor at all).
Note: This method should use native scrollable cursors, if
available , or revert to an emulation for forward-only
scrollable cursors. The method may raise NotSupportedErrors to
signal that a specific operation is not supported by the
database (e.g. backward scrolling).
Cursor Attribute .messages
This is a Python list object to which the interface appends
tuples (exception class, exception value) for all messages
which the interfaces receives from the underlying database for
The list is cleared by all standard cursor methods calls (prior
to executing the call) except for the .fetchXXX() calls
automatically to avoid excessive memory usage and can also be
cleared by executing "del cursor.messages[:]".
All error and warning messages generated by the database are
placed into this list, so checking the list allows the user to
verify correct operation of the method calls.
The aim of this attribute is to eliminate the need for a
Warning exception which often causes problems (some warnings
really only have informational character).
Connection Attribute .messages
Same as cursor.messages except that the messages in the list
are connection oriented.
The list is cleared automatically by all standard connection
methods calls (prior to executing the call) to avoid excessive
memory usage and can also be cleared by executing "del
This PEP only affects database modules/packages which adhere to
the Python DB API 2.0 standard. Some of these extensions may
become manditory features in future DB API standard versions.
This document has been placed in the public domain.
CEO eGenix.com Software GmbH
Consulting & Company: http://www.egenix.com/
Python Software: http://www.lemburg.com/python/