From 672ce97bdf606744a3990423afb28ce939dc5a21 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 16 Jun 2022 10:09:00 +0200 Subject: [PATCH 01/16] gh-61162: Clarify sqlite3 connection context manager docs Explicitly note that transactions are only closed if there is an open transation, and that transactions are _not_ implicitly opened in context manager __enter__. --- Doc/library/sqlite3.rst | 12 +++++++++--- .../2022-06-16-10-10-59.gh-issue-61162.1ypkG8.rst | 1 + 2 files changed, 10 insertions(+), 3 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 32de16594c0ed1..47ccacc7183f98 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1435,9 +1435,15 @@ 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: +that automatically commit or rollback transactions, +*if* there is an open transaction. +If there is no open transaction, the context manager is a no-op. +In the event of an exception, the transaction is rolled back; +otherwise, the transaction is committed: + +.. note:: + + The context manager does not implicitly start a new transaction. .. 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..92e2bb5a359e31 --- /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` connection context manager behaviour. From 61b31f9865d309ddfe1509c0da022f2d98bbfc10 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Thu, 16 Jun 2022 10:20:45 +0200 Subject: [PATCH 02/16] Update Doc/library/sqlite3.rst --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 47ccacc7183f98..42d98b50fca3b9 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1443,7 +1443,7 @@ otherwise, the transaction is committed: .. note:: - The context manager does not implicitly start a new transaction. + The context manager does not implicitly open a new transaction. .. literalinclude:: ../includes/sqlite3/ctx_manager.py From 2434ba2be26b7838779e59ca8c24b5947dfd8624 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 16 Jun 2022 10:53:26 +0200 Subject: [PATCH 03/16] Address Adam's review: focus on the happy path --- Doc/library/sqlite3.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 42d98b50fca3b9..6d9c561b9c1ab6 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1434,12 +1434,13 @@ case-insensitively by name: Using the connection as a context manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Connection objects can be used as context managers -that automatically commit or rollback transactions, -*if* there is an open transaction. +With an open transaction, connection objects can be used as context managers +that automatically commit or rollback transactions. +If the body of the ``with`` statement finishes without exceptions, +the transaction is committed. +If an exception is raised and not caught, the transaction is rolled back. + If there is no open transaction, the context manager is a no-op. -In the event of an exception, the transaction is rolled back; -otherwise, the transaction is committed: .. note:: From 71f2f45d8b49f08df950946fed97d4368777a0a3 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 16 Jun 2022 10:55:38 +0200 Subject: [PATCH 04/16] Remove the now obsolete note --- Doc/library/sqlite3.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 6d9c561b9c1ab6..328b359995d94a 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1442,10 +1442,6 @@ If an exception is raised and not caught, the transaction is rolled back. If there is no open transaction, the context manager is a no-op. -.. note:: - - The context manager does not implicitly open a new transaction. - .. literalinclude:: ../includes/sqlite3/ctx_manager.py From 76319b7f143a2cc426d0c3f2fba2e467ed9f4b39 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 16 Jun 2022 20:17:59 +0200 Subject: [PATCH 05/16] Clarify? --- Doc/library/sqlite3.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 328b359995d94a..6b6f85e5494f10 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1434,13 +1434,21 @@ case-insensitively by name: Using the connection as a context manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -With an open transaction, connection objects can be used as context managers -that automatically commit or rollback transactions. -If the body of the ``with`` statement finishes without exceptions, +Connection objects can be used as context managers that automatically commit or +rollback 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 an exception is raised and not caught, the transaction is rolled back. +If this commit fails, the transaction is rolled back. +If the body of the ``with`` statement raise an exception which is not caught, +the transaction is rolled back. -If there is no open transaction, the context manager is a no-op. +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 does not implicitly open a new transaction. + The context manager does not close the connection. .. literalinclude:: ../includes/sqlite3/ctx_manager.py From 20a100aa5a2654404845d839cb7204e060b9bca6 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Thu, 16 Jun 2022 20:25:58 +0200 Subject: [PATCH 06/16] Update sqlite3.rst --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 6b6f85e5494f10..75ad4fb44cbf7e 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1448,7 +1448,7 @@ the context manager is a no-op. .. note:: The context manager does not implicitly open a new transaction. - The context manager does not close the connection. + The context manager does not implicitly close the connection. .. literalinclude:: ../includes/sqlite3/ctx_manager.py From 28c435f5c431aff5e8269934339123bafc85dfea Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 17 Jun 2022 01:18:23 +0200 Subject: [PATCH 07/16] Add context manager anchor Co-authored-by: CAM Gerlach --- Doc/library/sqlite3.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 75ad4fb44cbf7e..4de084c22b7901 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1431,6 +1431,8 @@ case-insensitively by name: .. literalinclude:: ../includes/sqlite3/rowclass.py +.. _sqlite3-connection-context-manager: + Using the connection as a context manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 6baac817729d17ff167d8aa201fd4c4e4e4ae7a0 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 17 Jun 2022 01:19:05 +0200 Subject: [PATCH 08/16] Use anchor in NEWS entry Co-authored-by: CAM Gerlach --- .../Documentation/2022-06-16-10-10-59.gh-issue-61162.1ypkG8.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 92e2bb5a359e31..c8b3a222232189 100644 --- 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 @@ -1 +1 @@ -Clarify :mod:`sqlite3` connection context manager behaviour. +Clarify :mod:`sqlite3` behavior when :ref:`sqlite3-connection-context-manager`. From 8808fb91b0d12321ee1e3a408e81c708ad8dbf90 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 17 Jun 2022 01:25:48 +0200 Subject: [PATCH 09/16] Update Doc/library/sqlite3.rst Co-authored-by: CAM Gerlach --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 4de084c22b7901..bcab25c170cffd 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1440,8 +1440,8 @@ Connection objects can be used as context managers that automatically commit or rollback 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, the transaction is rolled back. -If the body of the ``with`` statement raise an exception which is not caught, +If this commit fails, +or the body of the ``with`` statement raise an exception which is not caught, the transaction is rolled back. If there is no open transaction upon leaving the body of the ``with`` statement, From 72373997b773a79afcc8c0f6b9a4cd6d4f84ec1d Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 17 Jun 2022 01:27:03 +0200 Subject: [PATCH 10/16] Add connection class link Co-authored-by: CAM Gerlach --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index bcab25c170cffd..cd1afc88022ed7 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1436,7 +1436,7 @@ case-insensitively by name: Using the connection as a context manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Connection objects can be used as context managers that automatically commit or +:class:`Connection` objects can be used as context managers that automatically commit or rollback 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. From 6218dba2f350620dfed5fcce02571120fd4375eb Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 17 Jun 2022 01:29:09 +0200 Subject: [PATCH 11/16] Make it more concise Co-authored-by: CAM Gerlach --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index cd1afc88022ed7..6521ce9dfbc792 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1449,8 +1449,8 @@ the context manager is a no-op. .. note:: - The context manager does not implicitly open a new transaction. - The context manager does not implicitly close the connection. + The context manager does not implicitly open a new transaction + or close the connection. .. literalinclude:: ../includes/sqlite3/ctx_manager.py From 32beb9f28970298b494d2953438eea0907adda8e Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 17 Jun 2022 09:16:43 +0200 Subject: [PATCH 12/16] Adjust wording and reflow for 79 chars --- Doc/library/sqlite3.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 6521ce9dfbc792..bde9541e65464d 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1436,8 +1436,9 @@ case-insensitively by name: Using the connection as a context manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:class:`Connection` objects can be used as context managers that automatically commit or -rollback open transactions when leaving the body of the context manager. +A :class:`Connection` object can be used as a context manager that +automatically commit or rollback 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, From a64fad4c82a742cd41400f0c15b16496eb282d7a Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 17 Jun 2022 17:38:46 +0200 Subject: [PATCH 13/16] Update Doc/library/sqlite3.rst Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index bde9541e65464d..7092f3446859a6 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1442,7 +1442,7 @@ context manager. If the body of the :keyword:`with` statement finishes without exceptions, the transaction is committed. If this commit fails, -or the body of the ``with`` statement raise an exception which is not caught, +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, From 420c8ce435326cb06a9b54a58b440a81971e7801 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Fri, 17 Jun 2022 17:44:14 +0200 Subject: [PATCH 14/16] Object is singular --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 7092f3446859a6..87fbe58f88ed25 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1437,7 +1437,7 @@ Using the connection as a context manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A :class:`Connection` object can be used as a context manager that -automatically commit or rollback open transactions when leaving the body of the +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. From 9fc380174fafa47497a9bd0e59dafdf97e55f4d1 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 17 Jun 2022 19:52:49 +0200 Subject: [PATCH 15/16] Reflow to 79 char limit --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 87fbe58f88ed25..513425e96897d8 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1437,8 +1437,8 @@ Using the connection as a context manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. +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, From b2ae22c2497310d21ab19ac334d653b07f3a1727 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sun, 19 Jun 2022 22:04:42 +0200 Subject: [PATCH 16/16] Finishing touch: Use neither...nor instead of does not...or --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 513425e96897d8..7ee5fb74cc629e 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1450,8 +1450,8 @@ the context manager is a no-op. .. note:: - The context manager does not implicitly open a new transaction - or close the connection. + The context manager neither implicitly opens a new transaction + nor closes the connection. .. literalinclude:: ../includes/sqlite3/ctx_manager.py