Clarify PEP-249 compliance

Author: geryogam

Doc/library/sqlite3.rst

@@ -654,7 +654,7 @@ Connection objects
       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`,
-      this method does not execute any implicit transaction control.
+      this method does not perform any implicit transaction control.
       Make sure to :meth:`commit` before closing
       to avoid losing pending changes.
 
@@ -1257,17 +1257,16 @@ 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.
+        Non-:pep:`249`-compliant (pre-Python 3.12) transaction control.
         See :attr:`isolation_level` for more details.
 
         This is currently the default value of :attr:`!autocommit`.
@@ -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),
@@ -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 open 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
+non-:pep:`249`-compliant (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 open 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 new a 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 underlying
+  `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 open 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