[DB-SIG] UML diagram of Python DB API 2.0 specification

[Travis Spencer]

Hello All,

My research group is using two Python DB API-compliant modules to
interface with a couple backend database servers.  Last term, I was
asked to do some work on this aspect of our project for the first
time.  I didn't know anything about database programming in Python, so
one of my colleagues pointed me to the Python DB API specification[1].
 She said that studying it would show me how to work with each of the
two modules since both conformed to the same interface.  It was very
useful indeed!  However, as I read it and reread it and re-reread it,
I found myself reaching for some succinct overview that summarized the
entire API -- something that I could easily and frequently refer back
to when I needed to look up from the details and take in the entire
specification.

Not finding such a resource, I created a UML diagram that illustrates
the specification's API in a broad sense.  It shows the mandated
classes, each one's fields and operations, and how they all fit
together into one package.

Specifically, the diagram shows the four top-level classes and the
module-level functions.  It depicts how the the top-level Error class
is the root of an inheritance hierarchy containing the seven specified
descendants.  The relationship that these classes have to the
Connection class's optional Error field is illustrated with a UML
associate (an arrow).  Uninterestingly but necessary, the Warning
class is also shown.  And then comes the good stuff: the Connection
and Cursor classes.

With one glance, you can learn all sorts of information about the
Connection class.  For instance, you can immediately see that it could
have as few as three attributes: the close, commit, and cursor
methods; the other attributes are optional.  All the information that
you can glean from the diagram is present in the specification of
course, but this alternative presentation format makes some things
easier to see.  For instance, the errorhandlers field is way at the
end of the specification where it can be easily overlooked; however,
this diagram pulls it to the forefront.

Likewise, the Cursor class's optional and required attributes can be
seen very obviously.  This clarity reveals many methods and fields
such as __iter__, lastrowid, and messages that otherwise require a
couple of readings before they are first noticed.

Lastly, the diagram shows the package-level attributes that are
defined by the standard.  The scope of these is illustrated by their
position in a UML utility stereotype called global.

I would like to share this resource with everyone in hopes that it
will help others get the big picture of what exactly the Python DB API
is setting forth.  For this reason, I'm freely releasing my UML
diagram's original source document (a Microsoft Visio file) and
various other formats that I've produced from it.  I am licencing all
of these under the GNU Free Documentation License (GFDL), so you can
use them in any way that complies with that license.  I'm willing to
relicense it under the same one that the Python documentation is
governed by if need be.

You will find the UML diagram in the following formats at each respective URL:

Microsoft Visio Drawing Format (VSD)
http://www.travisspencer.com/stash2/projects/perftrack/umldiagram/dbapi2.vsd

PDF
http://www.travisspencer.com/stash2/projects/perftrack/umldiagram/dbapi2.pdf

TIFF
http://www.travisspencer.com/stash2/projects/perftrack/umldiagram/dbapi2.tif

LZW Compressed TIFF
http://www.travisspencer.com/stash2/projects/perftrack/umldiagram/dbapi2.Z.tif

EPS
http://www.travisspencer.com/stash2/projects/perftrack/umldiagram/dbapi2.eps

GIF
http://www.travisspencer.com/stash2/projects/perftrack/umldiagram/dbapi2.gif

PNG
http://www.travisspencer.com/stash2/projects/perftrack/umldiagram/dbapi2.png

JPEG
http://www.travisspencer.com/stash2/projects/perftrack/umldiagram/dbapi2.jpg

Microsoft Visio XML Drawing (VDX)
http://www.travisspencer.com/stash2/projects/perftrack/umldiagram/dbapi2.vdx

I hope this diagram helps others get oriented as they learn more about
the Python Database API, build new compliant drivers, or use existing
ones.

If you have any comments or questions, please feel free to share them
(here on the list or privately via email).  I am happy to help if I
can and always appreciative of any constructive criticisms.

--

Regards,

Travis Spencer

[1] http://www.python.org/peps/pep-0249.html