This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: sqlite3 error classes should be documented
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: berker.peksag Nosy List: MLModel, PyDeq, abarry, berker.peksag, flox, georg.brandl, ghaering, jaysinh.shukla, matrixise, python-dev, timm
Priority: normal Keywords: easy, patch

Created on 2009-05-18 19:02 by MLModel, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
issue6057_python3_6.diff jaysinh.shukla, 2016-06-16 13:24 review
issue6057_python3_6_v2.diff jaysinh.shukla, 2016-06-16 14:12 review
issue6057-3.6.diff matrixise, 2016-08-08 06:35 review
issue6057-3.6-2.diff matrixise, 2016-08-10 17:13 review
Messages (18)
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) * (Python committer) 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.
msg194457 - (view) Author: Tim Martin (timm) Date: 2013-08-05 07:34
I would find it useful to have the exception classes listed in the Python documentation rather than having to refer to two documents, but I don't have strong feelings on this.

Given that nobody has fixed this for 4 years, should we just close the ticket? I'd be happy to do the necessary work if this is something we want changed, but I don't want to prepare a patch for a ticket that's never going to go anywhere.
msg242925 - (view) Author: Radek Holý (PyDeq) Date: 2015-05-11 23:30
One reason why I would like to have it mentioned in the documentation is that the fact that it is not documented there causes "sqlite3.Error" to be missing in the "objects.inv" file generated by Sphinx so that enabling the "nitpicky" mode with "intersphinx" extension when generating my documentation using Sphinx results in many "WARNING: py:exc reference target not found: sqlite3.Error" false positives.

(I'd also like to have it backported to Python 2.6 but I know that it's impossible)
msg268358 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-12 10:25
Here is a list of exceptions that need to be documented: IntegrityError, Warning, Error, ProgrammingError and DatabaseError.
msg268667 - (view) Author: Jaysinh shukla (jaysinh.shukla) * Date: 2016-06-16 13:24
Submitting the patch for Python 3.6.
msg268670 - (view) Author: Jaysinh shukla (jaysinh.shukla) * Date: 2016-06-16 14:12
Adding forgotten reference of ProgrammingError to last patch. Please review issue6057_python3_6_v2.diff
Thanks!
msg272146 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2016-08-08 06:28
Hi Jaysinh,

I have reviewed your patch, but for me, this one should be have an order for the exception.

* Warning
* Error
  * DatabaseError
    * ProgrammingError
    * IntegrityError 

Thank you
msg272147 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2016-08-08 06:35
Here is the patch with my comments.
msg272339 - (view) Author: Jaysinh shukla (jaysinh.shukla) * Date: 2016-08-10 15:35
Dear Stéphane,
    I will be agreed with the way proposed by you.
msg272343 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-08-10 16:59
Thanks for the patch!

+.. exception:: DatabaseError
+
+    Exception raised for errors that are related to the database.  It

Indentation is not in line with other items:

    +.. exception:: DatabaseError
    +
    +   Exception [...]

In Cursor.execute() documentation, ``sqlite3.Warning`` needs to be replaced with :exc:`sqlite3.Warning`.

Also, in Cursor.close() documentation, ``ProgrammingError`` needs to be replaced with :exc:`sqlite3.ProgrammingError`.
msg272344 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2016-08-10 17:13
Fixed with your comments.
msg273598 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-08-24 21:44
New changeset 1dbd1a9a6a9c by Berker Peksag in branch '3.5':
Issue #6057: Document exceptions in sqlite3 module
https://hg.python.org/cpython/rev/1dbd1a9a6a9c

New changeset 6f8042107d76 by Berker Peksag in branch 'default':
Issue #6057: Merge from 3.5
https://hg.python.org/cpython/rev/6f8042107d76
msg273599 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-08-24 21:45
Thanks for the patch, Jaysinh and Stéphane! :)
msg273600 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-08-24 21:49
Typo: "an Warning" ;)
msg273601 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-08-24 21:50
Already fixed in 78c039440d6b, thanks!
History
Date User Action Args
2022-04-11 14:56:49adminsetgithub: 50307
2016-08-24 21:50:40berker.peksagsetstatus: open -> closed

messages: + msg273601
2016-08-24 21:49:25abarrysetstatus: closed -> open
nosy: + abarry
messages: + msg273600

2016-08-24 21:45:31berker.peksagsetstatus: open -> closed
resolution: fixed
messages: + msg273599

stage: patch review -> resolved
2016-08-24 21:44:32python-devsetnosy: + python-dev
messages: + msg273598
2016-08-24 21:27:55berker.peksagsetstage: commit review -> patch review
2016-08-10 17:49:18matrixisesetstage: patch review -> commit review
2016-08-10 17:14:55matrixisesetassignee: berker.peksag
2016-08-10 17:13:22matrixisesetfiles: + issue6057-3.6-2.diff

messages: + msg272344
2016-08-10 16:59:35berker.peksagsetmessages: + msg272343
stage: commit review -> patch review
2016-08-10 16:03:30matrixisesetstage: patch review -> commit review
2016-08-10 15:35:41jaysinh.shuklasetmessages: + msg272339
2016-08-08 06:35:58matrixisesetfiles: + issue6057-3.6.diff

messages: + msg272147
2016-08-08 06:28:22matrixisesetstage: needs patch -> patch review
2016-08-08 06:28:10matrixisesetnosy: + matrixise
messages: + msg272146
2016-06-16 14:12:34jaysinh.shuklasetfiles: + issue6057_python3_6_v2.diff

messages: + msg268670
2016-06-16 13:24:56jaysinh.shuklasetfiles: + issue6057_python3_6.diff
keywords: + patch
messages: + msg268667
2016-06-16 07:45:54jaysinh.shuklasetnosy: + jaysinh.shukla
2016-06-12 10:25:49berker.peksagsetpriority: low -> normal
versions: + Python 3.5, Python 3.6, - Python 3.2, Python 3.3
nosy: + berker.peksag

messages: + msg268358

type: behavior -> enhancement
2015-05-11 23:30:27PyDeqsetnosy: + PyDeq
messages: + msg242925
2013-08-05 07:34:21timmsetnosy: + timm
messages: + msg194457
2013-01-30 02:44:59MLModelsetmessages: + msg180963
2011-10-29 02:07:27floxsetstage: needs patch
versions: + Python 3.3, - Python 3.1
2010-07-09 08:52:14floxsetnosy: + flox
versions: - Python 2.6, Python 3.0
assignee: ghaering -> (no value)
keywords: + easy
type: behavior
2009-05-22 03:12:21MLModelsetmessages: + msg88177
2009-05-20 22:30:08ghaeringsetpriority: low

messages: + msg88140
2009-05-20 18:32:54georg.brandlsetassignee: georg.brandl -> ghaering

nosy: + ghaering
2009-05-18 19:02:24MLModelcreate