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()