[Python-checkins] bpo-8145: Improve isolation_level documentation (GH-8499)
Steve Dower
webhook-mailer at python.org
Sun Jul 29 05:01:46 EDT 2018
https://github.com/python/cpython/commit/a71fed0b7596f1c11a2fa6c1b7311157148f5f9f
commit: a71fed0b7596f1c11a2fa6c1b7311157148f5f9f
branch: master
author: Berker Peksag <berker.peksag at gmail.com>
committer: Steve Dower <steve.dower at microsoft.com>
date: 2018-07-29T10:01:38+01:00
summary:
bpo-8145: Improve isolation_level documentation (GH-8499)
Initial patch by R. David Murray.
files:
M Doc/library/sqlite3.rst
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 37d2a4f50afd..9e3c56b5f918 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -281,7 +281,7 @@ Connection Objects
.. attribute:: isolation_level
- Get or set the current isolation level. :const:`None` for autocommit mode or
+ Get or set the current default isolation level. :const:`None` for autocommit mode or
one of "DEFERRED", "IMMEDIATE" or "EXCLUSIVE". See section
:ref:`sqlite3-controlling-transactions` for a more detailed explanation.
@@ -1010,22 +1010,30 @@ timestamp converter.
Controlling Transactions
------------------------
-By default, the :mod:`sqlite3` module opens transactions implicitly before a
-Data Modification Language (DML) statement (i.e.
-``INSERT``/``UPDATE``/``DELETE``/``REPLACE``).
-
-You can control which kind of ``BEGIN`` statements sqlite3 implicitly executes
-(or none at all) via the *isolation_level* parameter to the :func:`connect`
-call, or via the :attr:`isolation_level` property of connections.
+The underlying ``sqlite3`` library operates in ``autocommit`` mode by default,
+but the Python :mod:`sqlite3` module by default does not.
-If you want **autocommit mode**, then set :attr:`isolation_level` to ``None``.
+``autocommit`` mode 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.
-Otherwise leave it at its default, which will result in a plain "BEGIN"
-statement, or set it to one of SQLite's supported isolation levels: "DEFERRED",
-"IMMEDIATE" or "EXCLUSIVE".
+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``).
-The current transaction state is exposed through the
-:attr:`Connection.in_transaction` attribute of the connection object.
+You can control which kind of ``BEGIN`` statements :mod:`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``.
+
+You can disable the :mod:`sqlite3` module's implicit transaction management 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``,
+``SAVEPOINT``, and ``RELEASE`` statements in your code.
.. versionchanged:: 3.6
:mod:`sqlite3` used to implicitly commit an open transaction before DDL
More information about the Python-checkins
mailing list