usage docstring for pool listener

diff --git a/lib/sqlalchemy/interfaces.py b/lib/sqlalchemy/interfaces.py
index 959989662d8115b871f1dc9aa54e0c4a75ecc419..ae92dc50d0d7c742191659184dac4c166abf62cb 100644 (file)
--- a/lib/sqlalchemy/interfaces.py
+++ b/lib/sqlalchemy/interfaces.py
@@ -10,6 +10,18 @@
 class PoolListener(object):
     """Hooks into the lifecycle of connections in a ``Pool``.
 
+    Usage::
+    
+        # create a new pool with a listener
+        p = QueuePool(..., listeners=[MyListener()])
+        
+        # add a listener after the fact
+        p.add_listener(MyListener())
+        
+        # usage with create_engine()
+        e = create_engine("url://", ...)
+        e.pool.add_listener(MyListener())
+        
     All of the standard connection [sqlalchemy.pool#Pool] types can
     accept event listeners for key connection lifecycle events:
     creation, pool check-out and check-in.  There are no events fired
@@ -40,6 +52,7 @@ class PoolListener(object):
     internal event queues based on its capabilities.  In terms of
     efficiency and function call overhead, you're much better off only
     providing implementations for the hooks you'll be using.
+    
     """
 
     def connect(self, dbapi_con, con_record):