[3.10] gh-89018: Improve documentation of `sqlite3` exceptions (GH-27645) (#93838)
- Order exceptions as in PEP 249
- Reword descriptions, so they match the current behaviour
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>.
(cherry picked from commit bb0b7689465c3aac3b1d7f68c8990009462c1ae5)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index a430144..f1d0426 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -681,7 +681,7 @@
:ref:`placeholders <sqlite3-placeholders>`.
:meth:`execute` will only execute a single SQL statement. If you try to execute
- more than one statement with it, it will raise a :exc:`.Warning`. Use
+ more than one statement with it, it will raise a :exc:`Warning`. Use
:meth:`executescript` if you want to execute multiple SQL statements with one
call.
@@ -883,43 +883,74 @@
Exceptions
----------
+The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`).
+
.. exception:: Warning
- A subclass of :exc:`Exception`.
+ This exception is raised by ``sqlite3`` if an SQL query is not a
+ :class:`string <str>`, or if multiple statements are passed to
+ :meth:`~Cursor.execute` or :meth:`~Cursor.executemany`.
+ ``Warning`` is a subclass of :exc:`Exception`.
.. exception:: Error
- The base class of the other exceptions in this module. It is a subclass
- of :exc:`Exception`.
+ The base class of the other exceptions in this module.
+ Use this to catch all errors with one single :keyword:`except` statement.
+ ``Error`` is a subclass of :exc:`Exception`.
+
+.. exception:: InterfaceError
+
+ This exception is raised by ``sqlite3`` for fetch across rollback,
+ or if ``sqlite3`` is unable to bind parameters.
+ ``InterfaceError`` is a subclass of :exc:`Error`.
.. exception:: DatabaseError
Exception raised for errors that are related to the database.
+ This serves as the base exception for several types of database errors.
+ It is only raised implicitly through the specialised subclasses.
+ ``DatabaseError`` is a subclass of :exc:`Error`.
+
+.. exception:: DataError
+
+ Exception raised for errors caused by problems with the processed data,
+ like numeric values out of range, and strings which are too long.
+ ``DataError`` is a subclass of :exc:`DatabaseError`.
+
+.. exception:: OperationalError
+
+ Exception raised for errors that are related to the database's operation,
+ and not necessarily under the control of the programmer.
+ For example, the database path is not found,
+ or a transaction could not be processed.
+ ``OperationalError`` is a subclass of :exc:`DatabaseError`.
.. exception:: IntegrityError
Exception raised when the relational integrity of the database is affected,
e.g. a foreign key check fails. It is a subclass of :exc:`DatabaseError`.
+.. exception:: InternalError
+
+ Exception raised when SQLite encounters an internal error.
+ If this is raised, it may indicate that there is a problem with the runtime
+ SQLite library.
+ ``InternalError`` is a subclass of :exc:`DatabaseError`.
+
.. exception:: ProgrammingError
- Exception raised for programming errors, e.g. table not found or already
- exists, syntax error in the SQL statement, wrong number of parameters
- specified, etc. It is a subclass of :exc:`DatabaseError`.
-
-.. exception:: OperationalError
-
- Exception raised for errors that are related to the database's operation
- and not necessarily under the control of the programmer, e.g. an unexpected
- disconnect occurs, the data source name is not found, a transaction could
- not be processed, etc. It is a subclass of :exc:`DatabaseError`.
+ Exception raised for ``sqlite3`` API programming errors,
+ for example trying to operate on a closed :class:`Connection`,
+ or trying to execute non-DML statements with :meth:`~Cursor.executemany`.
+ ``ProgrammingError`` is a subclass of :exc:`DatabaseError`.
.. exception:: NotSupportedError
- Exception raised in case a method or database API was used which is not
- supported by the database, e.g. calling the :meth:`~Connection.rollback`
- method on a connection that does not support transaction or has
- transactions turned off. It is a subclass of :exc:`DatabaseError`.
+ Exception raised in case a method or database API is not supported by the
+ underlying SQLite library. For example, setting *deterministic* to
+ :const:`True` in :meth:`~Connection.create_function`, if the underlying SQLite library
+ does not support deterministic functions.
+ ``NotSupportedError`` is a subclass of :exc:`DatabaseError`.
.. _sqlite3-types:
