From cdf3689aa57e4682c023e81b14ba9f5f4251691a Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 19 Jun 2022 13:25:55 -0700 Subject: [PATCH] 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 Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> Automerge-Triggered-By: GH:erlend-aasland (cherry picked from commit 8e0897814109765a9e463676413fff016875217b) Co-authored-by: Erlend Egeberg Aasland --- Doc/library/sqlite3.rst | 22 +++++++++++++++---- ...2-06-16-10-10-59.gh-issue-61162.1ypkG8.rst | 1 + 2 files changed, 19 insertions(+), 4 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2022-06-16-10-10-59.gh-issue-61162.1ypkG8.rst diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index fbaebeed654249..2fb2b62c6d25af 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 00000000000000..c8b3a222232189 --- /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`.