From 74e6056162bc14ba2d1ba6702a5d23740cdc6707 Mon Sep 17 00:00:00 2001
From: Marc-Andre Lemburg <mal@egenix.com>
Date: Wed, 16 Nov 2022 19:04:43 +0100
Subject: [PATCH] Add optional Connection.autocommit attribute to PEP 249
 (#2887)

* Add optional Connection.autocommit attribute as discussed on the DB-SIG ML.

Fix the creation date to point to the announcement date of the
DB-API 2.0.

Add years to the acknowledgements.

Minor editorial changes.

* Fix spelling.

* Fix another spelling mistake.
---
 pep-0249.txt | 61 ++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 52 insertions(+), 9 deletions(-)

diff --git a/pep-0249.txt b/pep-0249.txt
index 09eaa4608..629a8ba89 100644
--- a/pep-0249.txt
+++ b/pep-0249.txt
@@ -5,7 +5,7 @@ Discussions-To: db-sig@python.org
 Status: Final
 Type: Informational
 Content-Type: text/x-rst
-Created: 29-Mar-2001
+Created: 12-Apr-1999
 Post-History:
 Replaces: 248
 
@@ -932,6 +932,34 @@ Cursor\ `.lastrowid`_
     *Warning Message:* "DB-API extension cursor.lastrowid used"
 
 
+.. _Connection.autocommit:
+.. _.autocommit:
+
+Connection\ `.autocommit`_
+    Attribute to query and set the autocommit mode of the connection.
+
+    Return ``True`` if the connection is operating in autocommit (non-
+    transactional) mode. Return ``False`` if the connection is
+    operating in manual commit (transactional) mode.
+
+    Setting the attribute to ``True`` or ``False`` adjusts the
+    connection's mode accordingly.
+
+    Changing the setting from ``True`` to ``False`` (disabling
+    autocommit) will have the database leave autocommit mode and start
+    a new transaction. Changing from ``False`` to ``True`` (enabling
+    autocommit) has database dependent semantics with respect to how
+    pending transactions are handled. [12]_
+
+    *Deprecation notice*: Even though several database modules implement
+    both the read and write nature of this attribute, setting the
+    autocommit mode by writing to the attribute is deprecated, since
+    this may result in I/O and related exceptions, making it difficult
+    to implement in an async context. [13]_
+
+    *Warning Message:* "DB-API extension connection.autocommit used"
+
+
 Optional Error Handling Extensions
 ==================================
 
@@ -1232,6 +1260,8 @@ Footnotes
 
         connect(dsn='myhost:MYDB', user='guido', password='234$')
 
+    Also see [13]_ regarding planned future additions to this list.
+
 .. [2] Module implementors should prefer ``numeric``, ``named`` or
     ``pyformat`` over the other formats because these offer more
     clarity and flexibility.
@@ -1241,10 +1271,10 @@ Footnotes
     the method, the interface should throw an exception in case the
     method is used.
 
-    The preferred approach is to not implement the method and thus
-    have Python generate an ``AttributeError`` in case the method is requested. This
-    allows the programmer to check for database capabilities using the
-    standard ``hasattr()`` function.
+    The preferred approach is to not implement the method and thus have
+    Python generate an ``AttributeError`` in case the method is
+    requested. This allows the programmer to check for database
+    capabilities using the standard ``hasattr()`` function.
 
     For some dynamically configured interfaces it may not be
     appropriate to require dynamically making the method
@@ -1309,20 +1339,33 @@ Footnotes
     the time of writing of the DB-API 2.0 in 1999, the warning framework
     in Python did not yet exist.
 
+.. [12] Many database modules implementing the autocommit attribute will
+    automatically commit any pending transaction and then enter
+    autocommit mode. It is generally recommended to explicitly
+    `.commit()`_ or `.rollback()`_ transactions prior to changing the
+    autocommit setting, since this is portable across database modules.
+
+.. [13] In a future revision of the DB-API, we are going to introduce a
+    new method ``.setautocommit(value)``, which will allow setting the
+    autocommit mode, and make ``.autocommit`` a read-only attribute.
+    Additionally, we are considering to add a new standard keyword
+    parameter ``autocommit`` to the Connection constructor. Modules
+    authors are encouraged to add these changes in preparation for this
+    change.
 
 Acknowledgements
 ================
 
 Many thanks go to Andrew Kuchling who converted the Python Database
 API Specification 2.0 from the original HTML format into the PEP
-format.
+format in 2001.
 
-Many thanks to James Henstridge for leading the discussion which led
-to the standardization of the two-phase commit API extensions.
+Many thanks to James Henstridge for leading the discussion which led to
+the standardization of the two-phase commit API extensions in 2008.
 
 Many thanks to Daniele Varrazzo for converting the specification from
 text PEP format to ReST PEP format, which allows linking to various
-parts.
+parts in 2012.
 
 Copyright
 =========