document ConnectionProxy

diff --git a/doc/build/reference/sqlalchemy/interfaces.rst b/doc/build/reference/sqlalchemy/interfaces.rst
index 6062b65778eeac26457d06f61c9cad6d1da65bbc..c629c3250ce1c4c58856f6277e34b69ff533f387 100644 (file)
--- a/doc/build/reference/sqlalchemy/interfaces.rst
+++ b/doc/build/reference/sqlalchemy/interfaces.rst
@@ -3,4 +3,4 @@ Interfaces
 
 .. automodule:: sqlalchemy.interfaces
    :members:
-
+   :undoc-members:

diff --git a/lib/sqlalchemy/interfaces.py b/lib/sqlalchemy/interfaces.py
index f9c21d2468f397fc24f2760bc10ab1165717fc28..dfceffe4451a0440d6d6b89a9a8c3adce9e4fb7f 100644 (file)
--- a/lib/sqlalchemy/interfaces.py
+++ b/lib/sqlalchemy/interfaces.py
@@ -108,20 +108,37 @@ class PoolListener(object):
 class ConnectionProxy(object):
     """Allows interception of statement execution by Connections.
     
-    Subclass ``ConnectionProxy``, overriding either or both of 
-    ``execute()`` and ``cursor_execute()``  The default behavior is provided,
-    which is to call the given executor function with the remaining 
-    arguments.  The proxy is then connected to an engine via
-    ``create_engine(url, proxy=MyProxy())`` where ``MyProxy`` is
-    the user-defined ``ConnectionProxy`` class.
+    Either or both of the ``execute()`` and ``cursor_execute()``
+    may be implemented to intercept compiled statement and
+    cursor level executions, e.g.::
+    
+        class MyProxy(ConnectionProxy):
+            def execute(self, conn, execute, clauseelement, *multiparams, **params):
+                print "compiled statement:", clauseelement
+                return execute(clauseelement, *multiparams, **params)
+                
+            def cursor_execute(self, execute, cursor, statement, parameters, context, executemany):
+                print "raw statement:", statement
+                return execute(cursor, statement, parameters, context)
+
+    The ``execute`` argument is a function that will fulfill the default
+    execution behavior for the operation.  The signature illustrated
+    in the example should be used.
+    
+    The proxy is installed into an :class:`~sqlalchemy.engine.Engine` via
+    the ``proxy`` argument::
+    
+        e = create_engine('someurl://', proxy=MyProxy())
     
     """
     def execute(self, conn, execute, clauseelement, *multiparams, **params):
-        """"""
+        """Intercept high level execute() events."""
+        
         return execute(clauseelement, *multiparams, **params)
 
     def cursor_execute(self, execute, cursor, statement, parameters, context, executemany):
-        """"""
+        """Intercept low-level cursor execute() events."""
+        
         return execute(cursor, statement, parameters, context)