gh-89022: Improve sqlite3 exceptions related to binding params and API misuse

[erlend-aasland]

• Map SQLITE_MISUSE to InterfaceError instead of ProgrammingError
• Raise more accurate exceptions when binding parameters fail

Fixes gh-89022

[erlend-aasland]

See also https://sqlite.org/rescode.html#misuse:

If SQLite ever returns SQLITE_MISUSE from any interface, that means that the application is incorrectly coded and needs to be fixed. Do not ship an application that sometimes returns SQLITE_MISUSE from a standard SQLite interface because that application contains potentially serious bugs.

[erlend-aasland]

Example of snippets with improved messages; this PR compared to latest official 3.11 release.

Limiting the length of string literals:

import sqlite3
cx = sqlite3.connect(":memory:")
cx.set_trace_callback(print)
cx.setlimit(sqlite3.SQLITE_LIMIT_LENGTH, 7)
cx.execute("select ?", ("a"*10,))

$ python3.11 lim.py 
Traceback (most recent call last):
  File "/Users/erlendaasland/src/cpython-build/lim.py", line 5, in <module>
    cx.execute("select ?", ("a"*10,))
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
sqlite3.InterfaceError: Error binding parameter 0 - probably unsupported type.
$ ./python.exe lim.py 
Traceback (most recent call last):
  File "/Users/erlendaasland/src/cpython-build/lim.py", line 5, in <module>
    cx.execute("select ?", ("a"*10,))
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
sqlite3.DataError: string or blob too big

Trying to bind to an unsupported type (note, SQLite parameters are 1-indexed, not 0-indexed):

import sqlite3
cx = sqlite3.connect(":memory:")
val = dict()
cx.execute("select ?", (val,))

$ python3.11 type.py 
Traceback (most recent call last):
  File "/Users/erlendaasland/src/cpython-build/type.py", line 4, in <module>
    cx.execute("select ?", (val,))
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
sqlite3.InterfaceError: Error binding parameter 0 - probably unsupported type.
$ ./python.exe type.py 
Traceback (most recent call last):
  File "/Users/erlendaasland/src/cpython-build/type.py", line 4, in <module>
    cx.execute("select ?", (val,))
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
sqlite3.ProgrammingError: Error binding parameter 1: type 'dict' in not supported

[JelleZijlstra]

This makes sense to me when comparing with https://peps.python.org/pep-0249/#exceptions

[malemburg]

Hi Erlend, the explicit exception changes look fine to me, since anything that a programmer using the module can potentially do wrong in terms of e.g. passing wrong number of parameters, using binding parameters where they are not allowed, etc. should result in a ProgrammingError.

I'm not sure about the SQLITE_MISUSE, though, since the SQLite docs are rather unspecific on what exactly can cause such an error. The one example they give (using a prepared statement after that prepared statement has been finalized) does point to an error which originates in the API itself rather than an error caused by the programmer using the API, so InterfaceError sounds correct.

In mxODBC, I use InterfaceError for e.g. using invalid attribute values passed to an ODBC API, or invalid lengths, options, invalid cursor state, etc. I.e. things where mxODBC itself would be doing something wrong, not necessarily the programmer. Sometimes the distinction is not a very clear one, though, so I wouldn't call the mapping I'm using the only correct one.

[malemburg]

LGTM, modulo the comments I made on the PR.

[malemburg]

LGTM, modulo the comments I made on the PR.

Strange, I clicked on the "Add your review" button and approved the changes, but the bar at the top of the PR still says that Github is waiting for a review.

[erlend-aasland]

I'm not sure about the SQLITE_MISUSE, though, since the SQLite docs are rather unspecific on what exactly can cause such an error. The one example they give (using a prepared statement after that prepared statement has been finalized) does point to an error which originates in the API itself rather than an error caused by the programmer using the API, so InterfaceError sounds correct.

Yes, the example you point to is definitely an InterfaceError. Also note this sentence, quoted from the SQLITE_MISUSE docs:

If SQLite ever returns SQLITE_MISUSE from any interface, that means that the application is incorrectly coded and needs to be fixed. Do not ship an application that sometimes returns SQLITE_MISUSE from a standard SQLite interface because that application contains potentially serious bugs.

I think this justifies mapping SQLITE_MISUSE to InterfaceError.

In mxODBC, I use InterfaceError for e.g. using invalid attribute values passed to an ODBC API, or invalid lengths, options, invalid cursor state, etc. I.e. things where mxODBC itself would be doing something wrong, not necessarily the programmer.

Exactly; this is also my understanding of InterfaceError.

Thanks for reviewing, and thanks for your input; highly appreciated.

[erlend-aasland]

Strange, I clicked on the "Add your review" button and approved the changes, but the bar at the top of the PR still says that Github is waiting for a review.

Looks like GitHub forked you! :)

[erlend-aasland]

FYI, I've resolved the conflicting files, so this is ready to land when the CI finishes.

[JelleZijlstra]

Windows x64 was stuck, I restarted it.