Author: phd
Date: 2007-07-23 07:57:20 -0600 (Mon, 23 Jul 2007)
New Revision: 2786
Modified:
SQLObject/docs/SQLObject.txt
Log:
Added events (signal) docs created by Andy Grover <an...@ba...>.
Modified: SQLObject/docs/SQLObject.txt
===================================================================
--- SQLObject/docs/SQLObject.txt 2007-07-23 13:55:10 UTC (rev 2785)
+++ SQLObject/docs/SQLObject.txt 2007-07-23 13:57:20 UTC (rev 2786)
@@ -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
================
|
