Skip to content

Commit

Permalink
[3.10] gh-89018: Improve documentation of sqlite3 exceptions (GH-27645
Browse files Browse the repository at this point in the history
) (#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 bb0b768)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
  • Loading branch information
erlend-aasland authored Jun 15, 2022
1 parent 095d09c commit 56ee410
Showing 1 changed file with 48 additions and 17 deletions.
65 changes: 48 additions & 17 deletions Doc/library/sqlite3.rst
Original file line number Diff line number Diff line change
Expand Up @@ -681,7 +681,7 @@ Cursor Objects
: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.

Expand Down Expand Up @@ -883,43 +883,74 @@ Now we plug :class:`Row` in::
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:: ProgrammingError
.. exception:: InternalError

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 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:: OperationalError
.. exception:: ProgrammingError

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:
Expand Down

0 comments on commit 56ee410

Please sign in to comment.