Add optional Connection.autocommit attribute to PEP 249

pep-0249.txt

@@ -5,7 +5,7 @@ Discussions-To: [email protected]
 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
 =========