gh-83638: Add sqlite3.Connection.autocommit for PEP 249 compliant behaviour

Doc/library/sqlite3.rst

@@ -235,8 +235,14 @@ Module functions and constants
    everything until the first ``'['`` for the column name and strip
    the preceding space: the column name would simply be "Expiration date".
 
+.. data:: DEPRECATED_TRANSACTION_CONTROL
 
-.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])
+   Set :attr:`~Connection.autocommit` to this constant to select deprecated
+   (pre Python 3.12) transaction control.
+   See :ref:`sqlite3-deprecated-transaction-control` for more information.
+
+
+.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri, autocommit])
 
    Opens a connection to the SQLite database file *database*. By default returns a
    :class:`Connection` object, unless a custom *factory* is given.
@@ -255,6 +261,11 @@ Module functions and constants
    For the *isolation_level* parameter, please see the
    :attr:`~Connection.isolation_level` property of :class:`Connection` objects.
 
+   For the *autocommit* parameter, please see the
+   :attr:`~Connection.autocommit` property. *autocommit* currently defaults to
+   :data:`~Connection.DEPRECATED_TRANSACTION_CONTROL`.
+   The default will change to :const:`False` in Python 3.14.
+
    SQLite natively supports only the types TEXT, INTEGER, REAL, BLOB and NULL. If
    you want to use other types you must add support for them yourself. The
    *detect_types* parameter and the using custom **converters** registered with the
@@ -318,6 +329,10 @@ Module functions and constants
    .. versionchanged:: 3.10
       Added the ``sqlite3.connect/handle`` auditing event.
 
+   .. versionchanged:: 3.12
+      Added the *autocommit* parameter.
+      Deprecated the *isolation_level* parameter.
+
 
 .. function:: register_converter(typename, callable)
 
@@ -385,6 +400,24 @@ Connection Objects
 
    An SQLite database connection has the following attributes and methods:
 
+   .. attribute:: autocommit
+
+      Get or set the :pep:`249` transaction behaviour.
+      *autocommit* has tree allowed values:
+
+      * :const:`False`: PEP 249 compliant transaction behaviour,
+        implying that a transaction is always open.
+        Use :meth:`commit` and :meth:`rollback` to close transactions.
+        Closing a transaction immediately opens a new one.
+        This will be the default value of *autocommit* in Python 3.14.
+
+      * :const:`True`: Use SQLite's autocommit behaviour.
+        You are also free to :meth:`execute` custom transaction statements.
+
+      * :data:`DEPRECATED_TRANSACTION_CONTROL`: Pre Python 3.12 compliant
+        transaction control. See :attr:`isolation_level`.
+        This is currently the default value of *autocommit*.
+
    .. attribute:: isolation_level
 
       Get or set the current default isolation level. :const:`None` for autocommit mode or
@@ -1365,41 +1398,83 @@ timestamp converter.
 
 .. _sqlite3-controlling-transactions:
 
-Controlling Transactions
-------------------------
+Controlling Transactions Using the Autocommit Property
+------------------------------------------------------
 
 The underlying ``sqlite3`` library operates in ``autocommit`` mode by default,
 but the Python :mod:`sqlite3` module by default does not.
 
-``autocommit`` mode means that statements that modify the database take effect
+Use the :attr:`~Connection.autocommit` property to select transaction mode.
+This attribute can also be set when :meth:`connecting <~Connection.connect>`.
+
+Currently, *autocommit* defaults to :const:`DEPRECATED_TRANSACTION_CONTROL`,
+which means transaction control is selected using the
+:attr:`~Connection.isolation_level` property.
+See :ref:`sqlite3-deprecated-transaction-control` for more information.
+
+Starting with Python 3.14, *autocommit* will default to :const:`False`,
+which will imply :pep:`249` compliant transaction control. This means:
+
+* A transaction is always open.
+* Commit transactions using :meth:`~Connection.commit`.
+* Roll back transactions using :meth:`~Connection.rollback`.
+* Commit and rollback will open a new transaction immediately after execution.
+* An implicit rollback is performed if the database is closed with pending
+  changes.
+
+Set *autocommit* to :const:`True` to enable SQLite's autocommit mode.
+This mode is equal to setting :attr:`~Connection.isolation_level` to
+:const:`None`.
+
+``autocommit=True`` means that statements that modify the database take effect
 immediately.  A ``BEGIN`` or ``SAVEPOINT`` statement disables ``autocommit``
 mode, and a ``COMMIT``, a ``ROLLBACK``, or a ``RELEASE`` that ends the
 outermost transaction, turns ``autocommit`` mode back on.
 
-The Python :mod:`sqlite3` module by default issues a ``BEGIN`` statement
-implicitly before a Data Modification Language (DML) statement (i.e.
-``INSERT``/``UPDATE``/``DELETE``/``REPLACE``).
 
-You can control which kind of ``BEGIN`` statements :mod:`sqlite3` implicitly
+.. _sqlite3-deprecated-transaction-control:
+
+Controlling Transactions Using the Isolation Level Property
+-----------------------------------------------------------
+
+.. note::
+
+   The recommended way of controlling transactions, is via the
+   :attr:`~Connection.autocommit` parameter.
+
+If :attr:`~Connection.autocommit` is set to
+:data:`DEPRECATED_TRANSACTION_CONTROL`, transaction control is selected using
+the :attr:`~Connection.isolation_level` parameter.
+
+``isolation_level`` defaults to the empty string: ``""``. This implies that
+the Python :mod:`sqlite3` module issues a ``BEGIN`` statement
+implicitly before a Data Modification Language (DML) statement
+(``INSERT``, ``UPDATE``, ``DELETE``, and ``REPLACE``).
+
+You can control the kind of ``BEGIN`` statement ``sqlite3`` implicitly
 executes via the *isolation_level* parameter to the :func:`connect`
-call, or via the :attr:`isolation_level` property of connections.
-If you specify no *isolation_level*, a plain ``BEGIN`` is used, which is
-equivalent to specifying ``DEFERRED``.  Other possible values are ``IMMEDIATE``
-and ``EXCLUSIVE``.
+call, or via the :attr:`isolation_level` property of connection objects.
+By default, ``BEGIN`` is used, which is equivalent to
+``isolation_level="DEFERRED"``.
+Other possible values are ``"IMMEDIATE"`` and ``"EXCLUSIVE"``.
 
-You can disable the :mod:`sqlite3` module's implicit transaction management by
+Disable the :mod:`sqlite3` module's implicit transaction control by
 setting :attr:`isolation_level` to ``None``.  This will leave the underlying
 ``sqlite3`` library operating in ``autocommit`` mode.  You can then completely
-control the transaction state by explicitly issuing ``BEGIN``, ``ROLLBACK``,
+control transactions by explicitly executing ``BEGIN``, ``ROLLBACK``,
 ``SAVEPOINT``, and ``RELEASE`` statements in your code.
 
 Note that :meth:`~Cursor.executescript` disregards
 :attr:`isolation_level`; any transaction control must be added explicitly.
 
 .. versionchanged:: 3.6
-   :mod:`sqlite3` used to implicitly commit an open transaction before DDL
+   ``sqlite3`` used to implicitly commit an open transaction before DDL
    statements.  This is no longer the case.
 
+.. versionchanged: 3.12
+   The recommended way of controlling transactions is now via the
+   :attr:`~Connection.autocommit` parameter.
+
 
 Using :mod:`sqlite3` efficiently
 --------------------------------
@@ -1441,6 +1516,10 @@ committed:
 
 .. literalinclude:: ../includes/sqlite3/ctx_manager.py
 
+.. note::
+
+   The context manager does not implicitly begin a new transaction.
+
 
 .. rubric:: Footnotes
 

Doc/whatsnew/3.12.rst

@@ -98,6 +98,14 @@ os
   (Contributed by Kumar Aditya in :gh:`93312`.)
 
 
+sqlite3
+-------
+
+* Add :attr:`~sqlite3.Connection.autocommit` parameter for :pep:`249` compliant
+  transaction handling.
+  (Contributed by Erlend E. Aasland in :gh:`83638`.)
+
+
 Optimizations
 =============
 
@@ -118,6 +126,9 @@ CPython bytecode changes
 Deprecated
 ==========
 
+* The :attr:`sqlite3.Connection.isolation_level` parameter is deprecated.
+  Please use the new :attr:`sqlite3.Connection.autocommit` parameter instead.
+
 
 Pending Removal in Python 3.13
 ==============================

Lib/test/test_sqlite3/test_transactions.py

@@ -22,6 +22,7 @@
 
 import os, unittest
 import sqlite3 as sqlite
+from contextlib import contextmanager
 
 from test.support import LOOPBACK_TIMEOUT
 from test.support.os_helper import TESTFN, unlink
@@ -327,5 +328,102 @@ def test_isolation_level_none(self):
         self.assertEqual(self.traced, [self.QUERY])
 
 
+class AutocommitPEP249(unittest.TestCase):
+    """Test PEP-249 compliant autocommit behaviour."""
+    @contextmanager
+    def check_stmt_trace(self, cx, expected, reset=True):
+        try:
+            traced = []
+            cx.set_trace_callback(lambda stmt: traced.append(stmt))
+            yield
+        finally:
+            self.assertEqual(traced, expected)
+            if reset:
+                cx.set_trace_callback(None)
+
+    def test_autocommit_default(self):
+        with memory_database() as cx:
+            self.assertEqual(cx.autocommit,
+                             sqlite.DEPRECATED_TRANSACTION_CONTROL)
+
+    def test_autocommit_setget(self):
+        dataset = (
+            True,
+            False,
+            sqlite.DEPRECATED_TRANSACTION_CONTROL,
+        )
+        for mode in dataset:
+            with self.subTest(mode=mode):
+                with memory_database(autocommit=mode) as cx:
+                    self.assertEqual(cx.autocommit, mode)
+                with memory_database() as cx:
+                    cx.autocommit = mode
+                    self.assertEqual(cx.autocommit, mode)
+
+    def test_autocommit_setget_invalid(self):
+        msg = "autocommit must be True, False, or.*DEPRECATED"
+        for mode in "a", 12, (), None:
+            with self.subTest(mode=mode):
+                with self.assertRaisesRegex(ValueError, msg):
+                    with memory_database(autocommit=mode) as cx:
+                        self.assertEqual(cx.autocommit, mode)
+
+    def test_autocommit_disabled(self):
+        expected = [
+            "SELECT 1",
+            "COMMIT",
+            "BEGIN",
+            "ROLLBACK",
+            "BEGIN",
+        ]
+        with memory_database(autocommit=False) as cx:
+            self.assertTrue(cx.in_transaction)
+            with self.check_stmt_trace(cx, expected):
+                cx.execute("SELECT 1")
+                cx.commit()
+                cx.rollback()
+
+    def test_autocommit_disabled_implicit_rollback(self):
+        expected = ["ROLLBACK"]
+        with memory_database(autocommit=False) as cx:
+            self.assertTrue(cx.in_transaction)
+            with self.check_stmt_trace(cx, expected, reset=False):
+                cx.close()
+
+    def test_autocommit_enabled(self):
+        expected = ["SELECT 1"]
+        with memory_database(autocommit=True) as cx:
+            self.assertFalse(cx.in_transaction)
+            with self.check_stmt_trace(cx, expected):
+                cx.execute("SELECT 1")
+                cx.commit()  # expect this to pass silently
+                self.assertFalse(cx.in_transaction)
+
+    def test_autocommit_disabled_then_enabled(self):
+        expected = ["COMMIT"]
+        with memory_database(autocommit=False) as cx:
+            self.assertTrue(cx.in_transaction)
+            with self.check_stmt_trace(cx, expected):
+                cx.autocommit = True  # should commit
+                self.assertFalse(cx.in_transaction)
+
+    def test_autocommit_enabled_then_disabled(self):
+        expected = ["BEGIN"]
+        with memory_database(autocommit=True) as cx:
+            self.assertFalse(cx.in_transaction)
+            with self.check_stmt_trace(cx, expected):
+                cx.autocommit = False  # should begin
+                self.assertTrue(cx.in_transaction)
+
+    def test_autocommit_explicit_then_disabled(self):
+        expected = ["BEGIN DEFERRED", "COMMIT", "BEGIN"]
+        with memory_database(autocommit=True) as cx:
+            self.assertFalse(cx.in_transaction)
+            with self.check_stmt_trace(cx, expected):
+                cx.execute("BEGIN DEFERRED")
+                cx.autocommit = False  # should commit, then begin
+                self.assertTrue(cx.in_transaction)
+
+
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/Library/2022-06-14-22-46-05.gh-issue-83638.73xfGK.rst

@@ -0,0 +1,2 @@
+Add :attr:`sqlite3.Connection.autocommit` for :pep:`249` compliant
+transaction control. Patch by Erlend E. Aasland.