[Python-checkins] gh-61162: Clarify sqlite3 connection context manager docs (GH-93890)

[miss-islington]

https://github.com/python/cpython/commit/cdf3689aa57e4682c023e81b14ba9f5f4251691a
commit: cdf3689aa57e4682c023e81b14ba9f5f4251691a
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-06-19T13:25:55-07:00
summary:

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 at Gerlach.CAM>
Co-authored-by: Stanley <46876382+slateny at users.noreply.github.com>

Automerge-Triggered-By: GH:erlend-aasland
(cherry picked from commit 8e0897814109765a9e463676413fff016875217b)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland at protonmail.com>

files:
A Misc/NEWS.d/next/Documentation/2022-06-16-10-10-59.gh-issue-61162.1ypkG8.rst
M Doc/library/sqlite3.rst

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index fbaebeed65424..2fb2b62c6d25a 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -1188,13 +1188,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
index 0000000000000..c8b3a22223218
--- /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`.