[DB-SIG] PEP249 - Proposed change to DB-API 2.0

[Chris Cogdon]

[This is all IMHO, of course :)]

The Problem
-----------

One of the main purposes of the DB-API was to set a 'standard' for API
writiers to write to, so that users of the API could switch from one
database to another without rewriting large chunks of their code.

However, DB-API 2.0 currently encourages non-consistant behaviour through
the 'vague' requirements in the 'paramstyle' module-level variable. Ie, we
do not place any requirements on which paramstyle should be coded for,
only that the paramstyle chosen needs to be specified in that variable.

This means that if I'm currently using database BAR, who's Python API uses
paramstyle='format', and I switch to database BAZ who's Python API uses
paramstyle='pyformat', then I have to rewrite huge chunks of my code.

Alternatively, I could simply write a 'wrapper' around the existing api,
which converts paramstyles from what my original code used, to what the
new API expects. Yes, that'll work just fine, but... isn't that what the
API is supposed to be doing for me?

The Proposal
------------

The API be changed (2.1?) to include the following.

There is a module-level variable, valid_paramstyles, that containsthe list
of all paramstyles the API code can support.

There is a new method on the connection object, set_paramstyle, that
indicates which paramstyle the calling code is going to use. If the
calling code sets a paramstyle that is not supported, an exception is
raised. The default paramstyle is that specified in the existing
'paramstyle' variable. It is not modified by calls to
object.set_paramstyle.

There is a new module function, also called set_paramstyle, that sets the
'default' paramstyle that is used when connection objects are created. In
this case, the module.paramstyle IS modified. (Alternately, we could let
code change the variable module.paramstyle directly. Connection objects
would throw an exception if the default is not supported.)


The Benifit
-----------

I can write my database application using a single paramstyle (my
favourite is 'format'). All I then need to do is call set_paramstyle to
tell the DB-API to use the paramstyle I want.

DB-API writers would by default support the paramstyle easiest for the
database C interface. (assuming easy = most-efficient), and then call a
limited number of conversion functions for supporting other methods.

I perceive the DB-API module change to be made in a /single/ location,
whereas changing paramstyles in a database application would need to be
done all over the place, or a wrapper written.


Backward Combatibility
----------------------

The change above I perceive as being totally backward compatible. Existing
code that changes its own calling habits based on 'paramstyle' will still
work as expected.



Comments, anyone?


   ("`-/")_.-'"``-._        Chris Cogdon <chris@cogdon.org>
    . . `; -._    )-;-,_`)
   (v_,)'  _  )`-.\  ``-'
  _.- _..-_/ / ((.'
((,.-'   ((,/   fL