- SchemaItem, SchemaType now descend from common type

SchemaEventTarget, which supplies dispatch
- the dispatch now provides before_parent_attach(),
after_parent_attach(), events which generally bound the _set_parent()
event. [ticket:2037]
- the _on_table_attach mechanism now usually uses the
event dispatch
- fixed class-level event dispatch to propagate to all subclasses, not just
immediate subclasses
- fixed class-level event unpickling to handle more involved
inheritance hierarchies, needed by the new schema event dispatch.
- ForeignKeyConstraint doesn't re-call the column attach event
on ForeignKey objects that are already associated with the correct
Column
- we still need that ImportError on mysqldb CLIENT FLAGS to support
mock DBAPIs

1 files changed, 45 insertions, 6 deletions

diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py
index c1f10977d..8a2776898 100644
--- a/lib/sqlalchemy/events.py
+++ b/lib/sqlalchemy/events.py
@@ -10,12 +10,22 @@ from sqlalchemy import event, exc
 
 class DDLEvents(event.Events):
     """
-    Define create/drop event listers for schema objects.
-
-    These events currently apply to :class:`.Table`
-    and :class:`.MetaData` objects as targets.
-
-    e.g.::
+    Define event listeners for schema objects,
+    that is, :class:`.SchemaItem` and :class:`.SchemaEvent`
+    subclasses, including :class:`.MetaData`, :class:`.Table`,
+    :class:`.Column`.
+    
+    :class:`.MetaData` and :class:`.Table` support events
+    specifically regarding when CREATE and DROP
+    DDL is emitted to the database.  
+    
+    Attachment events are also provided to customize
+    behavior whenever a child schema element is associated
+    with a parent, such as, when a :class:`.Column` is associated
+    with its :class:`.Table`, when a :class:`.ForeignKeyConstraint`
+    is associated with a :class:`.Table`, etc.
+
+    Example using the ``after_create`` event::
 
         from sqlalchemy import event
         from sqlalchemy import Table, Column, Metadata, Integer
@@ -117,6 +127,35 @@ class DDLEvents(event.Events):
 
         """
 
+    def before_parent_attach(self, target, parent):
+        """Called before a :class:`.SchemaItem` is associated with 
+        a parent :class:`.SchemaItem`.
+        
+        """
+
+    def after_parent_attach(self, target, parent):
+        """Called after a :class:`.SchemaItem` is associated with 
+        a parent :class:`.SchemaItem`.
+        
+        """
+
+class SchemaEventTarget(object):
+    """Base class for elements that are the targets of :class:`.DDLEvents` events.
+    
+    This includes :class:`.SchemaItem` as well as :class:`.SchemaType`.
+    
+    """
+    dispatch = event.dispatcher(DDLEvents)
+
+    def _set_parent(self, parent):
+        """Associate with this SchemaEvent's parent object."""
+
+        raise NotImplementedError()
+
+    def _set_parent_with_dispatch(self, parent):
+        self.dispatch.before_parent_attach(self, parent) 
+        self._set_parent(parent) 
+        self.dispatch.after_parent_attach(self, parent) 
 
 class PoolEvents(event.Events):
     """Available events for :class:`.Pool`.