- reorganization

- attrbutes.py splits into attribtes.py and instrumentation.py
- all the various Event subclasses go into events.py modules
- some ideas for orm events
- move *Extension out to deprecated_interfaces

1 files changed, 160 insertions, 0 deletions

diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py
new file mode 100644
index 000000000..55d5932af
--- /dev/null
+++ b/lib/sqlalchemy/events.py
@@ -0,0 +1,160 @@
+"""Core event interfaces."""
+
+from sqlalchemy import event
+
+class DDLEvents(event.Events):
+    """
+    Define create/drop event listers for schema objects.
+    
+    See also:
+
+        :mod:`sqlalchemy.event`
+    
+    """
+    
+    def on_before_create(self, target, connection, **kw):
+        pass
+
+    def on_after_create(self, target, connection, **kw):
+        pass
+
+    def on_before_drop(self, target, connection, **kw):
+        pass
+    
+    def on_after_drop(self, target, connection, **kw):
+        pass
+    
+
+class PoolEvents(event.Events):
+    """Available events for :class:`.Pool`.
+    
+    The methods here define the name of an event as well
+    as the names of members that are passed to listener
+    functions.
+    
+    e.g.::
+    
+        from sqlalchemy import events
+        
+        def my_on_checkout(dbapi_conn, connection_rec, connection_proxy):
+            "handle an on checkout event"
+            
+        events.listen(my_on_checkout, 'on_checkout', Pool)
+
+    """
+    
+    def on_connect(self, dbapi_connection, connection_record):
+        """Called once for each new DB-API connection or Pool's ``creator()``.
+
+        :param dbapi_con:
+          A newly connected raw DB-API connection (not a SQLAlchemy
+          ``Connection`` wrapper).
+
+        :param con_record:
+          The ``_ConnectionRecord`` that persistently manages the connection
+
+        """
+
+    def on_first_connect(self, dbapi_connection, connection_record):
+        """Called exactly once for the first DB-API connection.
+
+        :param dbapi_con:
+          A newly connected raw DB-API connection (not a SQLAlchemy
+          ``Connection`` wrapper).
+
+        :param con_record:
+          The ``_ConnectionRecord`` that persistently manages the connection
+
+        """
+
+    def on_checkout(self, dbapi_connection, connection_record, connection_proxy):
+        """Called when a connection is retrieved from the Pool.
+
+        :param dbapi_con:
+          A raw DB-API connection
+
+        :param con_record:
+          The ``_ConnectionRecord`` that persistently manages the connection
+
+        :param con_proxy:
+          The ``_ConnectionFairy`` which manages the connection for the span of
+          the current checkout.
+
+        If you raise an ``exc.DisconnectionError``, the current
+        connection will be disposed and a fresh connection retrieved.
+        Processing of all checkout listeners will abort and restart
+        using the new connection.
+        """
+
+    def on_checkin(self, dbapi_connection, connection_record):
+        """Called when a connection returns to the pool.
+
+        Note that the connection may be closed, and may be None if the
+        connection has been invalidated.  ``checkin`` will not be called
+        for detached connections.  (They do not return to the pool.)
+
+        :param dbapi_con:
+          A raw DB-API connection
+
+        :param con_record:
+          The ``_ConnectionRecord`` that persistently manages the connection
+
+        """
+
+class EngineEvents(event.Events):
+    """Available events for :class:`.Engine`."""
+    
+    @classmethod
+    def listen(cls, fn, identifier, target):
+        from sqlalchemy.engine.base import Connection, \
+            _listener_connection_cls
+        if target.Connection is Connection:
+            target.Connection = _listener_connection_cls(
+                                        Connection, 
+                                        target.dispatch)
+        event.Events.listen(fn, identifier, target)
+
+    def on_before_execute(self, conn, clauseelement, multiparams, params):
+        """Intercept high level execute() events."""
+
+    def on_after_execute(self, conn, clauseelement, multiparams, params, result):
+        """Intercept high level execute() events."""
+        
+    def on_before_cursor_execute(self, conn, cursor, statement, 
+                        parameters, context, executemany):
+        """Intercept low-level cursor execute() events."""
+
+    def on_after_cursor_execute(self, conn, cursor, statement, 
+                        parameters, context, executemany):
+        """Intercept low-level cursor execute() events."""
+
+    def on_begin(self, conn):
+        """Intercept begin() events."""
+        
+    def on_rollback(self, conn):
+        """Intercept rollback() events."""
+        
+    def on_commit(self, conn):
+        """Intercept commit() events."""
+        
+    def on_savepoint(self, conn, name=None):
+        """Intercept savepoint() events."""
+        
+    def on_rollback_savepoint(self, conn, name, context):
+        """Intercept rollback_savepoint() events."""
+        
+    def on_release_savepoint(self, conn, name, context):
+        """Intercept release_savepoint() events."""
+        
+    def on_begin_twophase(self, conn, xid):
+        """Intercept begin_twophase() events."""
+        
+    def on_prepare_twophase(self, conn, xid):
+        """Intercept prepare_twophase() events."""
+        
+    def on_rollback_twophase(self, conn, xid, is_prepared):
+        """Intercept rollback_twophase() events."""
+        
+    def on_commit_twophase(self, conn, xid, is_prepared):
+        """Intercept commit_twophase() events."""
+