[SQL-CVS] r2785 - in SQLObject/branches/0.9: docs sqlobject

[<sub...@co...>]

Author: phd
Date: 2007-07-23 07:55:10 -0600 (Mon, 23 Jul 2007)
New Revision: 2785

Modified:
   SQLObject/branches/0.9/docs/SQLObject.txt
   SQLObject/branches/0.9/sqlobject/events.py
   SQLObject/branches/0.9/sqlobject/main.py
Log:
Added events (signal) docs created by Andy Grover <an...@ba...>.


Modified: SQLObject/branches/0.9/docs/SQLObject.txt
===================================================================
--- SQLObject/branches/0.9/docs/SQLObject.txt	2007-07-23 13:54:13 UTC (rev 2784)
+++ SQLObject/branches/0.9/docs/SQLObject.txt	2007-07-23 13:55:10 UTC (rev 2785)
@@ -1810,6 +1810,38 @@
 .. _pymssql: http://pymssql.sourceforge.net/
 .. _adodbapi: http://adodbapi.sourceforge.net/
 
+Events (signals)
+================
+
+Signals are a mechanism to be notified when data or schema changes happen
+through SQLObject. This may be useful for doing custom data validation,
+logging changes, setting default attributes, etc. Some of what signals can
+do is also possible by overriding methods, but signals may provide
+a cleaner way, especially across classes not related by inheritance.
+
+Example::
+
+   from sqlobject.events import listen, RowUpdateSignal, RowCreatedSignal
+   from model import Users
+
+   def update_listener(instance, kwargs):
+       """keep "last_updated" field current"""
+       import datetime
+       # BAD method 1, causes infinite recursion?
+       # instance should be read-only
+       instance.last_updated = datetime.datetime.now()
+       # GOOD method 2
+       kwargs['last_updated'] = datetime.datetime.now()
+
+   def created_listener(kwargs, post_funcs):
+       """"email me when new users added"""
+       # email() implementation left as an exercise for the reader
+       msg = "%s just was just added to the database!" % kwargs['name']
+       email(msg)
+
+   listen(update_listener, Users, RowUpdateSignal)
+   listen(created_listener, Users, RowCreatedSignal)
+
 Exported Symbols
 ================
 

Modified: SQLObject/branches/0.9/sqlobject/events.py
===================================================================
--- SQLObject/branches/0.9/sqlobject/events.py	2007-07-23 13:54:13 UTC (rev 2784)
+++ SQLObject/branches/0.9/sqlobject/events.py	2007-07-23 13:55:10 UTC (rev 2785)
@@ -107,7 +107,7 @@
     @@: Should this allow ``instance`` to be a primary key, so that a
     row can be deleted without first fetching it?
     """
-    
+
 class RowUpdateSignal(Signal):
     """
     Called when an instance is updated through a call to ``.set()``

Modified: SQLObject/branches/0.9/sqlobject/main.py
===================================================================
--- SQLObject/branches/0.9/sqlobject/main.py	2007-07-23 13:54:13 UTC (rev 2784)
+++ SQLObject/branches/0.9/sqlobject/main.py	2007-07-23 13:55:10 UTC (rev 2785)
@@ -1275,7 +1275,7 @@
         cache.created(id, self.__class__, self)
         self._init(id)
         post_funcs = []
-        kw = dict([('class',self.__class__),('id',id)])
+        kw = dict([('class', self.__class__), ('id', id)])
         self.sqlmeta.send(events.RowCreatedSignal, kw, post_funcs)