- recognize that do_rollback() and do_commit() work with a DBAPI connection,

whereas the other do_rollback_twophase(), savepoint etc. work with
:class:`.Connection`.  the context on these are different as twophase/savepoint
are available at the :class:`.Connection` level, whereas commit/rollback are needed
at a lower level as well.  Rename the argument to "dbapi_connection" when the conneciton
is in fact the DBAPI interface.
- start thinking about being able to track "autocommit" vs. "commit", but not sure
we have a need for this yet.
- have Pool call out to a Dialect for all rollback/commit/close operations now.  Pool
no longer calls DBAPI methods directly.  May use this for a workaround for [ticket:2611]
- add a new Pool event reset() to allow the pool's reset of the connection to be intercepted.
- remove methods in Informix dialect which appear to be hardcoding some isolation
settings on new Transaction only; the isolation API should be implemented for Informix.
also removed "flag" for transaction commit/rollback being not available; this should
be based on server/DBAPI version and we will need someone with test access in order
to help determine how this should work

1 files changed, 106 insertions, 20 deletions

diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py
index 66856a00e..0adec7fd3 100644
--- a/lib/sqlalchemy/engine/interfaces.py
+++ b/lib/sqlalchemy/engine/interfaces.py
@@ -402,15 +402,63 @@ class Dialect(object):
 
         raise NotImplementedError()
 
-    def do_begin(self, connection):
-        """Provide an implementation of *connection.begin()*, given a
-        DB-API connection."""
+    def do_begin(self, dbapi_connection):
+        """Provide an implementation of ``connection.begin()``, given a
+        DB-API connection.
+
+        The DBAPI has no dedicated "begin" method and it is expected
+        that transactions are implicit.  This hook is provided for those
+        DBAPIs that might need additional help in this area.
+
+        Note that :meth:`.Dialect.do_begin` is not called unless a
+        :class:`.Transaction` object is in use.  The
+        :meth:`.Dialect.do_autocommit`
+        hook is provided for DBAPIs that need some extra commands emitted
+        after a commit in order to enter the next transaction, when the
+        SQLAlchemy :class:`.Connection` is used in it's default "autocommit"
+        mode.
+
+        :param dbapi_connection: a DBAPI connection, typically
+         proxied within a :class:`.ConnectionFairy`.
+
+         """
 
         raise NotImplementedError()
 
-    def do_rollback(self, connection):
-        """Provide an implementation of *connection.rollback()*, given
-        a DB-API connection."""
+    def do_rollback(self, dbapi_connection):
+        """Provide an implementation of ``connection.rollback()``, given
+        a DB-API connection.
+
+        :param dbapi_connection: a DBAPI connection, typically
+         proxied within a :class:`.ConnectionFairy`.
+
+         """
+
+        raise NotImplementedError()
+
+
+    def do_commit(self, dbapi_connection):
+        """Provide an implementation of ``connection.commit()``, given a
+        DB-API connection.
+
+        :param dbapi_connection: a DBAPI connection, typically
+         proxied within a :class:`.ConnectionFairy`.
+
+        """
+
+        raise NotImplementedError()
+
+    def do_close(self, dbapi_connection):
+        """Provide an implementation of ``connection.close()``, given a DBAPI
+        connection.
+
+        This hook is called by the :class:`.Pool` when a connection has been
+        detached from the pool, or is being returned beyond the normal
+        capacity of the pool.
+
+        .. versionadded:: 0.8
+
+        """
 
         raise NotImplementedError()
 
@@ -424,53 +472,91 @@ class Dialect(object):
 
         raise NotImplementedError()
 
-    def do_commit(self, connection):
-        """Provide an implementation of *connection.commit()*, given a
-        DB-API connection."""
+    def do_savepoint(self, connection, name):
+        """Create a savepoint with the given name.
 
-        raise NotImplementedError()
+        :param connection: a :class:`.Connection`.
+        :param name: savepoint name.
 
-    def do_savepoint(self, connection, name):
-        """Create a savepoint with the given name on a SQLAlchemy
-        connection."""
+        """
 
         raise NotImplementedError()
 
     def do_rollback_to_savepoint(self, connection, name):
-        """Rollback a SQL Alchemy connection to the named savepoint."""
+        """Rollback a connection to the named savepoint.
+
+        :param connection: a :class:`.Connection`.
+        :param name: savepoint name.
+
+        """
 
         raise NotImplementedError()
 
     def do_release_savepoint(self, connection, name):
-        """Release the named savepoint on a SQL Alchemy connection."""
+        """Release the named savepoint on a connection.
+
+        :param connection: a :class:`.Connection`.
+        :param name: savepoint name.
+        """
 
         raise NotImplementedError()
 
     def do_begin_twophase(self, connection, xid):
-        """Begin a two phase transaction on the given connection."""
+        """Begin a two phase transaction on the given connection.
+
+        :param connection: a :class:`.Connection`.
+        :param xid: xid
+
+        """
 
         raise NotImplementedError()
 
     def do_prepare_twophase(self, connection, xid):
-        """Prepare a two phase transaction on the given connection."""
+        """Prepare a two phase transaction on the given connection.
+
+        :param connection: a :class:`.Connection`.
+        :param xid: xid
+
+        """
 
         raise NotImplementedError()
 
     def do_rollback_twophase(self, connection, xid, is_prepared=True,
                             recover=False):
-        """Rollback a two phase transaction on the given connection."""
+        """Rollback a two phase transaction on the given connection.
+
+        :param connection: a :class:`.Connection`.
+        :param xid: xid
+        :param is_prepared: whether or not
+         :meth:`.TwoPhaseTransaction.prepare` was called.
+        :param recover: if the recover flag was passed.
+
+        """
 
         raise NotImplementedError()
 
     def do_commit_twophase(self, connection, xid, is_prepared=True,
                             recover=False):
-        """Commit a two phase transaction on the given connection."""
+        """Commit a two phase transaction on the given connection.
+
+
+        :param connection: a :class:`.Connection`.
+        :param xid: xid
+        :param is_prepared: whether or not
+         :meth:`.TwoPhaseTransaction.prepare` was called.
+        :param recover: if the recover flag was passed.
+
+        """
 
         raise NotImplementedError()
 
     def do_recover_twophase(self, connection):
         """Recover list of uncommited prepared two phase transaction
-        identifiers on the given connection."""
+        identifiers on the given connection.
+
+        :param connection: a :class:`.Connection`.
+
+        """
 
         raise NotImplementedError()