Created on 2009-05-18 19:02 by MLModel, last changed 2013-01-30 02:44 by MLModel.
|msg88044 - (view)||Author: Mitchell Model (MLModel)||Date: 2009-05-18 19:02|
I can't find any documentation of the exception classes defined in the sqlite3 module. There are quite a few, and some inheritance. The examples in the sqlite3 module documentation have a few exception clauses, but the errors they catch are not explained. I would expect every module that defines exception classes to document them, including inheritance. For a module like sqlite3 it is particularly important because it is just an interface to C code. Expecting someone to figure out exception classes from a module's Python code is one thing, but asking them to go into the C code, which they might not even have, is another.
|msg88140 - (view)||Author: Gerhard Häring (ghaering) *||Date: 2009-05-20 22:30|
At the very start of the module's documentation it reads: """ pysqlite was written by Gerhard Häring and provides a SQL interface compliant with the DB-API 2.0 specification described by PEP 249. """ Where "PEP 249" is a link to the Database API 2.0 specification, which does document the xception classes and their hierarchy.
|msg88177 - (view)||Author: Mitchell Model (MLModel)||Date: 2009-05-22 03:12|
Thanks for the informatiion about the exception classes documented in the PEP. I didn't mean to suggest that the information wasn't available. (For that matter, I was able to extract it for my purposes by looking at the .c source.) I've been writing a book on "Bioinformatics Programming Using Python" for O'Reilly and working my way through the documentation for the many modules I describe in detail paying far more attention to accuracy, completeness, etc. than would normally concern me. In the process I have submitted many observations about inaccuracies, inconsistencies, gaps, etc. in the library documentation. In effect I am doing a "review" and picking up problems in a module documentation that could easily go unnoticed by anyone familiar with the modules. A small portion have involved incomplete transitions from Python 2 to Python 3. (My book uses 3; anyone involved in module documentation should take my comments as QA observations about Python 3 documentation and decide what, if anything, to do about them.) My concern is for non-developer Python programmers who expect module documentation to be self-contained except, perhaps, where there are pointers to major outside resources (for instance, sqlite.org documentation). I don't think we can ask or expect "normal" Python programmers to know what a PEP is, how to access it, what relationship a PEP has to the module as implemented, etc. True, for the particular case of the DB API interface the PEP document is more important than most becuase it defines an interface that other modules implement. In this case, perhaps the best approach would be to document the DB-API as part of the ordinary Python library documentation, then have sqlite3 be a subtopic of that. However it's done I think user's should be able to read the standard documentation and find what they need. An incidental reason is that people sometimes work offline and don't have access to the PEPs though they do have access to the installed documentation. All those arguments aside, perhaps what makes the most sense is to simply add the error hierarchy following "This is the exception inheritance layout:" to the sqlite documentation, while still referring the reader to the PEP. I am just really wary of having PEPs serve as documentation for ordinary Python programmers. Even many PEPs that have been accepted and implemented have more interest as background and explanation than practical documentation, snce the documentation of their contribution to the language and the library has been integrated into the regular documentation.
|msg180963 - (view)||Author: Mitchell Model (MLModel)||Date: 2013-01-30 02:44|
I still think the Exception class hierarchy should be described in the sqlite3 module documentation. Someone should decide one way or another and close this issue.
|2013-01-30 02:44:59||MLModel||set||messages: + msg180963|
|2011-10-29 02:07:27||flox||set||stage: needs patch|
versions: + Python 3.3, - Python 3.1
versions: - Python 2.6, Python 3.0
assignee: ghaering ->
keywords: + easy
|2009-05-22 03:12:21||MLModel||set||messages: + msg88177|
|2009-05-20 22:30:08||ghaering||set||priority: low|
messages: + msg88140
|2009-05-20 18:32:54||georg.brandl||set||assignee: georg.brandl -> ghaering|
nosy: + ghaering