Add documentation

Author: erlend-aasland

Doc/library/sqlite3.rst

@@ -236,7 +236,7 @@ Module functions and constants
    the preceding space: the column name would simply be "Expiration date".
 
 
-.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])
+.. 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 +255,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 a future Python release.
+
    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 +323,9 @@ Module functions and constants
    .. versionchanged:: 3.10
       Added the ``sqlite3.connect/handle`` auditing event.
 
+   .. versionchanged:: 3.12
+      Added the *autocommit* parameter.
+
 
 .. function:: register_converter(typename, callable)
 
@@ -385,6 +393,25 @@ 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 a future Python
+        release.
+
+      * :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 +1392,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.
+
+In a future Python release, *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 +1510,10 @@ committed:
 
 .. literalinclude:: ../includes/sqlite3/ctx_manager.py
 
+.. note::
+
+   The context manager does not implicitly begin a new transaction.
+
 
 .. rubric:: Footnotes