diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/sqlite3.rst | 65 |
1 files changed, 48 insertions, 17 deletions
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 @@ 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. @@ -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: |