python · geryogam · Nov 13, 2022 · Nov 13, 2022 · Nov 21, 2022 · Nov 21, 2022
@@ -634,27 +634,27 @@ Connection objects
 
    .. method:: commit()
 
-      Commit any pending transaction to the database.
+      Commit any open transaction to the database.
       If :attr:`autocommit` is ``True``, or there is no open transaction,
       this method does nothing.
-      If :attr:`!autocommit` is ``False``, a new transaction is implicitly
-      opened if a pending transaction was committed by this method.
+      If :attr:`!autocommit` is ``False``, this method implicitly opens
+      a new transaction after committing.
 
    .. method:: rollback()
 
-      Roll back to the start of any pending transaction.
+      Roll back to the start of any open transaction.
       If :attr:`autocommit` is ``True``, or there is no open transaction,
       this method does nothing.
-      If :attr:`!autocommit` is ``False``, a new transaction is implicitly
-      opened if a pending transaction was rolled back by this method.
+      If :attr:`!autocommit` is ``False``, this method implicitly opens
+      a new transaction after rolling back.
 
    .. method:: close()
 
       Close the database connection.
-      If :attr:`autocommit` is ``False``,
-      any pending transaction is implicitly rolled back.
+      If :attr:`autocommit` is ``False``, this method implicitly rolls back
+      any open transaction before closing.
       If :attr:`!autocommit` is ``True`` or :data:`LEGACY_TRANSACTION_CONTROL`,
-      no implicit transaction control is executed.
+      this method does not perform any implicit transaction control.
       Make sure to :meth:`commit` before closing
       to avoid losing pending changes.
 
@@ -1257,23 +1257,22 @@ Connection objects
       This attribute controls :pep:`249`-compliant transaction behaviour.
       :attr:`!autocommit` has three allowed values:
 
-      * ``False``: Select :pep:`249`-compliant transaction behaviour,
-        implying that :mod:`!sqlite3` ensures a transaction is always open.
+      * ``False``: :pep:`249`-compliant manual commit mode.
         Use :meth:`commit` and :meth:`rollback` to close transactions.
 
         This is the recommended value of :attr:`!autocommit`.
 
-      * ``True``: Use SQLite's `autocommit mode`_.
+      * ``True``: :pep:`249`-compliant autocommit mode.
         :meth:`commit` and :meth:`rollback` have no effect in this mode.
 
       * :data:`LEGACY_TRANSACTION_CONTROL`:
-        Pre-Python 3.12 (non-:pep:`249`-compliant) transaction control.
+        Legacy (pre-Python 3.12) transaction control.
         See :attr:`isolation_level` for more details.
 
         This is currently the default value of :attr:`!autocommit`.
 
       Changing :attr:`!autocommit` to ``False`` will open a new transaction,
-      and changing it to ``True`` will commit any pending transaction.
+      and changing it to ``True`` will commit any open transaction.
 
       See :ref:`sqlite3-transaction-control-autocommit` for more details.
 
@@ -1286,7 +1285,7 @@ Connection objects
 
    .. attribute:: in_transaction
 
-      This read-only attribute corresponds to the low-level SQLite
+      This read-only attribute corresponds to the low-level SQLite's
       `autocommit mode`_.
 
       ``True`` if a transaction is active (there are uncommitted changes),
@@ -1296,11 +1295,11 @@ Connection objects
 
    .. attribute:: isolation_level
 
-      Controls the :ref:`legacy transaction handling mode
+      Sets the :ref:`legacy transaction control mode
       <sqlite3-transaction-control-isolation-level>` of :mod:`!sqlite3`.
       If set to ``None``, transactions are never implicitly opened.
       If set to one of ``"DEFERRED"``, ``"IMMEDIATE"``, or ``"EXCLUSIVE"``,
-      corresponding to the underlying `SQLite transaction behaviour`_,
+      corresponding to the `SQLite transaction behaviour`_,
       :ref:`implicit transaction management
       <sqlite3-transaction-control-isolation-level>` is performed.
 
@@ -1309,7 +1308,7 @@ Connection objects
 
       .. note::
 
-         Using :attr:`autocommit` to control transaction handling is
+         Using :attr:`autocommit` to set transaction control is
          recommended over using :attr:`!isolation_level`.
          :attr:`!isolation_level` has no effect unless :attr:`autocommit` is
          set to :data:`LEGACY_TRANSACTION_CONTROL` (the default).
@@ -1456,7 +1455,7 @@ Cursor objects
       against all parameter sequences or mappings found in the sequence
       *parameters*.  It is also possible to use an
       :term:`iterator` yielding parameters instead of a sequence.
-      Uses the same implicit transaction handling as :meth:`~Cursor.execute`.
+      Uses the same implicit transaction control as :meth:`~Cursor.execute`.
 
       Example:
 
@@ -1474,7 +1473,7 @@ Cursor objects
       Execute the SQL statements in *sql_script*.
       If the :attr:`~Connection.autocommit` is
       :data:`LEGACY_TRANSACTION_CONTROL`
-      and there is a pending transaction,
+      and there is an open transaction,
       an implicit ``COMMIT`` statement is executed first.
       No other implicit transaction control is performed;
       any transaction control must be added to *sql_script*.
@@ -2385,30 +2384,35 @@ the :attr:`Connection.autocommit` attribute,
 which should preferrably be set using the *autocommit* parameter
 of :func:`connect`.
 
-It is suggested to set *autocommit* to ``False``,
-which implies :pep:`249`-compliant transaction control.
+It is suggested to set *autocommit* to ``False`` to enable the
+:pep:`249`-compliant manual commit mode.
 This means:
 
-* :mod:`!sqlite3` ensures that a transaction is always open,
-  so :meth:`Connection.commit` and :meth:`Connection.rollback`
-  will implicitly open a new transaction immediately after closing
-  the pending one.
-  :mod:`!sqlite3` uses ``BEGIN DEFERRED`` statements when opening transactions.
-* Transactions should be committed explicitly using :meth:`!commit`.
-* Transactions should be rolled back explicitly using :meth:`!rollback`.
-* An implicit rollback is performed if the database is
-  :meth:`~Connection.close`-ed with pending changes.
-
-Set *autocommit* to ``True`` to enable SQLite's `autocommit mode`_.
-In this mode, :meth:`Connection.commit` and :meth:`Connection.rollback`
-have no effect.
+* :meth:`Connection.connect`, :meth:`Connection.commit`,
+  and :meth:`Connection.rollback` implicitly open a new transaction to ensure
+  that a transaction is always open.
+  Those methods use a ``BEGIN DEFERRED`` statement when opening a transaction.
+* Transactions should be explicitly committed using :meth:`!commit`.
+* Transactions should be explicitly rolled back using :meth:`!rollback`.
+* :meth:`Connection.close` implicitly rolls back any open transaction.
+
+Set *autocommit* to ``True`` to enable the :pep:`249`-compliant autocommit mode.
+This means:
+
+* No implicit transaction control is performed.
+  This leaves SQLite in `autocommit mode`_,
+  but also allows the user to perform their own transaction control
+  using explicit SQL-transaction statements.
+* :meth:`Connection.commit` and :meth:`Connection.rollback` have no effect.
+
 Note that SQLite's autocommit mode is distinct from
 the :pep:`249`-compliant :attr:`Connection.autocommit` attribute;
-use :attr:`Connection.in_transaction` to query
-the low-level SQLite autocommit mode.
+SQLite's autocommit mode can be queried using the
+:attr:`Connection.in_transaction` attribute.
 
-Set *autocommit* to :data:`LEGACY_TRANSACTION_CONTROL`
-to leave transaction control behaviour to the
+Set *autocommit* to :data:`LEGACY_TRANSACTION_CONTROL` to enable legacy
+(pre-Python 3.12) transaction control.
+This means transaction control behaviour is left to the
 :attr:`Connection.isolation_level` attribute.
 See :ref:`sqlite3-transaction-control-isolation-level` for more information.
 
@@ -2430,29 +2434,29 @@ transaction behaviour is controlled using
 the :attr:`Connection.isolation_level` attribute.
 Otherwise, :attr:`!isolation_level` has no effect.
 
-If the connection attribute :attr:`~Connection.isolation_level`
-is not ``None``,
-new transactions are implicitly opened before
-:meth:`~Cursor.execute` and :meth:`~Cursor.executemany` executes
-``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statements;
-for other statements, no implicit transaction handling is performed.
-Use the :meth:`~Connection.commit` and :meth:`~Connection.rollback` methods
-to respectively commit and roll back pending transactions.
-You can choose the underlying `SQLite transaction behaviour`_ —
-that is, whether and what type of ``BEGIN`` statements :mod:`!sqlite3`
-implicitly executes –
-via the :attr:`~Connection.isolation_level` attribute.
+If :attr:`~Connection.isolation_level` is not ``None``:
+
+* :meth:`~Cursor.execute` and :meth:`~Cursor.executemany` implicitly open a new
+  transaction before executing an
+  ``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statement;
+  for other statements, no implicit transaction control is performed.
+  The type of ``BEGIN`` statement that those methods use for the
+  `SQLite transaction behaviour`_ can be chosen via the
+  :attr:`~Connection.isolation_level` attribute.
+* Transactions should be explicitly committed using :meth:`!commit`.
+* Transactions should be explicitly rolled back using :meth:`!rollback`.
 
 If :attr:`~Connection.isolation_level` is set to ``None``,
-no transactions are implicitly opened at all.
-This leaves the underlying SQLite library in `autocommit mode`_,
-but also allows the user to perform their own transaction handling
-using explicit SQL statements.
-The underlying SQLite library autocommit mode can be queried using the
+no implicit transaction control is performed.
+This leaves SQLite in `autocommit mode`_,
+but also allows the user to perform their own transaction control
+using explicit SQL-transaction statements.
+
+SQLite's autocommit mode can be queried using the
 :attr:`~Connection.in_transaction` attribute.
 
-The :meth:`~Cursor.executescript` method implicitly commits
-any pending transaction before execution of the given SQL script,
+:meth:`~Cursor.executescript` implicitly commits any open transaction before
+executing the given SQL script,
 regardless of the value of :attr:`~Connection.isolation_level`.
 
 .. versionchanged:: 3.6

@@ -325,7 +325,7 @@ def setUp(self):
         self.cx = sqlite.connect(":memory:")
         self.cx.execute("create table t(t)")
         self.traced = []
-        self.cx.set_trace_callback(lambda stmt: self.traced.append(stmt))
+        self.cx.set_trace_callback(self.traced.append)
 
     def tearDown(self):
         self.cx.close()