[DB-SIG] Optional DB API Extensions

[M.-A. Lemburg]

Here's some food for thought...

PEP: ???
Title: Optional Database API Extensions
Version: $Revision: 1.0 $
Author: mal@lemburg.com (Marc-Andre=82 Lemburg)
Status: Draft
Type: Standards Track
Python-Version: 2.3
Created: 23-Oct-2001
Post-History:=20

Abstract

    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.

Problem

    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
    as well.

    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
       be determined.

       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
       environments.

    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
       multi-connection environments.

    Cursor Method .scroll(value[,mode=3D'relative'])

       Scroll the cursor in the result set to a new position according
       to mode.
      =20
       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
       this cursor.

       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
       connection.messages[:]".

Scope

    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.

Copyright

    This document has been placed in the public domain.

=0C
Local Variables:
mode: indented-text
indent-tabs-mode: nil
End:

--=20
Marc-Andre Lemburg
CEO eGenix.com Software GmbH
______________________________________________________________________
Consulting & Company:                           http://www.egenix.com/
Python Software:                        http://www.lemburg.com/python/