Mitchell Model <m...@acm.org> added the comment:

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 decid
 e 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.

----------

_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue6057>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

Reply via email to