[Zope3-checkins] SVN: Zope3/trunk/src/zope/event/ Added new basic event system.

[Jim Fulton]

Log message for revision 24841:
Added new basic event system.



-=-
Added: Zope3/trunk/src/zope/event/README.txt
===================================================================
--- Zope3/trunk/src/zope/event/README.txt	2004-05-20 01:08:48 UTC (rev 24840)
+++ Zope3/trunk/src/zope/event/README.txt	2004-05-20 15:01:27 UTC (rev 24841)
@@ -0,0 +1,73 @@
+Events
+======
+
+This package provides a simple event system on which
+application-specific event systems can be built.
+
+Application code can generate events without be concerned about the
+event-processing frameworks that might handle the events.
+
+Events are objects that represent something happening in a system.
+They are used to extend processing by providing processing plug
+points. 
+
+The package has a list of subscribers.  Application code can manage
+subscriptiosn by manipulating this list.  For the examples here, we'll
+save the current contents away and empty the list. We'll restore the
+contents when we're done with out examples.
+
+  >>> import zope.event
+  >>> old_subscribers = zope.event.subscribers[:]
+  >>> del zope.event.subscribers[:]
+
+The package provides a `notify` function, which is used to
+notify subscribers that something has happened:
+
+  >>> class MyEvent:
+  ...     pass
+
+  >>> event = MyEvent()
+  >>> zope.event.notify(event)
+
+The notify function is caled with a single object, which we call an
+event.  Any object will do:
+
+  >>> zope.event.notify(None)
+  >>> zope.event.notify(42)
+
+An extremely trivial subscription mechanism is provided. Subscribers
+are simply callback functions:
+
+  >>> def f(event):
+  ...     print 'got:', event
+
+that are put into the subscriptions list:
+
+  >>> zope.event.subscribers.append(f)
+
+  >>> zope.event.notify(42)
+  got: 42
+
+  >>> def g(event):
+  ...     print 'also got:', event
+
+  >>> zope.event.subscribers.append(g)
+
+  >>> zope.event.notify(42)
+  got: 42
+  also got: 42
+
+To unsubscribe, simply remove a subscriber from the list:
+
+  >>> zope.event.subscribers.remove(f)
+  >>> zope.event.notify(42)
+  also got: 42
+
+Generally, application framworks will provide more sophisticated
+subscription mechanisms that build on this simple mechanism. The
+frameworks will install subscribers that then dispatch to other
+subscribers based on event types or data.
+
+We're done, so we'll restoe the subscribers:
+
+  >>> zope.event.subscribers[:] = old_subscribers


Property changes on: Zope3/trunk/src/zope/event/README.txt
___________________________________________________________________
Name: svn:eol-style
   + native

Added: Zope3/trunk/src/zope/event/__init__.py
===================================================================
--- Zope3/trunk/src/zope/event/__init__.py	2004-05-20 01:08:48 UTC (rev 24840)
+++ Zope3/trunk/src/zope/event/__init__.py	2004-05-20 15:01:27 UTC (rev 24841)
@@ -0,0 +1,23 @@
+##############################################################################
+#
+# Copyright (c) 2004 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""base event system implementation
+
+$Id$
+"""
+
+subscribers = []
+
+def notify(event):
+    for subscriber in subscribers:
+        subscriber(event)


Property changes on: Zope3/trunk/src/zope/event/__init__.py
___________________________________________________________________
Name: svn:keywords
   + Id
Name: svn:eol-style
   + native

Added: Zope3/trunk/src/zope/event/tests.py
===================================================================
--- Zope3/trunk/src/zope/event/tests.py	2004-05-20 01:08:48 UTC (rev 24840)
+++ Zope3/trunk/src/zope/event/tests.py	2004-05-20 15:01:27 UTC (rev 24841)
@@ -0,0 +1,52 @@
+##############################################################################
+#
+# Copyright (c) 2004 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Test the event system
+
+$Id$
+"""
+
+import os, doctest, new, unittest
+
+def DocFileSuite(*paths):
+    """Utility to create doc tests from readme files
+
+    Eventually, this, or something like it, will be part of doctest
+    """
+    # It's not entirely obvious how to connection this single string
+    # with unittest.  For now, re-use the _utest() function that comes
+    # standard with doctest in Python 2.3.  One problem is that the
+    # error indicator doesn't point to the line of the doctest file
+    # that failed.
+    t = doctest.Tester(globs={'__name__': '__main__'})
+    suite = unittest.TestSuite()
+    dir = os.path.split(__file__)[0]
+    for path in paths:
+        path = os.path.join(dir, path)
+        source = open(path).read()
+        def runit(path=path, source=source):
+            doctest._utest(t, path, source, path, 0)
+        runit = new.function(runit.func_code, runit.func_globals, path,
+                             runit.func_defaults, runit.func_closure)
+        f = unittest.FunctionTestCase(runit,
+                                      description="doctest from %s" % path)
+        suite.addTest(f)
+    return suite
+
+def test_suite():
+    return unittest.TestSuite((
+        DocFileSuite('README.txt'),
+        ))
+
+if __name__ == '__main__':
+    unittest.main(defaultTest='test_suite')


Property changes on: Zope3/trunk/src/zope/event/tests.py
___________________________________________________________________
Name: svn:keywords
   + Id
Name: svn:eol-style
   + native