Clarify sqlite3 documentation of PEP 249 compliance for commit modes

[geryogam]

Documentation

The sqlite3 documentation for the new Connection.autocommit attribute introduced in PR #93823 states:

   .. attribute:: autocommit

      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.

        This is the recommended value of :attr:`!autocommit`.

      * ``True``: Use SQLite's `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.
        See :attr:`isolation_level` for more details.

The sentence ‘This attribute controls :pep:249-compliant transaction behaviour.’ is misleading as only the new manual commit mode (autocommit=False) is PEP-249-compliant, since PEP 249 specifies only the manual commit mode.

Likewise, the sentence ‘Pre-Python 3.12 (non-:pep:249-compliant) transaction control.’ is misleading as only the legacy manual commit mode (isolation_level='DEFERRED', isolation_level='EXCLUSIVE', or isolation_level='IMMEDIATE') is non-PEP-249-compliant, since PEP 249 specifies only the manual commit mode.

Linked PRs

• gh-99828: Clarify sqlite3 documentation of PEP 249 compliance for commit modes #99829

[erlend-aasland]

The sentence ‘This attribute controls :pep:249-compliant transaction behaviour.’ is misleading as only the new manual commit mode (autocommit=False) is PEP-249-compliant, since PEP 249 specifies only the manual commit mode.

It is not misleading. PEP-249 says that autocommit is True implies leaving the "autocommitting" to SQLite. That is what we do, and there is nothing "non-PEP-249-compliant" about that.

Likewise, the sentence ‘Pre-Python 3.12 (non-:pep:249-compliant) transaction control.’ is misleading as only the legacy manual commit mode (isolation_level='DEFERRED', isolation_level='EXCLUSIVE', or isolation_level='IMMEDIATE') is non-PEP-249-compliant, since PEP 249 specifies only the manual commit mode.

Ditto. IMO, this is perfectly fine.

AFAICS, there is no need to change those wordings; suggesting to close this issue.

Thanks for your interest in improving the docs!

[geryogam]

Fair enough. Thanks for the discussion.