[DB-SIG] Controlling return types for DB APIs

[Carsten Haese]

On Wed, 2007-05-09 at 08:27 -0400, Jim Patterson wrote:
> [excellent points about database dependence and database
independence...]

I agree with everything you say, and my ultimate goal, unspoken until
now, is that the community will develop and agree on a set of mandatory
standard output maps that the application developers can rely on to
write database-independent code for the common use cases of decimal
formats, character formats, and date formats.

As you said, each database is different at the low level. Therefore, any
adapter function will usually be implemented in a database-specific way.
My proposal attempts to lay the necessary foundation for a generic
framework in which to specify adapter functions. If we agree that the
foundation is solid, we can then build output maps with standardized
names on top of this foundation. Under the hood, each API implementation
will use database-specific features, but the database-dependence will be
abstracted away from the application developer by using common map names
for common use cases.

In my opinion, consensus should be formed in two steps. First, we'd
agree that the foundation is solid and that we need mandatory maps for
common use cases based on that foundation. Then, in a separate
discussion, we'd negotiate what those mandatory maps should be and what
they're called. This way, we'll solve the two seemingly mutually
exclusive problems of allowing type mapping for common cases without
restricting usability for database-specific use cases. 

To name a concrete example, suppose we agree that the developer should
be able to choose between having decimals returned as floats, as
strings, or as Decimal instances. We could mandate that the DB-API
module provide output maps called, for example, DecimalAsFloat,
DecimalAsString, and DecimalAsDecimal.

Each of those would be a dictionary-like object that maps the
database-specific type description for "decimal" to a database-specific
adapter function that will accept the canonical database-specific
representation of a decimal value and return the corresponding
database-agnostic application object.

All this database-specific stuff is neatly hidden from the application
programmers. All they need to do is something like this

import somedb
conn = somedb.connect(...)
conn.outputmap = somedb.DecimalAsFloat

and they'll get all decimals returned as floats regardless of what kind
of database engine they're connected to.

I said the standard maps should be dictionary-like because I think we
should allow the application developer to combine standard maps by
adding them together, which ordinary dictionaries won't do. That way,
the developer will be able to write something like

conn.outputmap = somedb.DecimalAsFloat + somedb.CharAsUnicode

to combine two standard maps in a rather natural way.

I hope this makes sense,

-- 
Carsten Haese
http://informixdb.sourceforge.net