Make the notify function return its event argument.

This facilitates testing and higher-level APIs such as those found in
zope.lifecycleevent. It was proposed in zopefoundation/zope.lifecycleevent#11.

CHANGES.rst

@@ -9,6 +9,10 @@
 
 - Drop support for Python 3.3.
 
+- Make the ``notify`` function return its event argument. This
+  facilitates testing and higher-level APIs such as those found in
+  `zope.lifecycleevent <https://github.com/zopefoundation/zope.lifecycleevent/issues/11>`_.
+
 
 4.2.0 (2016-02-17)
 ==================

src/zope/event/__init__.py

@@ -30,3 +30,4 @@ def notify(event):
     """
     for subscriber in subscribers:
         subscriber(event)
+    return event

src/zope/event/classhandler.py

@@ -34,7 +34,7 @@
 new-style event classes are supported, and then by order of registry.
 
     >>> import zope.event
-    >>> zope.event.notify(MySubEvent())
+    >>> _ = zope.event.notify(MySubEvent())
     handler3 MySubEvent
     handler1 MySubEvent
     handler2 MySubEvent

src/zope/event/tests.py

@@ -29,7 +29,7 @@ def tearDown(self):
 
     def _callFUT(self, event):
         from zope.event import notify
-        notify(event)
+        return notify(event)
 
     def test_empty(self):
         event = object()
@@ -43,6 +43,10 @@ def test_not_empty(self):
         self._callFUT(event)
         self.assertEqual(dummy, [event])
 
+    def test_returns_argument(self):
+        result = self._callFUT(self)
+        self.assertIs(result, self)
+
 def setUpClassHandlers(test):
     import zope.event
     test.globs['old_subs'] = zope.event.subscribers