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 _______________________________________________ DB-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/db-sig
