8000 Improve sqlite3 documentation of the new autocommit attribute by geryogam · Pull Request #99435 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

Improve sqlite3 documentation of the new autocommit attribute #99435

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 9 commits into from
Closed

Improve sqlite3 documentation of the new autocommit attribute #99435

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
bb30103
Remove an unnecessary lambda in tests
geryogam Nov 13, 2022
261f21b
Clarify that implicit open or roll back happens in the same method call
geryogam Nov 13, 2022
d864934
Add connect() to the list of implicit-transaction-opening methods
geryogam Nov 21, 2022
8b250c0
Recommend commit() and rollback() in legacy manual commit mode
geryogam Nov 21, 2022
d11dcfb
Clarify PEP-249-compliant vs legacy transaction control
geryogam Nov 21, 2022
3750bf0
Improve wording consistency
geryogam Nov 21, 2022
b9034b1
Remove two ambiguous ‘underlying’
geryogam Nov 13, 2022
55a28c8
Normalize ‘open transaction’
geryogam Nov 13, 2022
6db7b57
Normalize ’transaction control’
geryogam Nov 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Clarify PEP-249-compliant vs legacy transaction control
  • Loading branch information
@geryogam
geryogam committed Nov 22, 2022
commit d11dcfb5eb35c1239ff944051a8c0092b77d3e9a
28 changes: 17 additions & 11 deletions Doc/library/sqlite3.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Legacy (pre-Python 3.12) transaction control.
See :attr:`isolation_level` for more details.

This is currently the default value of :attr:`!autocommit`.
Expand Down Expand Up @@ -2385,8 +2384,8 @@ 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:

* :meth:`Connection.connect`, :meth:`Connection.commit`,
Expand All @@ -2398,16 +2397,23 @@ This means:
* 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.
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.

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.

Expand Down
0