From f077653f208f6f7c89c78c87c2abb0ea7031dbc0 Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@agendaless.com>
Date: Wed, 28 Jul 2010 03:00:58 +0000
Subject: - A ``repoze.bfg.events.subscriber`` decorator was added.  This  
 decorator decorates module-scope functions, which are then treated   as event
 listeners after a scan() is performed.  See the Events   narrative
 documentation chapter and the ``repoze.bfg.events`` module   documentation
 for more information.

---
 repoze/bfg/events.py | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

(limited to 'repoze/bfg/events.py')

diff --git a/repoze/bfg/events.py b/repoze/bfg/events.py
index bdccfba9c..22822eeeb 100644
--- a/repoze/bfg/events.py
+++ b/repoze/bfg/events.py
@@ -1,3 +1,5 @@
+import venusian
+
 from zope.interface import implements
 
 from repoze.bfg.interfaces import IAfterTraversal
@@ -5,6 +7,68 @@ from repoze.bfg.interfaces import INewRequest
 from repoze.bfg.interfaces import INewResponse
 from repoze.bfg.interfaces import IWSGIApplicationCreatedEvent
 
+class subscriber(object):
+    """ Decorator activated via a :term:`scan` which treats the
+    function being decorated as an event subscriber for the set of
+    interfaces passed as ``*ifaces`` to the decorator constructor.
+
+    For example:
+
+    .. code-block:: python
+    
+       from repoze.bfg.interfaces import INewRequest
+       from repoze.bfg.events import subscriber
+
+       @subscriber(INewRequest)
+       def mysubscriber(event):
+           event.request.foo = 1
+
+    More than one event type can be passed as a construtor argument:
+        
+    .. code-block:: python
+    
+       from repoze.bfg.interfaces import INewRequest
+       from repoze.bfg.events import subscriber
+
+       @subscriber(INewRequest, INewResponse)
+       def mysubscriber(event):
+           print event
+
+    When the ``subscriber`` decorator is used without passing an arguments,
+    the function it decorates is called for every event sent:
+
+    .. code-block:: python
+    
+       from repoze.bfg.interfaces import INewRequest
+       from repoze.bfg.events import subscriber
+
+       @subscriber()
+       def mysubscriber(event):
+           print event
+
+    This method will have no effect until a :term:`scan` is performed
+    against the package or module which contains it, ala:
+
+    .. code-block:: python
+    
+       from repoze.bfg.configuration import Configurator
+       config = Configurator()
+       config.scan('somepackage_containing_subscribers')
+
+    """
+    venusian = venusian # for unit testing
+
+    def __init__(self, *ifaces):
+        self.ifaces = ifaces
+
+    def register(self, scanner, name, wrapped):
+        config = scanner.config
+        config.add_subscriber(wrapped, self.ifaces)
+
+    def __call__(self, wrapped):
+        self.venusian.attach(wrapped, self.register, category='bfg')
+        return wrapped
+
 class NewRequest(object):
     """ An instance of this class is emitted as an :term:`event`
     whenever :mod:`repoze.bfg` begins to process a new request.  The
-- 
cgit v1.2.3