Docs updates.

12 files changed, 102 insertions, 38 deletions

diff --git a/repoze/bfg/configuration.py b/repoze/bfg/configuration.py
index a3ce9b1e0..13f730d97 100644
--- a/repoze/bfg/configuration.py
+++ b/repoze/bfg/configuration.py
@@ -262,6 +262,22 @@ class Configurator(object):
 
     # API
 
+    def add_subscriber(self, subscriber, iface=None):
+        """ Add an event subscriber for the event stream implied by
+        the supplied ``iface`` interface.  The ``subscriber`` argument
+        represents a callable object; it will be called with a single
+        object ``event`` whenever :mod:`repoze.bfg` emits an event
+        associated with the ``iface``.  Using the default ``iface``
+        value, ``None`` will cause the subscriber to be registered for
+        all event types. See :ref:`events_chapter` for more
+        information about events and subscribers."""
+        if iface is None:
+            iface = (Interface,)
+        if not isinstance(iface, (tuple, list)):
+            iface = (iface,)
+        self.registry.registerHandler(subscriber, iface)
+        return subscriber
+
     def make_wsgi_app(self, manager=manager, getSiteManager=getSiteManager):
         """ Returns a :mod:`repoze.bfg` WSGI application representing
         the current configuration state."""
@@ -471,11 +487,19 @@ class Configurator(object):
             self.registry.registerUtility(mapper, IRoutesMapper)
         mapper.connect(path, name, factory, predicates=predicates)
 
-    def scan(self, package, _info=u'', martian=martian):
+    def scan(self, package=None, _info=u'', martian=martian):
         """ Scan a Python package and any of its subpackages for
-        configuration decorators such as ``@bfg_view``.  Any decorator
-        found will influence the current configuration state."""
+        objects marked with configuration decorators such as
+        ``@bfg_view``.  Any decorated object found will influence the
+        current configuration state.  See
+
+        The ``package`` argument should be a reference to a Python
+        package or module object.  If ``package`` is ``None``, the
+        package of the *caller* is used.
+        """
         # martian overrideable only for unit tests
+        if package is None:
+            package = caller_package()
         multi_grokker = BFGMultiGrokker()
         multi_grokker.register(BFGViewGrokker())
         module_grokker = martian.ModuleGrokker(grokker=multi_grokker)
@@ -739,8 +763,7 @@ def rendered_response(renderer, response, view, context, request,
     reg = getattr(request, 'registry', None)
     if reg is not None:
         # be kind to old unit tests
-        response_factory = reg.queryUtility(IResponseFactory,
-                                            default=Response)
+        response_factory = reg.queryUtility(IResponseFactory, default=Response)
     response = response_factory(result)
     if request is not None: # in tests, it may be None
         attrs = request.__dict__
diff --git a/repoze/bfg/includes/configure.zcml b/repoze/bfg/includes/configure.zcml
index db369dd2d..ffabca9a3 100644
--- a/repoze/bfg/includes/configure.zcml
+++ b/repoze/bfg/includes/configure.zcml
@@ -6,24 +6,4 @@
 
   <include file="meta.zcml" />
 
-  <renderer
-     factory="repoze.bfg.chameleon_zpt.renderer_factory"
-     name=".pt"
-     />
-
-  <renderer
-     factory="repoze.bfg.chameleon_text.renderer_factory"
-     name=".txt"
-     />
-
-  <renderer
-     factory="repoze.bfg.renderers.json_renderer_factory"
-     name="json"
-     />
-
-  <renderer
-     factory="repoze.bfg.renderers.string_renderer_factory"
-     name="string"
-     />
-
 </configure>
diff --git a/repoze/bfg/log.py b/repoze/bfg/log.py
index a9957e550..b8762e6e2 100644
--- a/repoze/bfg/log.py
+++ b/repoze/bfg/log.py
@@ -1,7 +1,7 @@
 import logging
 
-def make_stream_logger(name, stream, levelname='DEBUG',
-                       fmt='%(asctime)s %(message)s'):
+def make_stream_logger(
+    name, stream, levelname='DEBUG', fmt='%(asctime)s %(message)s'):
     """ Return an object which implements
     ``repoze.bfg.interfaces.IDebugLogger`` (ie. a Python PEP 282 logger
     instance) with the name ``name`` using the stream (or open
diff --git a/repoze/bfg/paster.py b/repoze/bfg/paster.py
index e57d17c1b..d5b03cf38 100644
--- a/repoze/bfg/paster.py
+++ b/repoze/bfg/paster.py
@@ -10,9 +10,9 @@ from paste.util.template import paste_script_template_renderer
 from repoze.bfg.scripting import get_root
 
 try:
-    from IPython.Shell import IPShell
+    from IPython.Shell import IPShell # pragma: no cover
 except ImportError:
-    IPShell = None
+    IPShell = None # pragma: no cover
 
 
 class StarterProjectTemplate(Template):
diff --git a/repoze/bfg/renderers.py b/repoze/bfg/renderers.py
index 2a42ef901..be04e6578 100644
--- a/repoze/bfg/renderers.py
+++ b/repoze/bfg/renderers.py
@@ -4,8 +4,8 @@ import pkg_resources
 from repoze.bfg.interfaces import ITemplateRenderer
 
 from repoze.bfg.compat import json
-from repoze.bfg.settings import get_settings
 from repoze.bfg.path import caller_package
+from repoze.bfg.settings import get_settings
 from repoze.bfg.threadlocal import get_current_registry
 
 # concrete renderer factory implementations
diff --git a/repoze/bfg/request.py b/repoze/bfg/request.py
index 131c786ca..a7f4f32ba 100644
--- a/repoze/bfg/request.py
+++ b/repoze/bfg/request.py
@@ -87,6 +87,8 @@ def add_global_response_headers(request, headerlist):
 
 from repoze.bfg.threadlocal import get_current_request as get_request # b/c
 
+get_request # prevent PyFlakes complaints
+
 deprecated('get_request',
            'As of repoze.bfg 1.0, any import of get_request from'
            '``repoze.bfg.request`` is '
diff --git a/repoze/bfg/router.py b/repoze/bfg/router.py
index 872b5a134..a68ce3653 100644
--- a/repoze/bfg/router.py
+++ b/repoze/bfg/router.py
@@ -26,7 +26,7 @@ from repoze.bfg.traversal import ModelGraphTraverser
 from repoze.bfg.view import default_forbidden_view
 from repoze.bfg.view import default_notfound_view
 
-make_app = make_app # prevent pyflakes from complaining
+make_app # prevent pyflakes from complaining
 
 class Router(object):
     """ The main repoze.bfg WSGI application. """
diff --git a/repoze/bfg/security.py b/repoze/bfg/security.py
index a7a5d5f35..0366107c7 100644
--- a/repoze/bfg/security.py
+++ b/repoze/bfg/security.py
@@ -6,11 +6,11 @@ from repoze.bfg.interfaces import IAuthenticationPolicy
 from repoze.bfg.interfaces import IAuthorizationPolicy
 from repoze.bfg.interfaces import ISecuredView
 
-# b/c import
-from repoze.bfg.exceptions import Forbidden as Unauthorized
-
+from repoze.bfg.exceptions import Forbidden as Unauthorized # b/c import
 from repoze.bfg.threadlocal import get_current_registry
 
+Unauthorized # prevent PyFlakes from complaining
+
 deprecated('Unauthorized',
     "('from repoze.bfg.security import Unauthorized' was  "
     "deprecated as of repoze.bfg 1.1; instead use 'from "
diff --git a/repoze/bfg/testing.py b/repoze/bfg/testing.py
index f12f5b110..4a4acf98b 100644
--- a/repoze/bfg/testing.py
+++ b/repoze/bfg/testing.py
@@ -13,6 +13,8 @@ from repoze.bfg.threadlocal import manager
 from repoze.bfg.threadlocal import get_current_registry
 from repoze.bfg.zcml import zcml_configure # API
 
+zcml_configure # prevent pyflakes from complaining
+
 _marker = object()
 
 def registerDummySecurityPolicy(userid=None, groupids=(), permissive=True):
diff --git a/repoze/bfg/tests/test_configuration.py b/repoze/bfg/tests/test_configuration.py
index c16d738f5..549663f2f 100644
--- a/repoze/bfg/tests/test_configuration.py
+++ b/repoze/bfg/tests/test_configuration.py
@@ -109,8 +109,6 @@ class ConfiguratorTests(unittest.TestCase):
         self.failUnless(registry.queryUtility(IFixture)) # only in c.zcml
 
     def test_ctor_noreg_zcml_file_routes_in_config(self):
-        from repoze.bfg.interfaces import ISettings
-        from repoze.bfg.interfaces import IRootFactory
         from repoze.bfg.interfaces import IRoutesMapper
         config = self._makeOne(
             zcml_file='repoze.bfg.tests.routesapp:configure.zcml')
@@ -158,6 +156,64 @@ class ConfiguratorTests(unittest.TestCase):
         self.assertEqual(config.registry.getUtility(IRendererFactory, 'yeah'),
                          renderer)
 
+    def test_add_subscriber_defaults(self):
+        from zope.interface import implements
+        from zope.interface import Interface
+        class IEvent(Interface):
+            pass
+        class Event:
+            implements(IEvent)
+        L = []
+        def subscriber(event):
+            L.append(event)
+        config = self._makeOne()
+        config.add_subscriber(subscriber)
+        event = Event()
+        config.registry.notify(event)
+        self.assertEqual(len(L), 1)
+        self.assertEqual(L[0], event)
+        config.registry.notify(object())
+        self.assertEqual(len(L), 2)
+
+    def test_add_subscriber_iface_specified(self):
+        from zope.interface import implements
+        from zope.interface import Interface
+        class IEvent(Interface):
+            pass
+        class Event:
+            implements(IEvent)
+        L = []
+        def subscriber(event):
+            L.append(event)
+        config = self._makeOne()
+        config.add_subscriber(subscriber, IEvent)
+        event = Event()
+        config.registry.notify(event)
+        self.assertEqual(len(L), 1)
+        self.assertEqual(L[0], event)
+        config.registry.notify(object())
+        self.assertEqual(len(L), 1)
+
+    def test_add_object_event_subscriber(self):
+        from zope.interface import implements
+        from zope.interface import Interface
+        class IEvent(Interface):
+            pass
+        class Event:
+            object = 'foo'
+            implements(IEvent)
+        event = Event()
+        L = []
+        def subscriber(object, event):
+            L.append(event)
+        config = self._makeOne()
+        config.add_subscriber(subscriber, (Interface, IEvent))
+        config.registry.subscribers((event.object, event), None)
+        self.assertEqual(len(L), 1)
+        self.assertEqual(L[0], event)
+        config.registry.subscribers((event.object, IDummy), None)
+        self.assertEqual(len(L), 1)
+        
     def test_make_wsgi_app(self):
         from repoze.bfg.threadlocal import get_current_registry
         from repoze.bfg.router import Router
@@ -220,7 +276,6 @@ class ConfiguratorTests(unittest.TestCase):
         registry = config.load_zcml(
             'repoze.bfg.tests.fixtureapp:configure.zcml',
             lock=dummylock)
-        from repoze.bfg.tests.fixtureapp.models import IFixture
         self.assertEqual(dummylock.acquired, True)
         self.assertEqual(dummylock.released, True)
 
diff --git a/repoze/bfg/url.py b/repoze/bfg/url.py
index 51e1b109e..d94cd429c 100644
--- a/repoze/bfg/url.py
+++ b/repoze/bfg/url.py
@@ -267,7 +267,7 @@ def static_url(path, request, **kw):
         # if it's not a package:relative/name and it's not an
         # /absolute/path it's a relative/path; this means its relative
         # to the package in which the caller's module is defined.
-        package = caller_package(level=2)
+        package = caller_package()
         path = '%s:%s' % (package.__name__, path)
 
     try:
diff --git a/repoze/bfg/view.py b/repoze/bfg/view.py
index c4542dc79..cfdf61522 100644
--- a/repoze/bfg/view.py
+++ b/repoze/bfg/view.py
@@ -32,6 +32,8 @@ from repoze.bfg.static import PackageURLParser
 # b/c imports
 from repoze.bfg.security import view_execution_permitted
 
+view_execution_permitted # prevent PyFlakes from complaining
+
 deprecated('view_execution_permitted',
     "('from repoze.bfg.view import view_execution_permitted' was  "
     "deprecated as of repoze.bfg 1.0; instead use 'from "