[Python-checkins] bpo-45089: Improve sqlite3 trace callback docs (GH-28238) (GH-28372)

[ambv]

https://github.com/python/cpython/commit/97802a8edb3f15aef9ecc1cac97c4c1b4ed3fdfc
commit: 97802a8edb3f15aef9ecc1cac97c4c1b4ed3fdfc
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2021-09-15T21:09:27+02:00
summary:

bpo-45089: Improve sqlite3 trace callback docs (GH-28238) (GH-28372)

- Add link to str object and sqlite3 transaction control
- Mention that exceptions are not propagated
(cherry picked from commit 51056b40e711d84692d099ac8970077b33c7fafd)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland at innova.no>

files:
M Doc/library/sqlite3.rst

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index c0b6ab079588d..2600a3db17e0c 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -446,14 +446,22 @@ Connection Objects
       Registers *trace_callback* to be called for each SQL statement that is
       actually executed by the SQLite backend.
 
-      The only argument passed to the callback is the statement (as string) that
-      is being executed. The return value of the callback is ignored. Note that
-      the backend does not only run statements passed to the :meth:`Cursor.execute`
-      methods.  Other sources include the transaction management of the Python
-      module and the execution of triggers defined in the current database.
+      The only argument passed to the callback is the statement (as
+      :class:`str`) that is being executed. The return value of the callback is
+      ignored. Note that the backend does not only run statements passed to the
+      :meth:`Cursor.execute` methods.  Other sources include the
+      :ref:`transaction management <sqlite3-controlling-transactions>` of the
+      sqlite3 module and the execution of triggers defined in the current
+      database.
 
       Passing :const:`None` as *trace_callback* will disable the trace callback.
 
+      .. note::
+         Exceptions raised in the trace callback are not propagated. As a
+         development and debugging aid, use
+         :meth:`~sqlite3.enable_callback_tracebacks` to enable printing
+         tracebacks from exceptions raised in the trace callback.
+
       .. versionadded:: 3.3