Get rid of ``zcml_file`` argument in configurator constructor in favor of the load_zcml API.

Get rid of hook_zca argument in configurator constructor in favor of a ``hook_zca`` method.

Provide an ``unhook_zca`` method.

11 files changed, 99 insertions, 96 deletions

diff --git a/docs/api/configuration.rst b/docs/api/configuration.rst
index 1107e840b..b23c34aa1 100644
--- a/docs/api/configuration.rst
+++ b/docs/api/configuration.rst
@@ -5,7 +5,7 @@
 
 .. automodule:: repoze.bfg.configuration
 
-  .. autoclass:: Configurator(registry=None, package=None, settings=None, root_factory=None, zcml_file=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, hook_zca=False)
+  .. autoclass:: Configurator(registry=None, package=None, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None)
 
      .. automethod:: add_renderer(name, factory)
 
@@ -17,6 +17,8 @@
 
      .. automethod:: add_view
 
+     .. automethod:: hook_zca()
+
      .. automethod:: load_zcml(spec)
 
      .. automethod:: make_wsgi_app()
@@ -30,3 +32,6 @@
      .. automethod:: set_notfound_view(view=None, attr=None, renderer=None, wrapper=None)
 
      .. automethod:: set_security_policies
+
+     .. automethod:: unhook_zca()
+
diff --git a/docs/narr/MyProject/myproject/run.py b/docs/narr/MyProject/myproject/run.py
index a9d9973bd..0d7647aa7 100644
--- a/docs/narr/MyProject/myproject/run.py
+++ b/docs/narr/MyProject/myproject/run.py
@@ -5,9 +5,9 @@ def app(global_config, **settings):
     """ This function returns a repoze.bfg.router.Router object.  It
     is usually called by the PasteDeploy framework during ``paster
     serve``"""
+    config = Configurator(root_factory=get_root, settings=settings)
     zcml_file = settings.get('configure_zcml', 'configure.zcml')
-    config = Configurator(root_factory=get_root, settings=settings,
-                          zcml_file=zcml_file)
+    config.load_zcml(zcml_file)
     return config.make_wsgi_app()
 
 
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 6a465db15..c8f29fdfd 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -587,7 +587,8 @@ In a file named ``helloworld.py``:
        return Response('Goodbye world!')
 
    if __name__ == '__main__':
-       config = Configurator(zcml_file='configure.zcml')
+       config = Configurator()
+       config.load_zcml('configure.zcml)
        app = config.make_wsgi_app()
        simple_server.make_server('', 8080, app).serve_forever()
 
@@ -629,26 +630,27 @@ within the ``if __name__ == '__main__'`` section of ``helloworld.py``:
        app = config.make_wsgi_app()
        simple_server.make_server('', 8080, app).serve_forever()
 
-In our "declarative" code, we've added a ``zcml_file`` argument to the
-``Configurator`` constructor's argument list with the value
-``configure.zcml``, and we've removed the lines which read
-``config.add_view(hello_world)`` and ``config.add_view(goodbye_world,
-name='goodbye')``, so that it now reads as:
+In our "declarative" code, we've added a call to the ``load_zcml``
+method of the ``Configurator`` with the value ``configure.zcml``, and
+we've removed the lines which read ``config.add_view(hello_world)``
+and ``config.add_view(goodbye_world, name='goodbye')``, so that it now
+reads as:
 
 .. code-block:: python
    :linenos:
 
    if __name__ == '__main__':
-       config = Configurator(zcml_file='configure.zcml')
+       config = Configurator()
+       config.load_zcml('configure.zcml')
        app = config.make_wsgi_app()
        simple_server.make_server('', 8080, app).serve_forever()
 
 Everything else is much the same.
 
-The ``zcml_file`` argument to the ``Configurator`` constructor tells
-the configurator to load configuration declarations from the
-``configure.zcml`` file which sits next to ``helloworld.py``.  Let's
-take a look at the ``configure.zcml`` file now:
+The ``config.load_zcml('configure.zcml')`` line tells the configurator
+to load configuration declarations from the ``configure.zcml`` file
+which sits next to ``helloworld.py``.  Let's take a look at the
+``configure.zcml`` file now:
 
 .. code-block:: xml
    :linenos:
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 80fe6beac..eb0135833 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -539,8 +539,8 @@ The ``myproject`` :term:`package` lives inside the ``MyProject``
    comment at the top.
 
 #. A ``configure.zcml`` is a :term:`ZCML` file which maps view names
-   to model types.  This is also known as the :term:`application
-   registry`.
+   to model types.  Its contents populate the :term:`application
+   registry` when loaded.
 
 #. A ``models.py`` module, which contains :term:`model` code.
 
diff --git a/docs/narr/scanning.rst b/docs/narr/scanning.rst
index 084d550d6..477b2144c 100644
--- a/docs/narr/scanning.rst
+++ b/docs/narr/scanning.rst
@@ -123,7 +123,8 @@ of the below examples produces the same application configuration.
 
       if __name__ == '__main__':
           from repoze.bfg.configuration import Configurator
-          config = Configurator(zcml_file='configure.zcml')
+          config = Configurator()
+          config.load_zcml('configure.zcml')
 
    .. code-block:: xml
       :linenos:
@@ -172,7 +173,8 @@ of the below examples produces the same application configuration.
 
       if __name__ == '__main__':
           from repoze.bfg.configuration import Configurator
-          config = Configurator(zcml_file='configure.zcml')
+          config = Configurator()
+          config.load_zcml('configure.zcml')
 
    .. code-block:: xml
       :linenos:
diff --git a/repoze/bfg/configuration.py b/repoze/bfg/configuration.py
index 4eccf628c..02e402796 100644
--- a/repoze/bfg/configuration.py
+++ b/repoze/bfg/configuration.py
@@ -126,25 +126,11 @@ class Configurator(object):
     If ``debug_logger`` is not passed, a default debug logger that
     logs to stderr will be used.  If it is passed, it should be an
     instance of a ``logging.Logger`` (PEP 282) class.
-
-    If ``hook_zca`` is ``True``, the configurator constructor will run
-    ``zope.component.getSiteManager.sethook(
-    repoze.bfg.threadlocals.get_current_registry)``.  This causes the
-    ``zope.component.getSiteManager`` API to return the
-    :mod:`repoze.bfg` thread local registry.  This has the effect of
-    causing ``zope.component`` thread local API functions such as
-    ``getUtility`` and ``getMultiAdapter`` to use the
-    :mod:`repoze.bfg` registry instead of the global Zope registry
-    during the scope of every :mod:`repoze.bfg` :term:`request`.  It
-    typically also means registrations made via ZCML will end up in
-    the :mod:`repoze.bfg` registry instead of the global Zope
-    registry.  By default, this is ``False``. """
-
+    """
     def __init__(self, registry=None, package=None, settings=None,
-                 root_factory=None, zcml_file=None,
-                 authentication_policy=None, authorization_policy=None,
-                 renderers=DEFAULT_RENDERERS, debug_logger=None,
-                 hook_zca=False):
+                 root_factory=None, authentication_policy=None,
+                 authorization_policy=None, renderers=DEFAULT_RENDERERS,
+                 debug_logger=None):
         self.package = package or caller_package()
         self.registry = registry
         if registry is None:
@@ -163,12 +149,6 @@ class Configurator(object):
                                            authorization_policy)
             for name, renderer in renderers:
                 self.add_renderer(name, renderer)
-            if hook_zca:
-                from zope.component import getSiteManager
-                getSiteManager.sethook(get_current_registry)
-                self.registry.zca_hooked = True
-            if zcml_file is not None:
-                self.load_zcml(zcml_file)
 
     def _set_settings(self, mapping):
         settings = Settings(mapping or {})
@@ -273,6 +253,33 @@ class Configurator(object):
 
     # API
 
+    def hook_zca(self):
+        """
+        If this method is called, the configurator will run
+        ``zope.component.getSiteManager.sethook(
+        repoze.bfg.threadlocals.get_current_registry)``.  This causes
+        the ``zope.component.getSiteManager`` API to return the
+        :mod:`repoze.bfg` thread local registry.  This has the effect
+        of causing ``zope.component`` thread local API functions such
+        as ``getUtility`` and ``getMultiAdapter`` to use the
+        :mod:`repoze.bfg` registry instead of the global Zope registry
+        during the scope of every :mod:`repoze.bfg` :term:`request`.
+        """
+        from zope.component import getSiteManager
+        getSiteManager.sethook(get_current_registry)
+
+    def unhook_zca(self):
+        """
+        If this method is called, the configurator constructor will
+        run ``zope.component.getSiteManager.reset()``.  This causes
+        the ``zope.component.getSiteManager`` API to return the
+        original registry assigned to it (usually the Zope global
+        registry), effectively undoing the work of the ``hook_zca``
+        method.
+        """
+        from zope.component import getSiteManager
+        getSiteManager.reset()
+
     def add_subscriber(self, subscriber, iface=None):
         """ Add an event subscriber for the event stream implied by
         the supplied ``iface`` interface.  The ``subscriber`` argument
@@ -1056,10 +1063,10 @@ def make_app(root_factory, package=None, filename='configure.zcml',
     ``settings`` keyword parameter.
     """
     settings = settings or options or {}
-    zcml_file = settings.get('configure_zcml', filename)
     config = Configurator(package=package, settings=settings,
-                          root_factory=root_factory, zcml_file=zcml_file,
-                          hook_zca=True) # hook_zca for bw compat
-    app = config.make_wsgi_app()
-    return app
+                          root_factory=root_factory)
+    config.hook_zca()
+    zcml_file = settings.get('configure_zcml', filename)
+    config.load_zcml(zcml_file)
+    return config.make_wsgi_app()
 
diff --git a/repoze/bfg/paster_templates/alchemy/+package+/run.py_tmpl b/repoze/bfg/paster_templates/alchemy/+package+/run.py_tmpl
index 5eeaf1cba..7ef208c30 100644
--- a/repoze/bfg/paster_templates/alchemy/+package+/run.py_tmpl
+++ b/repoze/bfg/paster_templates/alchemy/+package+/run.py_tmpl
@@ -25,8 +25,8 @@ def app(global_config, **settings):
     if db_echo is None:
         db_echo = True
     get_root = appmaker(db_string, db_echo)
+    config = Configurator(settings=settings, root_factory=get_root)
     zcml_file = settings.get('configure_zcml', 'configure.zcml')
-    config = Configurator(settings=settings, root_factory=get_root, 
-                          zcml_file=zcml_file)
+    config.load_zcml(zcml_file)
     return config.make_wsgi_app()
 
diff --git a/repoze/bfg/paster_templates/routesalchemy/+package+/run.py_tmpl b/repoze/bfg/paster_templates/routesalchemy/+package+/run.py_tmpl
index e0e705224..b592e45a9 100644
--- a/repoze/bfg/paster_templates/routesalchemy/+package+/run.py_tmpl
+++ b/repoze/bfg/paster_templates/routesalchemy/+package+/run.py_tmpl
@@ -22,7 +22,8 @@ def app(global_config, **settings):
     if db_string is None:
         raise ValueError("No 'db_string' value in application configuration.")
     initialize_sql(db_string)
+    config = Configurator(settings=settings)
     zcml_file = settings.get('configure_zcml', 'configure.zcml')
-    config = Configurator(settings=settings, zcml_file=zcml_file)
+    config.load_zcml(zcml_file)
     return config.make_wsgi_app()
 
diff --git a/repoze/bfg/paster_templates/starter/+package+/run.py_tmpl b/repoze/bfg/paster_templates/starter/+package+/run.py_tmpl
index b7cd4b2c3..12d2a0719 100644
--- a/repoze/bfg/paster_templates/starter/+package+/run.py_tmpl
+++ b/repoze/bfg/paster_templates/starter/+package+/run.py_tmpl
@@ -5,7 +5,7 @@ def app(global_config, **settings):
     """ This function returns a repoze.bfg.router.Router object.  It
     is usually called by the PasteDeploy framework during ``paster
     serve``"""
+    config = Configurator(root_factory=get_root, settings=settings)
     zcml_file = settings.get('configure_zcml', 'configure.zcml')
-    config = Configurator(root_factory=get_root, 
-                          settings=settings, zcml_file=zcml_file)
+    config.load_zcml(zcml_file)
     return config.make_wsgi_app()
diff --git a/repoze/bfg/paster_templates/zodb/+package+/run.py_tmpl b/repoze/bfg/paster_templates/zodb/+package+/run.py_tmpl
index 4fc20798d..c9023f822 100644
--- a/repoze/bfg/paster_templates/zodb/+package+/run.py_tmpl
+++ b/repoze/bfg/paster_templates/zodb/+package+/run.py_tmpl
@@ -14,7 +14,7 @@ def app(global_config, **settings):
     finder = PersistentApplicationFinder(zodb_uri, appmaker)
     def get_root(request):
         return finder(request.environ)
+    config = Configurator(root_factory=get_root, settings=settings)
     zcml_file = settings.get('configure_zcml', 'configure.zcml')
-    config = Configurator(root_factory=get_root,
-                          settings=settings, zcml_file=zcml_file)
+    config.load_zcml(zcml_file)
     return config.make_wsgi_app()
diff --git a/repoze/bfg/tests/test_configuration.py b/repoze/bfg/tests/test_configuration.py
index 750bd5054..ae75494e4 100644
--- a/repoze/bfg/tests/test_configuration.py
+++ b/repoze/bfg/tests/test_configuration.py
@@ -92,20 +92,6 @@ class ConfiguratorTests(unittest.TestCase):
         config = Configurator(package=bfg_pkg)
         self.assertEqual(config.package, bfg_pkg)
 
-    def test_ctor_noreg_zcml_file(self):
-        config = self._makeOne(
-            registry=None,
-            zcml_file='repoze.bfg.tests.fixtureapp:configure.zcml')
-        registry = config.registry
-        from repoze.bfg.tests.fixtureapp.models import IFixture
-        self.failUnless(registry.queryUtility(IFixture)) # only in c.zcml
-
-    def test_ctor_noreg_zcml_file_routes_in_config(self):
-        from repoze.bfg.interfaces import IRoutesMapper
-        config = self._makeOne(
-            zcml_file='repoze.bfg.tests.routesapp:configure.zcml')
-        self.failUnless(config.registry.getUtility(IRoutesMapper))
-
     def test_ctor_noreg_custom_settings(self):
         from repoze.bfg.interfaces import ISettings
         settings = {'reload_templates':True,
@@ -148,36 +134,28 @@ class ConfiguratorTests(unittest.TestCase):
         self.assertEqual(config.registry.getUtility(IRendererFactory, 'yeah'),
                          renderer)
 
-    def test_ctor_hook_zca_true(self):
+    def test_hook_zca(self):
         from zope.component import getSiteManager
         from repoze.bfg.threadlocal import get_current_registry
         try:
             getSiteManager.reset()
-            config = self._makeOne(hook_zca=True)
+            config = self._makeOne()
+            config.hook_zca()
             hooked = getSiteManager.sethook(None)
             self.assertEqual(hooked, get_current_registry)
         finally:
             getSiteManager.reset()
 
-    def test_ctor_hook_zca_false(self):
-        from zope.component import getSiteManager
-        from repoze.bfg.threadlocal import get_current_registry
-        try:
-            getSiteManager.reset()
-            config = self._makeOne(hook_zca=False)
-            hooked = getSiteManager.sethook(None)
-            self.failIfEqual(hooked, get_current_registry)
-        finally:
-            getSiteManager.reset()
-
-    def test_ctor_hook_zca_default_false(self):
+    def test_unhook_zca(self):
         from zope.component import getSiteManager
-        from repoze.bfg.threadlocal import get_current_registry
         try:
-            getSiteManager.reset()
             config = self._makeOne()
-            hooked = getSiteManager.sethook(None)
-            self.failIfEqual(hooked, get_current_registry)
+            reg = object()
+            hook = lambda *arg: reg
+            hooked = getSiteManager.sethook(hook)
+            self.assertEqual(getSiteManager(), reg)
+            config.unhook_zca()
+            self.assertNotEqual(getSiteManager(), reg)
         finally:
             getSiteManager.reset()
 
@@ -266,12 +244,17 @@ class ConfiguratorTests(unittest.TestCase):
         from repoze.bfg.tests.fixtureapp.models import IFixture
         self.failUnless(registry.queryUtility(IFixture)) # only in c.zcml
 
-    def test_load_zcml_as_resource_spec(self):
+    def test_load_zcml_routesapp(self):
+        from repoze.bfg.interfaces import IRoutesMapper
         config = self._makeOne()
-        registry = config.load_zcml(
-            'repoze.bfg.tests.fixtureapp:configure.zcml')
+        config.load_zcml('repoze.bfg.tests.routesapp:configure.zcml')
+        self.failUnless(config.registry.getUtility(IRoutesMapper))
+
+    def test_load_zcml_fixtureapp(self):
         from repoze.bfg.tests.fixtureapp.models import IFixture
-        self.failUnless(registry.queryUtility(IFixture)) # only in c.zcml
+        config = self._makeOne()
+        config.load_zcml('repoze.bfg.tests.fixtureapp:configure.zcml')
+        self.failUnless(config.registry.queryUtility(IFixture)) # only in c.zcml
 
     def test_load_zcml_as_relative_filename(self):
         import repoze.bfg.tests.fixtureapp
@@ -2512,7 +2495,7 @@ class TestMakeApp(unittest.TestCase):
         self.assertEqual(app.root_factory, rootfactory)
         self.assertEqual(app.settings, settings)
         self.assertEqual(app.zcml_file, 'configure.zcml')
-        self.assertEqual(app.hook_zca, True)
+        self.assertEqual(app.zca_hooked, True)
 
     def test_it_options_means_settings(self):
         settings = {'a':1}
@@ -2609,14 +2592,17 @@ class DummySecurityPolicy:
         return self.permitted
 
 class DummyConfigurator(object):
-    def __init__(self, registry=None, package=None,
-                 root_factory=None, zcml_file=None,
-                 settings=None, hook_zca=False):
+    def __init__(self, registry=None, package=None, root_factory=None,
+                 settings=None):
         self.root_factory = root_factory
         self.package = package
-        self.zcml_file = zcml_file
         self.settings = settings
-        self.hook_zca = hook_zca
+
+    def hook_zca(self):
+        self.zca_hooked = True
+
+    def load_zcml(self, filename):
+        self.zcml_file = filename
     
     def make_wsgi_app(self):
         return self