[Checkins] SVN: z3c.saconfig/trunk/s Introduce IEngineCreatedEvent when an engine is freshly created.

[Martijn Faassen]

Log message for revision 89892:
  Introduce IEngineCreatedEvent when an engine is freshly created.
  

Changed:
  U   z3c.saconfig/trunk/setup.py
  U   z3c.saconfig/trunk/src/z3c/saconfig/README.txt
  U   z3c.saconfig/trunk/src/z3c/saconfig/interfaces.py
  U   z3c.saconfig/trunk/src/z3c/saconfig/tests.py
  U   z3c.saconfig/trunk/src/z3c/saconfig/utility.py

-=-
Modified: z3c.saconfig/trunk/setup.py
===================================================================
--- z3c.saconfig/trunk/setup.py	2008-08-15 19:30:34 UTC (rev 89891)
+++ z3c.saconfig/trunk/setup.py	2008-08-15 20:49:08 UTC (rev 89892)
@@ -35,6 +35,7 @@
           'zope.component',
           'zope.hookable',
           'zope.security',
+          'zope.event',
           'zope.configuration',
       ],
       entry_points="""

Modified: z3c.saconfig/trunk/src/z3c/saconfig/README.txt
===================================================================
--- z3c.saconfig/trunk/src/z3c/saconfig/README.txt	2008-08-15 19:30:34 UTC (rev 89891)
+++ z3c.saconfig/trunk/src/z3c/saconfig/README.txt	2008-08-15 20:49:08 UTC (rev 89892)
@@ -140,6 +140,29 @@
   >>> bob.addresses
   []
 
+Events
+======
+
+When a new engine is created by an ``EngineFactory``, an
+``IEngineCreatedEvent`` is fired. This event has an attribute
+``engine`` that contains the engine that was just created::
+
+  >>> from z3c.saconfig.interfaces import IEngineCreatedEvent
+  >>> @component.adapter(IEngineCreatedEvent)
+  ... def createdHandler(event):
+  ...     print "created engine"
+  >>> component.provideHandler(createdHandler)
+  >>> event_engine_factory = EngineFactory(TEST_DSN1)
+  >>> engine = event_engine_factory()
+  created engine
+
+Let's get rid of the event handler again::
+
+  >>> sm = component.getSiteManager()
+  >>> sm.unregisterHandler(None, 
+  ...   required=[IEngineCreatedEvent])
+  True
+
 SiteScopedSession (one database per site)
 =========================================
 

Modified: z3c.saconfig/trunk/src/z3c/saconfig/interfaces.py
===================================================================
--- z3c.saconfig/trunk/src/z3c/saconfig/interfaces.py	2008-08-15 19:30:34 UTC (rev 89891)
+++ z3c.saconfig/trunk/src/z3c/saconfig/interfaces.py	2008-08-15 20:49:08 UTC (rev 89892)
@@ -1,4 +1,4 @@
-from zope.interface import Interface
+from zope.interface import Interface, implements, Attribute
 
 class IScopedSession(Interface):
     """A utility that plugs into SQLAlchemy's scoped session machinery.
@@ -56,3 +56,17 @@
 
         This causes the engine to be recreated on next use.
         """
+
+class IEngineCreatedEvent(Interface):
+    """An SQLAlchemy engine has been created.
+
+    Hook into this event to do setup that can only be performed with
+    an active engine.
+    """
+    engine = Attribute("The engine that was just created.")
+    
+class EngineCreatedEvent(object):
+    implements(IEngineCreatedEvent)
+
+    def __init__(self, engine):
+        self.engine = engine

Modified: z3c.saconfig/trunk/src/z3c/saconfig/tests.py
===================================================================
--- z3c.saconfig/trunk/src/z3c/saconfig/tests.py	2008-08-15 19:30:34 UTC (rev 89891)
+++ z3c.saconfig/trunk/src/z3c/saconfig/tests.py	2008-08-15 20:49:08 UTC (rev 89892)
@@ -22,6 +22,7 @@
 
 from zope import component
 from zope.component import registry
+import zope.component.eventtesting
 
 TEST_TWOPHASE = bool(os.environ.get('TEST_TWOPHASE'))
 TEST_DSN = os.environ.get('TEST_DSN', 'sqlite:///:memory:')
@@ -33,6 +34,8 @@
 def setUpReadMe(test):
     # set up special local component architecture
     setHooks()
+    # set up event handling
+    zope.component.eventtesting.setUp(test)
 
 def tearDownReadMe(test):
     # clean up Zope

Modified: z3c.saconfig/trunk/src/z3c/saconfig/utility.py
===================================================================
--- z3c.saconfig/trunk/src/z3c/saconfig/utility.py	2008-08-15 19:30:34 UTC (rev 89891)
+++ z3c.saconfig/trunk/src/z3c/saconfig/utility.py	2008-08-15 20:49:08 UTC (rev 89892)
@@ -10,9 +10,10 @@
 from zope.interface import implements
 from zope import component
 from zope.sqlalchemy import ZopeTransactionExtension
+from zope.event import notify
 
 from z3c.saconfig.interfaces import (IScopedSession, ISiteScopedSession,
-                                     IEngineFactory)
+                                     IEngineFactory, EngineCreatedEvent)
 
 SA_0_5 = sqlalchemy.__version__ == 'svn' or sqlalchemy.__version__.split('.')[:2] == ['0', '5']
 
@@ -162,7 +163,9 @@
             # need to check, another thread may have got there first
             if self._key not in _ENGINES:
                 args, kw = self.configuration()
-                _ENGINES[self._key] = sqlalchemy.create_engine(*args, **kw)
+                _ENGINES[self._key] = engine = sqlalchemy.create_engine(
+                    *args, **kw)
+                notify(EngineCreatedEvent(engine))
             return _ENGINES[self._key]
         finally:
             _ENGINES_LOCK.release()