Features

--------

- The ``Configurator`` object now has two new methods: ``begin`` and
  ``end``.  The ``begin`` method is meant to be called before any
  "configuration" begins (e.g. before ``add_view``, et. al are
  called).  The ``end`` method is meant to be called after all
  "configuration" is complete.

  Previously, before there was imperative configuration at all (1.1
  and prior), configuration begin and end was invariably implied by
  the process of loading a ZCML file.  When a ZCML load happened, the
  threadlocal data structure containing the request and registry was
  modified before the load, and torn down after the load, making sure
  that all framework code that needed ``get_current_registry`` for the
  duration of the ZCML load was satisfied.

  Some API methods called during imperative configuration, (such as
  ``Configurator.add_view`` when a renderer is involved) end up for
  historical reasons calling ``get_current_registry``.  However, in
  1.2a5 and below, the Configurator supplied no functionality that
  allowed people to make sure that ``get_current_registry`` returned
  the registry implied by the configurator being used.  ``begin`` now
  serves this purpose.  Inversely, ``end`` pops the thread local
  stack, undoing the actions of ``begin``.

  We make this boundary explicit to reduce the potential for confusion
  when the configurator is used in different circumstances (e.g. in
  unit tests and app code vs. just in initial app setup).

  Existing code written for 1.2a1-1.2a5 which does not call ``begin``
  or ``end`` continues to work in the same manner it did before.  It
  is however suggested that this code be changed to call ``begin`` and
  ``end`` to reduce the potential for confusion in the future.

- All ``paster`` templates which generate an application skeleton now
  make use of the new ``begin`` and ``end`` methods of the
  Configurator they use in their respective copies of ``run.py`` and
  ``tests.py``.

Documentation
-------------

- All documentation that makes use of a ``Configurator`` object to do
  application setup and test setup now makes use of the new ``begin``
  and ``end`` methods of the configurator.

Bug Fixes
---------

- When a ``repoze.bfg.exceptions.NotFound`` or
  ``repoze.bfg.exceptions.Forbidden`` *class* (as opposed to instance)
  was raised as an exception within a root factory (or route root
  factory), the exception would not be caught properly by the
  ``repoze.bfg.`` Router and it would propagate to up the call stack,
  as opposed to rendering the not found view or the forbidden view as
  would have been expected.

18 files changed, 87 insertions, 49 deletions

diff --git a/docs/tutorials/bfgwiki/src/authorization/tutorial/run.py b/docs/tutorials/bfgwiki/src/authorization/tutorial/run.py
index 98baa440b..c80fce02a 100644
--- a/docs/tutorials/bfgwiki/src/authorization/tutorial/run.py
+++ b/docs/tutorials/bfgwiki/src/authorization/tutorial/run.py
@@ -15,6 +15,8 @@ def app(global_config, **settings):
     def get_root(request):
         return finder(request.environ)
     config = Configurator(root_factory=get_root, settings=settings)
+    config.begin()
     config.load_zcml('configure.zcml')
+    config.end()
     return config.make_wsgi_app()
 
diff --git a/docs/tutorials/bfgwiki/src/authorization/tutorial/tests.py b/docs/tutorials/bfgwiki/src/authorization/tutorial/tests.py
index fa025787e..6853bc376 100644
--- a/docs/tutorials/bfgwiki/src/authorization/tutorial/tests.py
+++ b/docs/tutorials/bfgwiki/src/authorization/tutorial/tests.py
@@ -94,7 +94,7 @@ class AddPageTests(unittest.TestCase):
         request = testing.DummyRequest({'form.submitted':True,
                                         'body':'Hello yo!'})
         request.subpath = ['AnotherPage']
-        response = self._callFUT(context, request)
+        self._callFUT(context, request)
         page = context['AnotherPage']
         self.assertEqual(page.data, 'Hello yo!')
         self.assertEqual(page.__name__, 'AnotherPage')
diff --git a/docs/tutorials/bfgwiki/src/basiclayout/tutorial/run.py b/docs/tutorials/bfgwiki/src/basiclayout/tutorial/run.py
index 748b13eef..7d4220717 100644
--- a/docs/tutorials/bfgwiki/src/basiclayout/tutorial/run.py
+++ b/docs/tutorials/bfgwiki/src/basiclayout/tutorial/run.py
@@ -15,5 +15,7 @@ def app(global_config, **settings):
     def get_root(request):
         return finder(request.environ)
     config = Configurator(root_factory=get_root, settings=settings)
+    config.begin()
     config.load_zcml('configure.zcml')
+    config.end()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/bfgwiki/src/basiclayout/tutorial/tests.py b/docs/tutorials/bfgwiki/src/basiclayout/tutorial/tests.py
index 849e75ad4..32821ce0e 100644
--- a/docs/tutorials/bfgwiki/src/basiclayout/tutorial/tests.py
+++ b/docs/tutorials/bfgwiki/src/basiclayout/tutorial/tests.py
@@ -1,13 +1,15 @@
 import unittest
 
+from repoze.bfg.configuration import Configurator
 from repoze.bfg import testing
 
 class ViewTests(unittest.TestCase):
     def setUp(self):
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
 
     def tearDown(self):
-        testing.tearDown()
+        self.config.end()
 
     def test_my_view(self):
         from tutorial.views import my_view
diff --git a/docs/tutorials/bfgwiki/src/models/tutorial/run.py b/docs/tutorials/bfgwiki/src/models/tutorial/run.py
index 748b13eef..7d4220717 100644
--- a/docs/tutorials/bfgwiki/src/models/tutorial/run.py
+++ b/docs/tutorials/bfgwiki/src/models/tutorial/run.py
@@ -15,5 +15,7 @@ def app(global_config, **settings):
     def get_root(request):
         return finder(request.environ)
     config = Configurator(root_factory=get_root, settings=settings)
+    config.begin()
     config.load_zcml('configure.zcml')
+    config.end()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/bfgwiki/src/models/tutorial/tests.py b/docs/tutorials/bfgwiki/src/models/tutorial/tests.py
index 1c1faf855..1eee68e7f 100644
--- a/docs/tutorials/bfgwiki/src/models/tutorial/tests.py
+++ b/docs/tutorials/bfgwiki/src/models/tutorial/tests.py
@@ -1,5 +1,6 @@
 import unittest
 
+from repoze.bfg.configuration import Configurator
 from repoze.bfg import testing
 
 class PageModelTests(unittest.TestCase):
@@ -49,10 +50,11 @@ class AppmakerTests(unittest.TestCase):
 
 class ViewTests(unittest.TestCase):
     def setUp(self):
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
 
     def tearDown(self):
-        testing.tearDown()
+        self.config.end()
 
     def test_my_view(self):
         from tutorial.views import my_view
diff --git a/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/run.py b/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/run.py
index 748b13eef..7d4220717 100644
--- a/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/run.py
+++ b/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/run.py
@@ -15,5 +15,7 @@ def app(global_config, **settings):
     def get_root(request):
         return finder(request.environ)
     config = Configurator(root_factory=get_root, settings=settings)
+    config.begin()
     config.load_zcml('configure.zcml')
+    config.end()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/tests.py b/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/tests.py
index fa025787e..6853bc376 100644
--- a/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/tests.py
+++ b/docs/tutorials/bfgwiki/src/viewdecorators/tutorial/tests.py
@@ -94,7 +94,7 @@ class AddPageTests(unittest.TestCase):
         request = testing.DummyRequest({'form.submitted':True,
                                         'body':'Hello yo!'})
         request.subpath = ['AnotherPage']
-        response = self._callFUT(context, request)
+        self._callFUT(context, request)
         page = context['AnotherPage']
         self.assertEqual(page.data, 'Hello yo!')
         self.assertEqual(page.__name__, 'AnotherPage')
diff --git a/docs/tutorials/bfgwiki/src/views/tutorial/run.py b/docs/tutorials/bfgwiki/src/views/tutorial/run.py
index 748b13eef..7d4220717 100644
--- a/docs/tutorials/bfgwiki/src/views/tutorial/run.py
+++ b/docs/tutorials/bfgwiki/src/views/tutorial/run.py
@@ -15,5 +15,7 @@ def app(global_config, **settings):
     def get_root(request):
         return finder(request.environ)
     config = Configurator(root_factory=get_root, settings=settings)
+    config.begin()
     config.load_zcml('configure.zcml')
+    config.end()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/bfgwiki/src/views/tutorial/tests.py b/docs/tutorials/bfgwiki/src/views/tutorial/tests.py
index 1b2ea972a..bbf86633a 100644
--- a/docs/tutorials/bfgwiki/src/views/tutorial/tests.py
+++ b/docs/tutorials/bfgwiki/src/views/tutorial/tests.py
@@ -94,7 +94,7 @@ class AddPageTests(unittest.TestCase):
         request = testing.DummyRequest({'form.submitted':True,
                                         'body':'Hello yo!'})
         request.subpath = ['AnotherPage']
-        response = self._callFUT(context, request)
+        self._callFUT(context, request)
         page = context['AnotherPage']
         self.assertEqual(page.data, 'Hello yo!')
         self.assertEqual(page.__name__, 'AnotherPage')
diff --git a/docs/tutorials/bfgwiki2/src/authorization/tutorial/run.py b/docs/tutorials/bfgwiki2/src/authorization/tutorial/run.py
index 9ca9fe71e..332f0408f 100644
--- a/docs/tutorials/bfgwiki2/src/authorization/tutorial/run.py
+++ b/docs/tutorials/bfgwiki2/src/authorization/tutorial/run.py
@@ -23,5 +23,7 @@ def app(global_config, **settings):
         raise ValueError("No 'db_string' value in application configuration.")
     initialize_sql(db_string)
     config = Configurator(settings=settings)
+    config.begin()
     config.load_zcml('configure.zcml')
+    config.end()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/bfgwiki2/src/authorization/tutorial/tests.py b/docs/tutorials/bfgwiki2/src/authorization/tutorial/tests.py
index 52d2fed86..7bc8e11ce 100644
--- a/docs/tutorials/bfgwiki2/src/authorization/tutorial/tests.py
+++ b/docs/tutorials/bfgwiki2/src/authorization/tutorial/tests.py
@@ -1,4 +1,6 @@
 import unittest
+
+from repoze.bfg.configuration import Configurator
 from repoze.bfg import testing
 
 def _initTestingDB():
@@ -11,21 +13,22 @@ def _initTestingDB():
     Base.metadata.create_all(engine)
     return DBSession
 
-def _registerRoutes():
-    testing.registerRoute(':pagename', 'view_page')
-    testing.registerRoute(':pagename/edit_page', 'edit_page')
-    testing.registerRoute('add_page/:pagename', 'add_page')
+def _registerRoutes(config):
+    config.add_route('view_page', ':pagename')
+    config.add_route('edit_page', ':pagename/edit_page')
+    config.add_route('add_page', 'add_page/:pagename')
 
 class ViewWikiTests(unittest.TestCase):
     def setUp(self):
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
 
     def tearDown(self):
-        testing.tearDown()
+        self.config.end()
         
     def test_it(self):
         from tutorial.views import view_wiki
-        testing.registerRoute(':pagename', 'view_page')
+        self.config.add_route('view_page', ':pagename')
         request = testing.DummyRequest()
         response = view_wiki(request)
         self.assertEqual(response.location, 'http://example.com/FrontPage')
@@ -33,11 +36,12 @@ class ViewWikiTests(unittest.TestCase):
 class ViewPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
 
     def tearDown(self):
         self.session.remove()
-        testing.tearDown()
+        self.config.end()
         
     def _callFUT(self, request):
         from tutorial.views import view_page
@@ -49,7 +53,7 @@ class ViewPageTests(unittest.TestCase):
         request.matchdict['pagename'] = 'IDoExist'
         page = Page('IDoExist', 'Hello CruelWorld IDoExist')
         self.session.add(page)
-        _registerRoutes()
+        _registerRoutes(self.config)
         info = self._callFUT(request)
         self.assertEqual(info['page'], page)
         self.assertEqual(
@@ -67,18 +71,19 @@ class ViewPageTests(unittest.TestCase):
 class AddPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
 
     def tearDown(self):
         self.session.remove()
-        testing.tearDown()
+        self.config.end()
 
     def _callFUT(self, request):
         from tutorial.views import add_page
         return add_page(request)
 
     def test_it_notsubmitted(self):
-        _registerRoutes()
+        _registerRoutes(self.config)
         request = testing.DummyRequest()
         request.matchdict = {'pagename':'AnotherPage'}
         info = self._callFUT(request)
@@ -88,22 +93,23 @@ class AddPageTests(unittest.TestCase):
         
     def test_it_submitted(self):
         from tutorial.models import Page
-        _registerRoutes()
+        _registerRoutes(self.config)
         request = testing.DummyRequest({'form.submitted':True,
                                         'body':'Hello yo!'})
         request.matchdict = {'pagename':'AnotherPage'}
-        response = self._callFUT(request)
+        self._callFUT(request)
         page = self.session.query(Page).filter_by(name='AnotherPage').one()
         self.assertEqual(page.data, 'Hello yo!')
 
 class EditPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
 
     def tearDown(self):
         self.session.remove()
-        testing.tearDown()
+        self.config.end()
 
     def _callFUT(self, request):
         from tutorial.views import edit_page
@@ -111,7 +117,7 @@ class EditPageTests(unittest.TestCase):
 
     def test_it_notsubmitted(self):
         from tutorial.models import Page
-        _registerRoutes()
+        _registerRoutes(self.config)
         request = testing.DummyRequest()
         request.matchdict = {'pagename':'abc'}
         page = Page('abc', 'hello')
@@ -122,7 +128,7 @@ class EditPageTests(unittest.TestCase):
         
     def test_it_submitted(self):
         from tutorial.models import Page
-        _registerRoutes()
+        _registerRoutes(self.config)
         request = testing.DummyRequest({'form.submitted':True,
                                         'body':'Hello yo!'})
         request.matchdict = {'pagename':'abc'}
diff --git a/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/run.py b/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/run.py
index 9ca9fe71e..332f0408f 100644
--- a/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/run.py
+++ b/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/run.py
@@ -23,5 +23,7 @@ def app(global_config, **settings):
         raise ValueError("No 'db_string' value in application configuration.")
     initialize_sql(db_string)
     config = Configurator(settings=settings)
+    config.begin()
     config.load_zcml('configure.zcml')
+    config.end()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/tests.py b/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/tests.py
index 0c44baf16..2ef74cce7 100644
--- a/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/tests.py
+++ b/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/tests.py
@@ -1,4 +1,5 @@
 import unittest
+from repoze.bfg.configuration import Configurator
 from repoze.bfg import testing
 
 def _initTestingDB():
@@ -8,11 +9,12 @@ def _initTestingDB():
 
 class TestMyView(unittest.TestCase):
     def setUp(self):
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
         _initTestingDB()
 
     def tearDown(self):
-        testing.tearDown()
+        self.config.end()
 
     def test_it(self):
         from tutorial.views import my_view
diff --git a/docs/tutorials/bfgwiki2/src/models/tutorial/run.py b/docs/tutorials/bfgwiki2/src/models/tutorial/run.py
index 9ca9fe71e..332f0408f 100644
--- a/docs/tutorials/bfgwiki2/src/models/tutorial/run.py
+++ b/docs/tutorials/bfgwiki2/src/models/tutorial/run.py
@@ -23,5 +23,7 @@ def app(global_config, **settings):
         raise ValueError("No 'db_string' value in application configuration.")
     initialize_sql(db_string)
     config = Configurator(settings=settings)
+    config.begin()
     config.load_zcml('configure.zcml')
+    config.end()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/bfgwiki2/src/models/tutorial/tests.py b/docs/tutorials/bfgwiki2/src/models/tutorial/tests.py
index 0c44baf16..2ef74cce7 100644
--- a/docs/tutorials/bfgwiki2/src/models/tutorial/tests.py
+++ b/docs/tutorials/bfgwiki2/src/models/tutorial/tests.py
@@ -1,4 +1,5 @@
 import unittest
+from repoze.bfg.configuration import Configurator
 from repoze.bfg import testing
 
 def _initTestingDB():
@@ -8,11 +9,12 @@ def _initTestingDB():
 
 class TestMyView(unittest.TestCase):
     def setUp(self):
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
         _initTestingDB()
 
     def tearDown(self):
-        testing.tearDown()
+        self.config.end()
 
     def test_it(self):
         from tutorial.views import my_view
diff --git a/docs/tutorials/bfgwiki2/src/views/tutorial/run.py b/docs/tutorials/bfgwiki2/src/views/tutorial/run.py
index 9ca9fe71e..332f0408f 100644
--- a/docs/tutorials/bfgwiki2/src/views/tutorial/run.py
+++ b/docs/tutorials/bfgwiki2/src/views/tutorial/run.py
@@ -23,5 +23,7 @@ def app(global_config, **settings):
         raise ValueError("No 'db_string' value in application configuration.")
     initialize_sql(db_string)
     config = Configurator(settings=settings)
+    config.begin()
     config.load_zcml('configure.zcml')
+    config.end()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/bfgwiki2/src/views/tutorial/tests.py b/docs/tutorials/bfgwiki2/src/views/tutorial/tests.py
index 52d2fed86..7bc8e11ce 100644
--- a/docs/tutorials/bfgwiki2/src/views/tutorial/tests.py
+++ b/docs/tutorials/bfgwiki2/src/views/tutorial/tests.py
@@ -1,4 +1,6 @@
 import unittest
+
+from repoze.bfg.configuration import Configurator
 from repoze.bfg import testing
 
 def _initTestingDB():
@@ -11,21 +13,22 @@ def _initTestingDB():
     Base.metadata.create_all(engine)
     return DBSession
 
-def _registerRoutes():
-    testing.registerRoute(':pagename', 'view_page')
-    testing.registerRoute(':pagename/edit_page', 'edit_page')
-    testing.registerRoute('add_page/:pagename', 'add_page')
+def _registerRoutes(config):
+    config.add_route('view_page', ':pagename')
+    config.add_route('edit_page', ':pagename/edit_page')
+    config.add_route('add_page', 'add_page/:pagename')
 
 class ViewWikiTests(unittest.TestCase):
     def setUp(self):
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
 
     def tearDown(self):
-        testing.tearDown()
+        self.config.end()
         
     def test_it(self):
         from tutorial.views import view_wiki
-        testing.registerRoute(':pagename', 'view_page')
+        self.config.add_route('view_page', ':pagename')
         request = testing.DummyRequest()
         response = view_wiki(request)
         self.assertEqual(response.location, 'http://example.com/FrontPage')
@@ -33,11 +36,12 @@ class ViewWikiTests(unittest.TestCase):
 class ViewPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
 
     def tearDown(self):
         self.session.remove()
-        testing.tearDown()
+        self.config.end()
         
     def _callFUT(self, request):
         from tutorial.views import view_page
@@ -49,7 +53,7 @@ class ViewPageTests(unittest.TestCase):
         request.matchdict['pagename'] = 'IDoExist'
         page = Page('IDoExist', 'Hello CruelWorld IDoExist')
         self.session.add(page)
-        _registerRoutes()
+        _registerRoutes(self.config)
         info = self._callFUT(request)
         self.assertEqual(info['page'], page)
         self.assertEqual(
@@ -67,18 +71,19 @@ class ViewPageTests(unittest.TestCase):
 class AddPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
 
     def tearDown(self):
         self.session.remove()
-        testing.tearDown()
+        self.config.end()
 
     def _callFUT(self, request):
         from tutorial.views import add_page
         return add_page(request)
 
     def test_it_notsubmitted(self):
-        _registerRoutes()
+        _registerRoutes(self.config)
         request = testing.DummyRequest()
         request.matchdict = {'pagename':'AnotherPage'}
         info = self._callFUT(request)
@@ -88,22 +93,23 @@ class AddPageTests(unittest.TestCase):
         
     def test_it_submitted(self):
         from tutorial.models import Page
-        _registerRoutes()
+        _registerRoutes(self.config)
         request = testing.DummyRequest({'form.submitted':True,
                                         'body':'Hello yo!'})
         request.matchdict = {'pagename':'AnotherPage'}
-        response = self._callFUT(request)
+        self._callFUT(request)
         page = self.session.query(Page).filter_by(name='AnotherPage').one()
         self.assertEqual(page.data, 'Hello yo!')
 
 class EditPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        testing.setUp()
+        self.config = Configurator()
+        self.config.begin()
 
     def tearDown(self):
         self.session.remove()
-        testing.tearDown()
+        self.config.end()
 
     def _callFUT(self, request):
         from tutorial.views import edit_page
@@ -111,7 +117,7 @@ class EditPageTests(unittest.TestCase):
 
     def test_it_notsubmitted(self):
         from tutorial.models import Page
-        _registerRoutes()
+        _registerRoutes(self.config)
         request = testing.DummyRequest()
         request.matchdict = {'pagename':'abc'}
         page = Page('abc', 'hello')
@@ -122,7 +128,7 @@ class EditPageTests(unittest.TestCase):
         
     def test_it_submitted(self):
         from tutorial.models import Page
-        _registerRoutes()
+        _registerRoutes(self.config)
         request = testing.DummyRequest({'form.submitted':True,
                                         'body':'Hello yo!'})
         request.matchdict = {'pagename':'abc'}