diff options
| author | Erlend Egeberg Aasland <erlend.aasland@protonmail.com> | 2022-06-19 20:17:43 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-06-19 20:17:43 (GMT) |
| commit | 8e0897814109765a9e463676413fff016875217b (patch) | |
| tree | 543ba00b7a6276cfb495994d6565076c89262982 | |
| parent | 6446592c89b0c581c00e170ae6278291e940755c (diff) | |
| download | cpython-8e0897814109765a9e463676413fff016875217b.zip cpython-8e0897814109765a9e463676413fff016875217b.tar.gz cpython-8e0897814109765a9e463676413fff016875217b.tar.bz2 | |
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
| -rw-r--r-- | Doc/library/sqlite3.rst | 22 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2022-06-16-10-10-59.gh-issue-61162.1ypkG8.rst | 1 |
2 files changed, 19 insertions, 4 deletions
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 357b7b4..c1d6b94 100644 --- 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 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`. |