Merge branch 'dev' into feature/dev-indexes

docs/guide/index.rst

@@ -11,3 +11,4 @@ User Guide
    document-instances
    querying
    gridfs
+   signals

docs/guide/signals.rst

@@ -0,0 +1,49 @@
+.. _signals:
+
+Signals
+=======
+
+.. versionadded:: 0.5
+
+Signal support is provided by the excellent `blinker`_ library and
+will gracefully fall back if it is not available.
+
+
+The following document signals exist in MongoEngine and are pretty self explaintary:
+
+  * `mongoengine.signals.pre_init`
+  * `mongoengine.signals.post_init`
+  * `mongoengine.signals.pre_save`
+  * `mongoengine.signals.post_save`
+  * `mongoengine.signals.pre_delete`
+  * `mongoengine.signals.post_delete`
+
+Example usage::
+
+    from mongoengine import *
+    from mongoengine import signals
+
+    class Author(Document):
+        name = StringField()
+
+        def __unicode__(self):
+            return self.name
+
+        @classmethod
+        def pre_save(cls, instance, **kwargs):
+            logging.debug("Pre Save: %s" % instance.name)
+
+        @classmethod
+        def post_save(cls, instance, **kwargs):
+            logging.debug("Post Save: %s" % instance.name)
+            if 'created' in kwargs:
+                if kwargs['created']:
+                    logging.debug("Created")
+                else:
+                    logging.debug("Updated")
+        
+        signals.pre_save.connect(Author.pre_save)
+        signals.post_save.connect(Author.post_save)
+
+
+.. _blinker: http://pypi.python.org/pypi/blinker