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.

5 files changed, 27 insertions, 18 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: