[DB-SIG] annotated 1.1 spec / feedback

Greg Stein gstein@lyra.org
Thu, 04 Mar 1999 02:40:14 -0800


I've prepared an annotated 1.1 spec (it lists changes since 1.0). It is
located at:

  http://www.lyra.org/greg/anno-DatabaseAPI-1.1.html

Please let me know if I've missed any changes. I'll update the page to
follow Marc-Andre's releases of the API spec. Just watch for the version
string at the top to see if I've updated yet.


While annotating, I've also prepared some feedback items:

* Connect() should be lower-cased to connect(). Most Python module-level
functions are all lower case; we should follow suit.

* the connect() parameters should be called "examples" rather than
"usually". I've seen a db module or two where they try to follow suit
and munge together parameters into a string, simply to have to tear it
apart. We should not try to avoid imposing on the connection parameters.
For example: MySQL should take four params: host, user, password,
database. "dsn" is not "typical" for it, so we should confuse people
into attempting to abide by it.

* the parameters should be positional, rather than keyword-based.
keywords can be optional, but we should not require the params to be
keyword-based.

* I think the exception should only be available thru dbi. Having them
in two places may lead to using different classes, thus breaking the
inheritance/catching of the exceptions. I understand that the module
implementor can get the other class object and expose it as a value, but
there'd be hard-to-find problems if they skipped that step.

* maybe we should discuss punting dbi. module distribution may be easier
without it. While it is handy for clients that use more than one DB
module, I can easily envision a python module that exports the
appropriate set for the DB being used.

* cursor.rowcount is new, and is extraneous. The result of execute()
should be used.

* the params to callproc should be: callproc(procname [, params]).

* I think we should clean up the description attribute if possible. The
7-tuple is/was very Oracle-specific.

* The old description for execute() returning None was clearer. Note
that a SELECT can return no columns/rows (where your description says >
0).

* For the >=0 return value from execute(), it should be clarified with
the word "affect" since you could delete them or insert them (which are
not "touching" rows).

* in general, I think the 1.1 change to the return value description
didn't really clear things up. Basing the descriptions on returning
columns/rows doesn't make much sense to me. Instead, I liked the
description based on the *type* of statement that was performed. Under
this style, a SELECT that doesn't produce columns/rows would return 1,
but that is just wrong.

* execute()'s description should change back to the terms "sequence" and
"sequence of sequences" for the parameters. There is no reason to force
them to be tuples or lists.

* the part about cursor movement in fetchone() should be totally
removed. fetchone() is about the CLIENT fetching a single row. It should
NOT affect how the underlying module performs its fetches.

* the fetch* methods should say they return a sequence or a sequence of
sequences. We should not force them to be tuples or lists of tuples.
Some DB modules may want to have additional semantics or capabilities on
their results. As long as it obeys sequence behavior, then the spec
should be happy. The arraysize attribute's description also refers to a
list of tuples, and should be updated.

* dbiDate values probably shouldn't *contain* mxDateTime values.
Instead, mxDateTime should be used in place of dbiDate. The point of
dbiDate was to provide a way to discriminate between an integer and a
date (unix ticks). mxDateTime can fill the same role.

* we may want to strike the "ending in db" comment. seems silly in
retrospec and (empirically) has not been followed anyhow.

Cheers,
-g

--
Greg Stein, http://www.lyra.org/