gh-61162: Clarify sqlite3 connection context manager docs (GH-93890)

Explicitly note that transactions are only closed if there is an open
transation at `__exit__`, and that transactions are not implicitly
opened during `__enter__`.

Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
Automerge-Triggered-By: GH:erlend-aasland

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 357b7b4365d5bac67200f78a53aef4d11bedeeb5..c1d6b946f4e5c5a3d77e8385139026fdb66af758 100644 (file)
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -1430,13 +1430,27 @@ case-insensitively by name:
 .. literalinclude:: ../includes/sqlite3/rowclass.py
 
 
+.. _sqlite3-connection-context-manager:
+
 Using the connection as a context manager
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Connection objects can be used as context managers
-that automatically commit or rollback transactions.  In the event of an
-exception, the transaction is rolled back; otherwise, the transaction is
-committed:
+A :class:`Connection` object can be used as a context manager that
+automatically commits or rolls back open transactions when leaving the body of
+the context manager.
+If the body of the :keyword:`with` statement finishes without exceptions,
+the transaction is committed.
+If this commit fails,
+or if the body of the ``with`` statement raises an uncaught exception,
+the transaction is rolled back.
+
+If there is no open transaction upon leaving the body of the ``with`` statement,
+the context manager is a no-op.
+
+.. note::
+
+   The context manager neither implicitly opens a new transaction
+   nor closes the connection.
 
 .. literalinclude:: ../includes/sqlite3/ctx_manager.py
 

diff --git a/Misc/NEWS.d/next/Documentation/2022-06-16-10-10-59.gh-issue-61162.1ypkG8.rst b/Misc/NEWS.d/next/Documentation/2022-06-16-10-10-59.gh-issue-61162.1ypkG8.rst
new file mode 100644 (file)
index 0000000..c8b3a22
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-06-16-10-10-59.gh-issue-61162.1ypkG8.rst
@@ -0,0 +1 @@
+Clarify :mod:`sqlite3` behavior when :ref:`sqlite3-connection-context-manager`.