diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 1681fc49e9f1e0..20d0e1ae33aa65 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -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 ` 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 ` 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 diff --git a/Lib/test/test_sqlite3/test_transactions.py b/Lib/test/test_sqlite3/test_transactions.py index 5d211dd47b0b6b..d09a60248e83ca 100644 --- a/Lib/test/test_sqlite3/test_transactions.py +++ b/Lib/test/test_sqlite3/test_transactions.py @@ -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()