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 =========