[DB-SIG] DB API 3.0 strawman

[Federico Di Gregorio]

hi,

i don't like all the complexity you added to the dbapi, so i will be a
little bit harsh in my comments. also, i think much of the stuff here
can safetly go into a wrapper module. so my advice is to don't call this
pep dbapi-3.0.

On 06 Aug 2001 02:19:09 +1000, Stuart Bishop wrote:

>     Module Interface (sql.py)

why are you calling this pep dbapi if it documents a different thing?

> 	rollback(savepoint=None)

what db support savepoints? if it is just one, lets treat this as a
db-specific extension, no need to pollute the simplicity of dbapi.

> 	quote(object)

nice. i'd put it at module level.
 
> 	execute(operation,[seq_of_parameters])

why to add a new fucntion just to avoid two method calls?

> 	capabilities

i'd like to see a list called `formats', listing all the supported
formats. almost all the drivers support more than one bound args format
and currently there is no why to support them.

> 	set_transaction_level(level)

i agree, but doing this right will be difficult. does we really want to
put such a burden on driver developers?

> 
> 	autocommit(flag)
> 
> 	    Do we want an autocommit method? It would need to default
> 	    to false for backwards compatibility, and remembering
> 	    to turn autocommit on is as easy as explicitly calling
> 	    commit().

ok. (but autocommit is just a specific case of transaction level.)

> 	savepoint()
> 
> 	    Sets a savepoint in the current transaction, or throws a
> 	    NotSupportedError exception. Returns an object which may
> 	    be passed to the rollback method to rollback the transaction
> 	    to this point.

see above.

> 	next()
> 
> 	    Return the Row object for the next row from the currently
> 	    executing SQL statement. As per DB API 2.0 spec, except
> 	    a StopIteration exception is raised when the result set
> 	    is exhausted.

nice addition to dbapi.

> 
> 	__iter__()
> 
> 	    Returns self.

why?

> 
> 	nextset()
> 
> 	    I guess as per DB API 2.0 spec.
> 
> 	warnings
> 
> 	    List of Warning exceptions generated so far by the currently
> 	    executing statement. This list is cleared automatically by the
> 	    execute and callproc methods.

this is good for me.

> 
> 	clear_warnings()
> 
> 	    Erase the list of warnings. Same as 'del cursor.warnings[:]'
> 	    Is this method required?

no. you can just do cursor.warnings = None

>     Row Object
> 
> 	When a Cursor is iterated over, it returns Row objects.
> 	dtuple.py (http://www.lyra.org/greg/python/) provides such an
> 	implementation already.
> 
> 	[index_or_key]
> 
> 	    Retrieve a field from the Row. If index_or_key is an integer,
> 	    the column of the field is referenced by number (with the first
> 	    column index 0). If index_or_key is a string, the column is
> 	    referenced by its lowercased name (lowercased to avoid problems
> 	    with the differing methods vendors use to capitalize their column
> 	    names).

i like this concept. this is really missing from the dbapi.

> 
>     Type Objects and Constructors
> 
> 	As per DB API 2.0 spec.
> 
> 	Do we need Date, Time and DateTime classes, or just DateTime?

i think that every dbapi compliant driver should provide Date and Time,
usually wrapping the mxDateTime objects.

> 
> 	Need to author the 'Date PEP'. It would be nice if there was a
> 	more intelligent standard Date class in the Python core that
> 	we could leverage. If we don't, people will start using the
> 	sql module for the more intelligent DateTime object it would
> 	need to provide even if they arn't using databases.
> 
>     ConnectionPool Object
> 
> 	A connection pool, to be documented.

better done at user-level (i say that *even* if psycopg supports
connection pools natively. for us war a design choice but should not be
forced on developers of drivers, imho.)

> 
> Rationale
> 
>     The module is called sql.py, to avoid any ambiguity with non-realational
>     or non-SQL compliant database interfaces. This also nicely limits
>     the scope of the project. Other suggestions are 'sqlutil' and 'rdbms',
>     since 'sql' may refer to the language itself.
> 
>     Previous versions of the DB API have been intentially kept lean to
>     make it simpler to develop and maintain drivers, as a richer feature
>     set could be implemented by a higher level wrapper and maintained in
>     a single place rather than in every API compliant driver. As this
>     revision provides a single place to maintain code, these features
>     can now be provided without placing a burden to the driver authors.

mmm... so why are you proposing this to be dbapi-3.0? imo, we should
separate work in 3 parts:

	1/ dbapi, always lean and easy to implement to have a large base of
	compliant drivers.

	2/ sql.py, based on dbapi, to provide richer functionality.

	3/ dbapi extensions (the document i am writing, sorry for being so
	late), that describes common dbapi extensions (usually features not
	provided by every db and so not pertinent to 1 or 2.)
 
>     Existing DB API 1.0 and 2.0 drivers can be used to power the backend
>     of this module. This means that there will be a full compliment of
>     drivers available from day 1 of this modules release without placing
>     a burden on driver developers and maintainers.

completely agreed.

> 	It was difficult to write code that connected to multiple
> 	database vendor's databases. Each seperate driver used defined
> 	its own heirarchy of exceptions that needed to be handled,
> 	their own datetime class and their own set of datatype constants.

but the hierarchy of exceptions is documented in the dbapi pep. lets fix
the drivers, first.
 
> 	Platform independant code could not be written simply,
> 	due to the differing paramater styles used by bind variables.
> 	This also caused problems with publishing example code and tutorials.

this is true, but i think it was a design decision to allow for
different format styles. anyway, a single format supported (using a
wrapper) by all drivers seems good to me.

> 	The API remained minimal, as any new features would need to
> 	be implemented by all driver maintainers. The DB-SIG felt
> 	most feature suggestions would be better implemented by higher
> 	level wrappers, such as that defined by this PEP.

i mostly agree with you so:

	1/ found a name for this pep (*not* dbapi, it isn't)
	2/ if everybody agree, start implement it.

ciao,
federico

-- 
Federico Di Gregorio
MIXAD LIVE Chief of Research & Technology              fog@mixadlive.com
Debian GNU/Linux Developer & Italian Press Contact        fog@debian.org
                             Best friends are often failed lovers. -- Me