From 1cee1d05edd4a0f8fdd7e704663eb6c8893ff161 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 6 Aug 2021 21:59:30 +0200 Subject: [PATCH 01/17] Document all sqlite3 exceptions - Copy exception descriptions from PEP 249 - Order exceptions as in PEP 249 --- Doc/library/sqlite3.rst | 42 ++++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 6399bed7ed52c6..05340683ddd68f 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -829,35 +829,55 @@ Exceptions .. exception:: Warning - A subclass of :exc:`Exception`. + Exception raised for important warnings like data truncations while + inserting, etc. It 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 error exceptions in this module. Use this to + catch all errors with one single except statement. :exc:`Error` is a + subclass of :exc:`Exception`. + +.. exception:: InterfaceError + + Exception raised for errors that are related to the database interface + rather than the database itself. It is a subclass of :exc:`Error`. .. exception:: DatabaseError - Exception raised for errors that are related to the database. + Exception raised for errors that are related to the database. It is a + subclass of :exc:`Error`. + +.. exception:: DataError + + Exception raised for errors that are due to problems with the processed data + like division by zero, numeric value out of range, 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:: 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 the database encounters an internal error, e.g. the + cursor is not valid anymore, the transaction is out of sync, etc. It 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:: NotSupportedError Exception raised in case a method or database API was used which is not From 0e6af97222ea0215b1429d679d1a04898dac2ec2 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 6 Aug 2021 22:18:46 +0200 Subject: [PATCH 02/17] Add markup for except keyword --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 05340683ddd68f..9f623583e69f5a 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -835,8 +835,8 @@ Exceptions .. exception:: Error The base class of the other error exceptions in this module. Use this to - catch all errors with one single except statement. :exc:`Error` is a - subclass of :exc:`Exception`. + catch all errors with one single :keyword:`except` statement. :exc:`Error` + is a subclass of :exc:`Exception`. .. exception:: InterfaceError From b3ae237bb4471e0b2b32cd612e9ef77840c2664c Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 7 Aug 2021 20:03:57 +0200 Subject: [PATCH 03/17] Address review: adjust DataError wording --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 9f623583e69f5a..70bdc5ffda73ed 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -851,8 +851,8 @@ Exceptions .. exception:: DataError Exception raised for errors that are due to problems with the processed data - like division by zero, numeric value out of range, etc. It is a subclass of - :exc:`DatabaseError`. + like numeric value out of range and too long strings, etc. It is a subclass + of :exc:`DatabaseError`. .. exception:: OperationalError From 86baecee7ddef8bdc2eecb578a2e04848d22bb32 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 12 Apr 2022 20:19:19 +0200 Subject: [PATCH 04/17] WIP --- Doc/library/sqlite3.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index eb016fd33d1582..89f221ca2cd4a2 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1006,10 +1006,11 @@ Now we plug :class:`Row` in:: Exceptions ---------- +The exception hierarchy is defined by DB-API 2.0. + .. exception:: Warning - Exception raised for important warnings like data truncations while - inserting, etc. It is a subclass of :exc:`Exception`. + This exception is not raised by :mod:`sqlite3`. .. exception:: Error @@ -1017,11 +1018,6 @@ Exceptions catch all errors with one single :keyword:`except` statement. :exc:`Error` is a subclass of :exc:`Exception`. -.. exception:: InterfaceError - - Exception raised for errors that are related to the database interface - rather than the database itself. It is a subclass of :exc:`Error`. - .. attribute:: sqlite_errorcode The numeric error code from the @@ -1036,6 +1032,11 @@ Exceptions .. versionadded:: 3.11 +.. exception:: InterfaceError + + Exception raised for errors that are related to the database interface + rather than the database itself. It is a subclass of :exc:`Error`. + .. exception:: DatabaseError Exception raised for errors that are related to the database. It is a From 7951b1c0a3d2636cf0fdbbc8ae1b4d541bc8e173 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 26 May 2022 00:29:05 +0200 Subject: [PATCH 05/17] Sync with main --- Doc/library/sqlite3.rst | 60 ++++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 25 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 4c5ece146197a1..1bfad9e83aeaa0 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1103,12 +1103,13 @@ The exception hierarchy is defined by DB-API 2.0. .. exception:: Warning This exception is not raised by :mod:`sqlite3`. + ``Warning`` is a subclass of :exc:`Exception`. .. exception:: Error - The base class of the other error exceptions in this module. Use this to - catch all errors with one single :keyword:`except` statement. :exc:`Error` - 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`. .. attribute:: sqlite_errorcode @@ -1126,50 +1127,59 @@ The exception hierarchy is defined by DB-API 2.0. .. exception:: InterfaceError - Exception raised for errors that are related to the database interface - rather than the database itself. It is a subclass of :exc:`Error`. + Exception raised for misuse of the low-level SQLite C API. + In other words, if this exception is raised, it is probably a bug in the + ``sqlite3`` module. + ``InterfaceError`` is a subclass of :exc:`Error`. .. exception:: DatabaseError - Exception raised for errors that are related to the database. It is a - subclass of :exc:`Error`. + Exception raised for errors that are related to the database. + This serves the base exception for several types of database errors. + It is only raised implicitly through the specialised variants. + ``DatabaseError`` is a subclass of :exc:`Error`. .. exception:: DataError - Exception raised for errors that are due to problems with the processed data - like numeric value out of range and too long strings, etc. It is a subclass - of :exc:`DatabaseError`. + Exception raised for errors caused by problems with the processed data, + like numeric value out of range, and too long strings. + ``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, 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 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`. + for example, a foreign key check fails. + ``IntegrityError`` is a subclass of :exc:`DatabaseError`. .. exception:: InternalError - Exception raised when the database encounters an internal error, e.g. the - cursor is not valid anymore, the transaction is out of sync, etc. It is a - subclass of :exc:`DatabaseError`. + 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 raised for ``sqlite3`` API programming errors. + for example syntax errors in SQL statements, and wrong number of bindings + supplied to a query. + ``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:`create_function`, if the underlying SQLite library + does not support deterministic functions. + ``NotSupportedError`` is a subclass of :exc:`DatabaseError`. .. _sqlite3-blob-objects: From 18d701e48f2e461574fcdf39ab24d1afb1004877 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Tue, 31 May 2022 13:45:41 +0200 Subject: [PATCH 06/17] Update Doc/library/sqlite3.rst Co-authored-by: Alex Waygood --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 1bfad9e83aeaa0..a7ced19a668b14 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1128,7 +1128,7 @@ The exception hierarchy is defined by DB-API 2.0. .. exception:: InterfaceError Exception raised for misuse of the low-level SQLite C API. - In other words, if this exception is raised, it is probably a bug in the + In other words, if this exception is raised, it probably indicates a bug in the ``sqlite3`` module. ``InterfaceError`` is a subclass of :exc:`Error`. From 7a12a7b0a6303551e6fbb06a5c00bd1b4709e8d6 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Tue, 31 May 2022 13:45:51 +0200 Subject: [PATCH 07/17] Update Doc/library/sqlite3.rst Co-authored-by: Alex Waygood --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index a7ced19a668b14..5eba5d40bcc24c 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1135,7 +1135,7 @@ The exception hierarchy is defined by DB-API 2.0. .. exception:: DatabaseError Exception raised for errors that are related to the database. - This serves the base exception for several types of database errors. + This serves as the base exception for several types of database errors. It is only raised implicitly through the specialised variants. ``DatabaseError`` is a subclass of :exc:`Error`. From 9fec685552b8e694270f7dd8e9cc8e4c2abc87ff Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Tue, 31 May 2022 13:46:01 +0200 Subject: [PATCH 08/17] Update Doc/library/sqlite3.rst Co-authored-by: Alex Waygood --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 5eba5d40bcc24c..96eb001baf26ef 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1136,7 +1136,7 @@ The exception hierarchy is defined by DB-API 2.0. 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 variants. + It is only raised implicitly through the specialised subclasses. ``DatabaseError`` is a subclass of :exc:`Error`. .. exception:: DataError From e0cc0d4735feaec4300de5b237a36626f9d9ee9d Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Tue, 31 May 2022 13:46:09 +0200 Subject: [PATCH 09/17] Update Doc/library/sqlite3.rst Co-authored-by: Alex Waygood --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 96eb001baf26ef..22be94962dc218 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1142,7 +1142,7 @@ The exception hierarchy is defined by DB-API 2.0. .. exception:: DataError Exception raised for errors caused by problems with the processed data, - like numeric value out of range, and too long strings. + like numeric values out of range, and strings which are too long. ``DataError`` is a subclass of :exc:`DatabaseError`. .. exception:: OperationalError From 1ceb02fe95cf05d24c3039fec3a3ead08ede2048 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Tue, 31 May 2022 13:52:33 +0200 Subject: [PATCH 10/17] Update Doc/library/sqlite3.rst Co-authored-by: Alex Waygood --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 22be94962dc218..5d5e9e72037957 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1177,7 +1177,7 @@ The exception hierarchy is defined by DB-API 2.0. 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:`create_function`, if the underlying SQLite library + :const:`True` in :meth:`~Connection.create_function`, if the underlying SQLite library does not support deterministic functions. ``NotSupportedError`` is a subclass of :exc:`DatabaseError`. From 91494dd1077e9f11c005490dffef5cd82d08b722 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 31 May 2022 13:59:29 +0200 Subject: [PATCH 11/17] Address review --- Doc/library/sqlite3.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 5d5e9e72037957..240792a61ad8d0 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1102,7 +1102,7 @@ The exception hierarchy is defined by DB-API 2.0. .. exception:: Warning - This exception is not raised by :mod:`sqlite3`. + This exception is not raised by ``sqlite3``. ``Warning`` is a subclass of :exc:`Exception`. .. exception:: Error @@ -1156,8 +1156,7 @@ The exception hierarchy is defined by DB-API 2.0. .. exception:: IntegrityError Exception raised when the relational integrity of the database is affected, - for example, a foreign key check fails. - ``IntegrityError`` is a subclass of :exc:`DatabaseError`. + e.g. a foreign key check fails. It is a subclass of :exc:`DatabaseError`. .. exception:: InternalError From aa140d4a3acc5f48dc18621d622e790e36cd899a Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 1 Jun 2022 09:56:45 +0200 Subject: [PATCH 12/17] Reword ProgrammingError --- Doc/library/sqlite3.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 240792a61ad8d0..ba63397f01230a 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1098,7 +1098,7 @@ Blob Objects Exceptions ---------- -The exception hierarchy is defined by DB-API 2.0. +The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`). .. exception:: Warning @@ -1167,9 +1167,9 @@ The exception hierarchy is defined by DB-API 2.0. .. exception:: ProgrammingError - Exception raised for ``sqlite3`` API programming errors. - for example syntax errors in SQL statements, and wrong number of bindings - supplied to a query. + Exception raised for ``sqlite3`` API programming errors, + for example supplying the wrong number of bindings to a query, + or trying to operate on a closed :class:`Connection`. ``ProgrammingError`` is a subclass of :exc:`DatabaseError`. .. exception:: NotSupportedError From 59dcdbda7bdd0f64b2685dd544dddaeb1e44f6fd Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 1 Jun 2022 10:02:52 +0200 Subject: [PATCH 13/17] Reword Waning --- Doc/library/sqlite3.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index ba63397f01230a..c6d4f2e39e0358 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -844,7 +844,7 @@ Cursor Objects :ref:`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:`ProgrammingError`. Use :meth:`executescript` if you want to execute multiple SQL statements with one call. @@ -1102,7 +1102,9 @@ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`). .. exception:: Warning - This exception is not raised by ``sqlite3``. + This exception is not currently raised by the ``sqlite3`` module, + but may be raised by applications using ``sqlite3``, + for example if a user-defined function trunkates data while inserting. ``Warning`` is a subclass of :exc:`Exception`. .. exception:: Error From 9c112a8b2fce65cfa28da773c7852c1c6b061475 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 1 Jun 2022 10:05:07 +0200 Subject: [PATCH 14/17] Revert incorrect change --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index c6d4f2e39e0358..c8428e7b51b536 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -844,7 +844,7 @@ Cursor Objects :ref:`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:`ProgrammingError`. 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. From 8b7293e47441d65786c05d19d0921d31b574f164 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 1 Jun 2022 10:10:51 +0200 Subject: [PATCH 15/17] Revert "Revert incorrect change" This reverts commit 9c112a8b2fce65cfa28da773c7852c1c6b061475. --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index c8428e7b51b536..c6d4f2e39e0358 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -844,7 +844,7 @@ Cursor Objects :ref:`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:`ProgrammingError`. Use :meth:`executescript` if you want to execute multiple SQL statements with one call. From c25c95e87766bae3edadebe6c95ee79933c24a15 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Wed, 1 Jun 2022 10:11:29 +0200 Subject: [PATCH 16/17] Update Doc/library/sqlite3.rst Co-authored-by: Alex Waygood --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index c6d4f2e39e0358..0e753855c01867 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1104,7 +1104,7 @@ The exception hierarchy is defined by the DB-API 2.0 (:pep:`249`). This exception is not currently raised by the ``sqlite3`` module, but may be raised by applications using ``sqlite3``, - for example if a user-defined function trunkates data while inserting. + for example if a user-defined function truncates data while inserting. ``Warning`` is a subclass of :exc:`Exception`. .. exception:: Error From 7c1bd6cab7937343b23f0f0208b4b37e71b56e2b Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 1 Jun 2022 10:39:05 +0200 Subject: [PATCH 17/17] Adjust a couple of more inconsistencies --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 0e753855c01867..5c62047a421895 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -581,7 +581,7 @@ Connection Objects method with :const:`None` for *handler*. Returning a non-zero value from the handler function will terminate the - currently executing query and cause it to raise an :exc:`OperationalError` + currently executing query and cause it to raise a :exc:`DatabaseError` exception. @@ -813,7 +813,7 @@ Connection Objects *name*, and reopen *name* as an in-memory database based on the serialization contained in *data*. Deserialization will raise :exc:`OperationalError` if the database connection is currently involved - in a read transaction or a backup operation. :exc:`DataError` will be + in a read transaction or a backup operation. :exc:`OverflowError` will be raised if ``len(data)`` is larger than ``2**63 - 1``, and :exc:`DatabaseError` will be raised if *data* does not contain a valid SQLite database.