fix merge conflicts

68 files changed, 528 insertions, 315 deletions

diff --git a/docs/api.rst b/docs/api.rst
index f8c532cd6..b650c8ded 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -12,7 +12,7 @@ documentation is organized alphabetically by module name.
    api/authentication
    api/chameleon_text
    api/chameleon_zpt
-   api/configuration
+   api/config
    api/events
    api/exceptions
    api/httpexceptions
diff --git a/docs/api/configuration.rst b/docs/api/config.rst
index 6d5c9f16b..64dc4d0dd 100644
--- a/docs/api/configuration.rst
+++ b/docs/api/config.rst
@@ -1,11 +1,11 @@
 .. _configuration_module:
 
-:mod:`pyramid.configuration`
--------------------------------
+:mod:`pyramid.config`
+---------------------
 
-.. automodule:: pyramid.configuration
+.. automodule:: pyramid.config
 
-  .. autoclass:: Configurator(registry=None, package=None, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None, default_permission=None, session_factory=None)
+  .. autoclass:: Configurator(registry=None, package=None, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None, default_permission=None, session_factory=None, autocommit=False)
 
      .. attribute:: registry
 
@@ -22,6 +22,12 @@
 
      .. automethod:: get_settings
 
+     .. automethod:: commit
+
+     .. automethod:: action
+
+     .. automethod:: include
+
      .. automethod:: with_package
 
      .. automethod:: maybe_dotted
diff --git a/docs/conventions.rst b/docs/conventions.rst
index a17af7230..71c40e104 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -22,12 +22,12 @@ concept are presented in the following style:
 
 We present Python method names using the following style:
 
-  :meth:`pyramid.configuration.Configurator.add_view`
+  :meth:`pyramid.config.Configurator.add_view`
 
 We present Python class names, module names, attributes and global
 variables using the following style:
 
-  :class:`pyramid.configuration.Configurator.registry`
+  :class:`pyramid.config.Configurator.registry`
 
 References to glossary terms are presented using the following style:
 
diff --git a/docs/designdefense.rst b/docs/designdefense.rst
index 1409403c4..1a8868883 100644
--- a/docs/designdefense.rst
+++ b/docs/designdefense.rst
@@ -37,7 +37,7 @@ Too Complex
    :linenos:
 
    from paste.httpserver import serve
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    from pyramid.response import Response
 
    def hello_world(request):
@@ -545,7 +545,7 @@ everything done completely imperatively.  For example, the very most basic
 
    from webob import Response
    from paste.httpserver import serve
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
 
    def hello_world(request):
        return Response('Hello world!')
@@ -1707,7 +1707,7 @@ where comments take into account what we've discussed in the
        return Response('Hello world!') 
 
    if __name__ == '__main__':
-       from pyramid.configuration import Configurator
+       from pyramid.config import Configurator
        config = Configurator()       # no global application object.
        config.add_view(hello_world)  # explicit non-decorator registration
        app = config.make_wsgi_app()  # explicitly WSGI
diff --git a/docs/glossary.rst b/docs/glossary.rst
index ee7a2784d..2494a6cdf 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -585,7 +585,7 @@ Glossary
    configurator
      An object used to do :term:`configuration declaration` within an
      application.  The most common configurator is an instance of the
-     ``pyramid.configuration.Configurator`` class.
+     ``pyramid.config.Configurator`` class.
 
    imperative configuration
      The configuration mode in which you use Python to call methods on
@@ -822,8 +822,8 @@ Glossary
 
    View handler
      A view handler ties together
-     :meth:`pyramid.configuration.Configurator.add_route` and
-     :meth:`pyramid.configuration.Configurator.add_view` to make it more
+     :meth:`pyramid.config.Configurator.add_route` and
+     :meth:`pyramid.config.Configurator.add_view` to make it more
      convenient to register a collection of views as a single class when
      using :term:`url dispatch`.  See also :ref:`handlers_chapter`.
 
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 388297de7..0ef67248b 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -85,7 +85,7 @@ API Reference
    api/authentication
    api/chameleon_text
    api/chameleon_zpt
-   api/configuration
+   api/config
    api/events
    api/exceptions
    api/httpexceptions
diff --git a/docs/narr/MyProject/myproject/__init__.py b/docs/narr/MyProject/myproject/__init__.py
index 936404c82..05730a115 100644
--- a/docs/narr/MyProject/myproject/__init__.py
+++ b/docs/narr/MyProject/myproject/__init__.py
@@ -1,4 +1,4 @@
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from myproject.models import get_root
 
 def main(global_config, **settings):
diff --git a/docs/narr/MyProject/myproject/tests.py b/docs/narr/MyProject/myproject/tests.py
index 2f14a946b..b14fb37af 100644
--- a/docs/narr/MyProject/myproject/tests.py
+++ b/docs/narr/MyProject/myproject/tests.py
@@ -1,11 +1,11 @@
 import unittest
 
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from pyramid import testing
 
 class ViewTests(unittest.TestCase):
     def setUp(self):
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index cf1f1ae28..4f26b092a 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -38,7 +38,7 @@ imperatively:
    :linenos:
 
    from paste.httpserver import serve
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    from pyramid.response import Response
 
    def hello_world(request):
@@ -98,7 +98,7 @@ attribute to the ``hello`` function, making it available for a
 
 :app:`Pyramid` is willing to :term:`scan` a module or a package and
 its subpackages for decorations when the
-:meth:`pyramid.configuration.Configurator.scan` method is invoked:
+:meth:`pyramid.config.Configurator.scan` method is invoked:
 scanning implies searching for configuration declarations in a package
 and its subpackages.  For example:
 
@@ -116,7 +116,7 @@ and its subpackages.  For example:
           return Response('Hello')
 
       if __name__ == '__main__':
-          from pyramid.configuration import Configurator
+          from pyramid.config import Configurator
           config = Configurator()
           config.scan()
           app = config.make_wsgi_app()
@@ -136,7 +136,7 @@ the intent of the configuration decoration.
 
 In the example above, this is best represented as the scanner
 translating the arguments to :class:`pyramid.view.view_config` into a
-call to the :meth:`pyramid.configuration.Configurator.add_view`
+call to the :meth:`pyramid.config.Configurator.add_view`
 method, effectively:
 
 .. ignore-next-block
diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst
index eeaed318f..99c5a75ac 100644
--- a/docs/narr/declarative.rst
+++ b/docs/narr/declarative.rst
@@ -41,7 +41,7 @@ In a file named ``helloworld.py``:
 
    from paste.httpserver import serve
    from pyramid.response import Response
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
 
    def hello_world(request):
        return Response('Hello world!')
@@ -91,7 +91,7 @@ the ``if __name__ == '__main__'`` section of ``helloworld.py``:
 
 In our "declarative" code, we've removed the call to ``add_view`` and
 replaced it with a call to the
-:meth:`pyramid.configuration.Configurator.load_zcml` method so that
+:meth:`pyramid.config.Configurator.load_zcml` method so that
 it now reads as:
 
 .. code-block:: python
@@ -135,13 +135,13 @@ This ``<view>`` declaration tag performs the same function as the
 ``add_view`` method that was employed within
 :ref:`imperative_configuration`.  In fact, the ``<view>`` tag is
 effectively a "macro" which calls the
-:meth:`pyramid.configuration.Configurator.add_view` method on your
+:meth:`pyramid.config.Configurator.add_view` method on your
 behalf.
 
 The ``<view>`` tag is an example of a :app:`Pyramid` declaration
 tag.  Other such tags include ``<route>`` and ``<scan>``.  Each of
 these tags is effectively a "macro" which calls methods of a
-:class:`pyramid.configuration.Configurator` object on your behalf.
+:class:`pyramid.config.Configurator` object on your behalf.
 
 Essentially, using a :term:`ZCML` file and loading it from the
 filesystem allows us to put our configuration statements within this
@@ -212,7 +212,7 @@ To do so, first, create a file named ``helloworld.py``:
 .. code-block:: python
    :linenos:
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    from pyramid.response import Response
    from paste.httpserver import serve
 
@@ -277,7 +277,7 @@ within the ``if __name__ == '__main__'`` section of ``helloworld.py``:
        serve(app, host='0.0.0.0')
 
 In our "declarative" code, we've added a call to the
-:meth:`pyramid.configuration.Configurator.load_zcml` method with
+:meth:`pyramid.config.Configurator.load_zcml` method 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:
@@ -433,13 +433,13 @@ configurations imperatively, we saw this code:
    config.add_view(goodbye_world, name='goodbye')
 
 Each ``<view>`` declaration tag encountered in a ZCML file effectively
-invokes the :meth:`pyramid.configuration.Configurator.add_view`
+invokes the :meth:`pyramid.config.Configurator.add_view`
 method on the behalf of the developer.  Various attributes can be
 specified on the ``<view>`` tag which influence the :term:`view
 configuration` it creates.
 
 Since the relative ordering of calls to
-:meth:`pyramid.configuration.Configurator.add_view` doesn't matter
+:meth:`pyramid.config.Configurator.add_view` doesn't matter
 (see the sidebar entitled *View Dispatch and Ordering* within
 :ref:`adding_configuration`), the relative order of ``<view>`` tags in
 ZCML doesn't matter either.  The following ZCML orderings are
@@ -501,7 +501,7 @@ file points to is scanned.
        return Response('Hello')
 
    if __name__ == '__main__':
-       from pyramid.configuration import Configurator
+       from pyramid.config import Configurator
        config = Configurator()
        config.begin()
        config.load_zcml('configure.zcml')
@@ -644,12 +644,11 @@ See :ref:`view_directive` for complete ZCML directive documentation.
 Configuring a Route via ZCML
 ----------------------------
 
-Instead of using the imperative
-:meth:`pyramid.configuration.Configurator.add_route` method to add a new
-route, you can alternately use :term:`ZCML`.  :ref:`route_directive`
-statements in a :term:`ZCML` file used by your application is a sign that
-you're using :term:`URL dispatch`.  For example, the following :term:`ZCML
-declaration` causes a route to be added to the application.
+Instead of using the imperative :meth:`pyramid.config.Configurator.add_route`
+method to add a new route, you can alternately use :term:`ZCML`.
+:ref:`route_directive` statements in a :term:`ZCML` file. For example, the
+following :term:`ZCML declaration` causes a route to be added to the
+application.
 
 .. code-block:: xml
    :linenos:
@@ -679,6 +678,46 @@ is the order that they appear relative to each other in the ZCML file.
 See :ref:`route_directive` for full ``route`` ZCML directive
 documentation.
 
+.. _zcml_handler_configuration:
+
+Configuring a Handler via ZCML
+------------------------------
+
+Instead of using the imperative
+:meth:`pyramid.config.Configurator.add_handler` method to add a new
+route, you can alternately use :term:`ZCML`.  :ref:`handler_directive`
+statements in a :term:`ZCML` file used by your application is a sign that
+you're using :term:`URL dispatch`.  For example, the following :term:`ZCML
+declaration` causes a route to be added to the application.
+
+.. code-block:: xml
+   :linenos:
+
+   <handler
+     route_name="myroute"
+     pattern="/prefix/{action}"
+     handler=".handlers.MyHandler"
+    />
+
+.. note::
+
+   Values prefixed with a period (``.``) within the values of ZCML attributes
+   such as the ``handler`` attribute of a ``handler`` directive mean
+   "relative to the Python package directory in which this :term:`ZCML` file
+   is stored".  So if the above ``handler`` declaration was made inside a
+   ``configure.zcml`` file that lived in the ``hello`` package, you could
+   replace the relative ``.views.MyHandler`` with the absolute
+   ``hello.views.MyHandler`` Either the relative or absolute form is
+   functionally equivalent.  It's often useful to use the relative form, in
+   case your package's name changes.  It's also shorter to type.
+
+The order that the routes attached to handlers are evaluated when declarative
+configuration is used is the order that they appear relative to each other in
+the ZCML file.
+
+See :ref:`handler_directive` for full ``handler`` ZCML directive
+documentation.
+
 .. index::
    triple: view; zcml; static resource
 
@@ -778,7 +817,7 @@ listening on ``example.com`` must be itself configured to respond properly to
 such a request.  The :func:`pyramid.url.static_url` API is discussed in more
 detail later in this chapter.
 
-The :meth:`pyramid.configuration.Configurator.add_static_view` method offers
+The :meth:`pyramid.config.Configurator.add_static_view` method offers
 an imperative equivalent to the ``static`` ZCML directive.  Use of the
 ``add_static_view`` imperative configuration method is completely equivalent
 to using ZCML for the same purpose.  See :ref:`static_resources_section` for
@@ -1028,7 +1067,7 @@ with ``.jinja2`` as its ``renderer`` value.  The ``name`` passed to the
 ``renderer=`` to the view configuration.
 
 See also :ref:`renderer_directive` and
-:meth:`pyramid.configuration.Configurator.add_renderer`.
+:meth:`pyramid.config.Configurator.add_renderer`.
 
 
 Overriding an Existing Renderer
@@ -1097,7 +1136,7 @@ tag):
     />
 
 See also :ref:`renderer_directive` and
-:meth:`pyramid.configuration.Configurator.add_renderer`.
+:meth:`pyramid.config.Configurator.add_renderer`.
 
 .. _zcml_adding_a_translation_directory:
 
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index 1edc2c5b0..06b30883f 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -34,7 +34,7 @@ when it's called.
 The mere existence of a subscriber function, however, is not sufficient to
 arrange for it to be called.  To arrange for the subscriber to be called,
 you'll need to use the
-:meth:`pyramid.configuration.Configurator.add_subscriber` method or you'll
+:meth:`pyramid.config.Configurator.add_subscriber` method or you'll
 need to use the :func:`pyramid.events.subscriber` decorator to decorate a
 function found via a :term:`scan`.
 
@@ -42,7 +42,7 @@ function found via a :term:`scan`.
 
    You can imperatively configure a subscriber function to be called
    for some event type via the
-   :meth:`pyramid.configuration.Configurator.add_subscriber`
+   :meth:`pyramid.config.Configurator.add_subscriber`
    method (see also :term:`Configurator`):
 
    .. code-block:: python
@@ -53,12 +53,12 @@ function found via a :term:`scan`.
       from subscribers import mysubscriber
 
       # "config" below is assumed to be an instance of a 
-      # pyramid.configuration.Configurator object
+      # pyramid.config.Configurator object
 
       config.add_subscriber(mysubscriber, NewRequest)
 
    The first argument to
-   :meth:`pyramid.configuration.Configurator.add_subscriber` is the
+   :meth:`pyramid.config.Configurator.add_subscriber` is the
    subscriber function (or a :term:`dotted Python name` which refers
    to a subscriber callable); the second argument is the event type.
 
@@ -127,7 +127,7 @@ configuration startup:
 .. code-block:: python
    :linenos:
 
-   # config is an instance of pyramid.configuration.Configurator
+   # config is an instance of pyramid.config.Configurator
 
    config.add_subscriber('myproject.subscribers.handle_new_request',
                          'pyramid.events.NewRequest')
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index 902fb001d..1f9fd1288 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -23,7 +23,7 @@ relying on :term:`configuration decoration` meant to be detected via
 a :term:`scan`, and you mustn't configure your :app:`Pyramid`
 application *imperatively* by using any code which configures the
 application through methods of the :term:`Configurator` (except for
-the :meth:`pyramid.configuration.Configurator.load_zcml` method).
+the :meth:`pyramid.config.Configurator.load_zcml` method).
 
 Instead, you must always use :term:`ZCML` for the equivalent
 purposes. :term:`ZCML` declarations that belong to an application can be
@@ -104,7 +104,7 @@ configuration imperatively, one of two things may be true:
   :class:`pyramid.view.view_config` decorators, you can just prevent a
   :term:`scan` from happening (by omitting the ``<scan>`` declaration
   from ZCML or omitting any call to the
-  :meth:`pyramid.configuration.Configurator.scan` method).  This
+  :meth:`pyramid.config.Configurator.scan` method).  This
   will cause the decorators to do nothing.  At this point, you will
   need to convert all the configuration done in decorators into
   equivalent :term:`ZCML` and add that ZCML to a separate Python
@@ -170,7 +170,7 @@ something like this:
 
 - In the ``__init__.py`` of the new package, load the ``configure.zcml`` file
   of the new package using the
-  :meth:`pyramid.configuration.Configurator.load_zcml` method.
+  :meth:`pyramid.config.Configurator.load_zcml` method.
 
 .. index::
    pair: overriding; views
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index 86152c8b2..b40faee3d 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -26,7 +26,7 @@ configured imperatively:
 .. code-block:: python
    :linenos:
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    from pyramid.response import Response
    from paste.httpserver import serve
 
@@ -68,12 +68,12 @@ The above script defines the following set of imports:
 .. code-block:: python
    :linenos:
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    from pyramid.response import Response
    from paste.httpserver import serve
 
 The script imports the ``Configurator`` class from the
-``pyramid.configuration`` module.  This class is used to configure
+``pyramid.config`` module.  This class is used to configure
 :app:`Pyramid` for a particular application.  An instance of this class
 provides methods which help configure various parts of :app:`Pyramid` for a
 given application deployment.
@@ -180,7 +180,7 @@ code within the ``if`` block should only be run during a direct script
 execution.
 
 The ``config = Configurator()`` line above creates an instance of the
-:class:`pyramid.configuration.Configurator` class.  The resulting
+:class:`pyramid.config.Configurator` class.  The resulting
 ``config`` object represents an API which the script uses to configure
 this particular :app:`Pyramid` application.  Methods called on the
 Configurator will cause registrations to be made in a
@@ -199,7 +199,7 @@ Adding Configuration
    config.add_view(goodbye_world, name='goodbye')
 
 Each of these lines calls the
-:meth:`pyramid.configuration.Configurator.add_view` method.  The
+:meth:`pyramid.config.Configurator.add_view` method.  The
 ``add_view`` method of a configurator registers a :term:`view
 configuration` within the :term:`application registry`.  A :term:`view
 configuration` represents a set of circumstances related to the
@@ -249,7 +249,7 @@ set of predicates) is always invoked.
 In this application, :app:`Pyramid` chooses the most specific view
 callable based only on view :term:`predicate` applicability.  The
 ordering of calls to
-:meth:`pyramid.configuration.Configurator.add_view` is never very
+:meth:`pyramid.config.Configurator.add_view` is never very
 important.  We can register ``goodbye_world`` first and
 ``hello_world`` second; :app:`Pyramid` will still give us the most
 specific callable when a request is dispatched to it.
@@ -269,7 +269,7 @@ WSGI Application Creation
 
 After configuring views and ending configuration, the script creates a
 WSGI *application* via the
-:meth:`pyramid.configuration.Configurator.make_wsgi_app` method.  A
+:meth:`pyramid.config.Configurator.make_wsgi_app` method.  A
 call to ``make_wsgi_app`` implies that all configuration is finished
 (meaning all method calls to the configurator which set up views, and
 various other configuration settings have been performed).  The
@@ -332,7 +332,7 @@ References
 ----------
 
 For more information about the API of a :term:`Configurator` object,
-see :class:`pyramid.configuration.Configurator` .
+see :class:`pyramid.config.Configurator` .
 
 For more information about :term:`view configuration`, see
 :ref:`views_chapter`.
diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst
index d28c9d120..f6e658cf0 100644
--- a/docs/narr/handlers.rst
+++ b/docs/narr/handlers.rst
@@ -6,8 +6,8 @@ View Handlers
 Along with normal view callables, :app:`Pyramid` provides the concept of a
 :term:`view handler`.  Using a view handler instead of a plain :term:`view
 callable` makes it unnecessary to call
-:meth:`pyramid.configuration.Configurator.add_route` (and/or
-:meth:`pyramid.configuration.Configurator.add_view`) "by hand" multiple
+:meth:`pyramid.config.Configurator.add_route` (and/or
+:meth:`pyramid.config.Configurator.add_view`) "by hand" multiple
 times, making it more pleasant to register a collection of views as a single
 class when using :term:`url dispatch`.  The view handler machinery also
 introduces the concept of an ``action``, which is used as a :term:`view
@@ -27,7 +27,7 @@ during configuration.  After the view handler class is instantiated, a
 method on the instance is called. The method which is called depends on
 the view handler configuration.
 
-The :meth:`pyramid.configuration.Configurator.add_handler` method will
+The :meth:`pyramid.config.Configurator.add_handler` method will
 scan the handler class and automatically set up views for methods that
 are auto-exposed, or were decorated with the
 :class:`~pyramid.view.action` decorator. This decorator is used to setup
@@ -56,7 +56,7 @@ Here's an example view handler class:
             return {}
 
 An accompanying call to the
-:meth:`~pyramid.configuration.Configurator.add_handler` for the handler must
+:meth:`~pyramid.config.Configurator.add_handler` for the handler must
 be performed in order to register it with the system:
 
 .. code-block:: python
@@ -87,15 +87,22 @@ This will result one of the methods that are configured for the ``action`` of
 of the method is the same as the action name: 'index'. However, this
 need not be the case, as we will see below.
 
-Using :meth:`~pyramid.configuration.Configurator.add_handler`
+.. note::
+
+  Handler configuration may also be added to the system via :term:`ZCML` (see
+  :ref:`zcml_handler_configuration`).
+
+.. _using_add_handler:
+
+Using :meth:`~pyramid.config.Configurator.add_handler`
 -------------------------------------------------------------
 
-When calling :meth:`~pyramid.configuration.Configurator.add_handler`, an
+When calling :meth:`~pyramid.config.Configurator.add_handler`, an
 ``action`` is required in either the route pattern or as a keyword argument,
 but **cannot appear in both places**. A ``handler`` argument must also be
 supplied, which can be either a :term:`resource specification` or a Python
 reference to the handler class. Additional keyword arguments are passed
-directly through to :meth:`pyramid.configuration.Configurator.add_route`.
+directly through to :meth:`pyramid.config.Configurator.add_route`.
 
 For example:
 
@@ -106,10 +113,10 @@ For example:
                        handler='mypackage.handlers:MyHandler')
 
 In larger applications, it is advised to use a :term:`resource specification`
-with :meth:`~pyramid.configuration.Configurator.add_handler` to avoid having
+with :meth:`~pyramid.config.Configurator.add_handler` to avoid having
 to import every handler class.
 
-Multiple :meth:`~pyramid.configuration.Configurator.add_handler` calls can
+Multiple :meth:`~pyramid.config.Configurator.add_handler` calls can
 specify the same handler, to register specific route names for different
 handler/action combinations. For example:
 
@@ -130,7 +137,7 @@ The handler class specified can have a single class level attribute called
 ``None``. It's used to determine which method names will result in additional
 view configurations being registered.
 
-When :meth:`~pyramid.configuration.Configurator.add_handler` runs, every
+When :meth:`~pyramid.config.Configurator.add_handler` runs, every
 method in the handler class will be searched and a view registered if the
 method name matches the ``__autoexpose__`` regular expression, or if the
 method was decorated with :class:`~pyramid.view.action`.
@@ -170,12 +177,12 @@ Action Decorator
 
 The :class:`~pyramid.view.action` decorator registers view configuration
 information on the handler method, which is used by
-:meth:`~pyramid.configuration.Configurator.add_handler` to setup the view
+:meth:`~pyramid.config.Configurator.add_handler` to setup the view
 configuration.
 
 All keyword arguments are recorded, and passed to
-:meth:`~pyramid.configuration.Configurator.add_view`. Any valid keyword
-arguments for :meth:`~pyramid.configuration.Configurator.add_view` can thus be
+:meth:`~pyramid.config.Configurator.add_view`. Any valid keyword
+arguments for :meth:`~pyramid.config.Configurator.add_view` can thus be
 used with the :class:`~pyramid.view.action` decorator to further restrict when
 the view will be called.
 
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index ada96f897..10f463a17 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -29,7 +29,7 @@ class as the ``context`` of the view configuration.
 
    If your application uses :term:`imperative configuration`, you can
    replace the Not Found view by using the
-   :meth:`pyramid.configuration.Configurator.add_view` method to
+   :meth:`pyramid.config.Configurator.add_view` method to
    register an "exception view":
 
    .. code-block:: python
@@ -118,7 +118,7 @@ class as the ``context`` of the view configuration.
 
    If your application uses :term:`imperative configuration`, you can
    replace the Forbidden view by using the
-   :meth:`pyramid.configuration.Configurator.add_view` method to
+   :meth:`pyramid.config.Configurator.add_view` method to
    register an "exception view":
 
    .. code-block:: python
@@ -368,13 +368,13 @@ In the below, we assume it lives in a package named
 Lastly, if you're doing imperative configuration, and you'd rather do
 it after you've already constructed a :term:`configurator` it can also
 be registered via the
-:meth:`pyramid.configuration.Configurator.set_request_factory`
+:meth:`pyramid.config.Configurator.set_request_factory`
 method:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    from pyramid.request import Request
 
    class MyRequest(Request):
@@ -435,13 +435,13 @@ named ``mypackage.mymodule``.
 Lastly, if you're doing imperative configuration, and you'd rather do
 it after you've already constructed a :term:`configurator` it can also
 be registered via the
-:meth:`pyramid.configuration.Configurator.set_renderer_globals_factory`
+:meth:`pyramid.config.Configurator.set_renderer_globals_factory`
 method:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
 
    def renderer_globals_factory(system):
        return {'a':1}
@@ -474,7 +474,7 @@ that can be used for this purpose.  For example:
 
 An object of this type is sent as an event just before a :term:`renderer` is
 invoked (but *after* the application-level renderer globals factory added via
-:class:`pyramid.configuration.Configurator.set_renderer_globals_factory`, if
+:class:`pyramid.config.Configurator.set_renderer_globals_factory`, if
 any, has injected its own keys into the renderer globals dictionary).
 
 If a subscriber attempts to add a key that already exist in the renderer
@@ -659,7 +659,7 @@ performed, enabling you to set up the utility in advance:
    :linenos:
 
    from paste.httpserver import serve
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
 
    class UtilityImplementation:
 
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index 4acedc124..da77a28f0 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -40,7 +40,7 @@ configuration:
 .. code-block:: python
    :linenos:
 
-   # config is an instance of pyramid.configuration.Configurator
+   # config is an instance of pyramid.config.Configurator
 
    config.add_route('foobar', '{foo}/{bar}', view='myproject.views.foobar')
    config.add_route('bazbuz', '{baz}/{buz}', view='myproject.views.bazbuz')
@@ -50,7 +50,7 @@ and when that route is matched during a request, the view callable
 named by the ``view`` attribute is invoked.
 
 Typically, an application that uses only URL dispatch won't perform any calls
-to :meth:`pyramid.configuration.Configurator.add_view` in its startup code.
+to :meth:`pyramid.config.Configurator.add_view` in its startup code.
 
 Traversal Only
 ~~~~~~~~~~~~~~
@@ -61,7 +61,7 @@ declarations that look like this:
 .. code-block:: python
    :linenos:
 
-    # config is an instance of pyramid.configuration.Configurator
+    # config is an instance of pyramid.config.Configurator
 
     config.add_view('mypackage.views.foobar', name='foobar')
     config.add_view('mypackage.views.bazbuz', name='bazbuz')
@@ -72,7 +72,7 @@ When the above configuration is applied to an application, the
 be called when the URL ``/bazbuz`` is visited.
 
 Typically, an application that uses traversal exclusively won't perform any
-calls to :meth:`pyramid.configuration.Configurator.add_route` in its startup
+calls to :meth:`pyramid.config.Configurator.add_route` in its startup
 code.
 
 Hybrid Applications
@@ -158,11 +158,11 @@ match is straightforward.  When a route is matched:
   argument, the *global* :term:`root factory` will be called to
   generate a :term:`root` object.  The global root factory is the
   callable implied by the ``root_factory`` argument passed to
-  :class:`pyramid.configuration.Configurator` at application
+  :class:`pyramid.config.Configurator` at application
   startup time.
 
 - If a ``root_factory`` argument is not provided to the
-  :class:`pyramid.configuration.Configurator` at startup time, a
+  :class:`pyramid.config.Configurator` at startup time, a
   *default* root factory is used.  The default root factory is used to
   generate a root object.
 
@@ -263,7 +263,7 @@ thing to do.
 
   We could have also used our ``root_factory`` callable as the
   ``root_factory`` argument of the
-  :class:`pyramid.configuration.Configurator` constructor, instead
+  :class:`pyramid.config.Configurator` constructor, instead
   of associating it with a particular route inside the route's
   configuration.  Every hybrid route configuration that is matched but
   which does *not* name a ``factory`` attribute will use the use
@@ -305,13 +305,13 @@ invoked after a route matches:
    config.add_view('mypackage.views.myview', route_name='home')
 
 Note that the above call to
-:meth:`pyramid.configuration.Configurator.add_view` includes a ``route_name``
+:meth:`pyramid.config.Configurator.add_view` includes a ``route_name``
 argument.  View configurations that include a ``route_name`` argument are
 meant to associate a particular view declaration with a route, using the
 route's name, in order to indicate that the view should *only be invoked when
 the route matches*.
 
-Calls to :meth:`pyramid.configuration.Configurator.add_view` may pass a
+Calls to :meth:`pyramid.config.Configurator.add_view` may pass a
 ``route_name`` attribute, which refers to the value of an existing route's
 ``name`` argument.  In the above example, the route name is ``home``,
 referring to the name of the route defined above it.
@@ -362,7 +362,7 @@ Using the ``traverse`` Argument In a Route Definition
 
 Rather than using the ``*traverse`` remainder marker in a pattern, you
 can use the ``traverse`` argument to the
-:meth:`pyramid.configuration.Configurator.add_route` method.
+:meth:`pyramid.config.Configurator.add_route` method.
 
 When you use the ``*traverse`` remainder marker, the traversal path is
 limited to being the remainder segments of a request URL when a route
@@ -370,7 +370,7 @@ matches.  However, when you use the ``traverse`` argument or
 attribute, you have more control over how to compose a traversal path.
 
 Here's a use of the ``traverse`` pattern in a call to
-:meth:`pyramid.configuration.Configurator.add_route`:
+:meth:`pyramid.config.Configurator.add_route`:
 
 .. code-block:: python
    :linenos:
@@ -477,7 +477,7 @@ startup time.
    config.add_view('myproject.views.another', route_name='home')
 
 This is because the ``view`` argument to the
-:meth:`pyramid.configuration.Configurator.add_route` above is an *implicit*
+:meth:`pyramid.config.Configurator.add_route` above is an *implicit*
 default view when that route matches.  ``add_route`` calls don't *need* to
 supply a view attribute.  For example, this ``add_route`` call:
 
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 603b08cef..d8cc5cb1c 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -192,7 +192,7 @@ factory is best practice.  Using your own unique translation domain
 allows another person to reuse your application without needing to
 merge your translation files with his own.  Instead, he can just
 include your package's :term:`translation directory` via the
-:meth:`pyramid.configuration.Configurator.add_translation_dirs`
+:meth:`pyramid.config.Configurator.add_translation_dirs`
 method.
 
 .. note::
@@ -747,13 +747,13 @@ Localization-Related Deployment Settings
 A :app:`Pyramid` application will have a ``default_locale_name``
 setting.  This value represents the :term:`default locale name` used
 when the :term:`locale negotiator` returns ``None``.  Pass it to the
-:mod:`pyramid.configuration.Configurator` constructor at startup
+:mod:`pyramid.config.Configurator` constructor at startup
 time:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    config = Configurator(settings={'default_locale_name':'de'})
 
 You may alternately supply a ``default_locale_name`` via an
@@ -874,13 +874,13 @@ directory in the translation directory) within your :app:`Pyramid`
 application to be available to use for translation services.
 
 You can add a translation directory imperatively by using the
-:meth:`pyramid.configuration.Configurator.add_translation_dirs` during
+:meth:`pyramid.config.Configurator.add_translation_dirs` during
 application startup.  For example:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    config.begin()
    config.add_translation_dirs('my.application:locale/', 
                                'another.application:locale/')
@@ -888,7 +888,7 @@ application startup.  For example:
    config.end()
 
 A message catalog in a translation directory added via
-:meth:`pyramid.configuration.Configurator.add_translation_dirs`
+:meth:`pyramid.config.Configurator.add_translation_dirs`
 will be merged into translations from a message catalog added earlier
 if both translation directories contain translations for the same
 locale and :term:`translation domain`.
@@ -1000,17 +1000,17 @@ You may add your newly created locale negotiator to your application's
 configuration by passing an object which can act as the negotiator (or a
 :term:`dotted Python name` referring to the object) as the
 ``locale_negotiator`` argument of the
-:class:`pyramid.configuration.Configurator` instance during application
+:class:`pyramid.config.Configurator` instance during application
 startup.  For example:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    config = Configurator(locale_negotiator=my_locale_negotiator)
 
 Alternately, use the
-:meth:`pyramid.configuration.Configurator.set_locale_negotiator`
+:meth:`pyramid.config.Configurator.set_locale_negotiator`
 method.
 
 For example:
@@ -1018,7 +1018,7 @@ For example:
 .. code-block:: python
    :linenos:
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    config = Configurator()
    config.begin()
    config.set_locale_negotiator(my_locale_negotiator)
diff --git a/docs/narr/models.rst b/docs/narr/models.rst
index 20f443571..2c72e766d 100644
--- a/docs/narr/models.rst
+++ b/docs/narr/models.rst
@@ -9,14 +9,14 @@ omnipresent in :app:`Pyramid`:
   willing to walk over when :term:`traversal` is used.
 
 - The ``context`` and ``containment`` arguments to
-  :meth:`pyramid.configuration.Configurator.add_view` often
+  :meth:`pyramid.config.Configurator.add_view` often
   reference a model class.
 
 - A :term:`root factory` returns a model instance.
 
 - A model instance is generated as a result of :term:`url dispatch`
   (see the ``factory`` argument to
-  :meth:`pyramid.configuration.Configurator.add_route`).
+  :meth:`pyramid.config.Configurator.add_route`).
 
 - A model instance is exposed to :term:`view` code as the
   :term:`context` of a view.
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 6036feb90..f8a9017db 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -754,7 +754,7 @@ also informs Python that the directory which contains it is a *package*.
    :linenos:
 
 #. Line 1 imports the :term:`Configurator` class from
-   :mod:`pyramid.configuration` that we use later.
+   :mod:`pyramid.config` that we use later.
 
 #. Line 2 imports the ``get_root`` function from
    :mod:`myproject.models` that we use later.
@@ -915,7 +915,7 @@ made for you by any paster template, you can decide to lay your code out any
 way you see fit.
 
 For example, the configuration method named
-:meth:`~pyramid.configuration.Configurator.add_view` requires you to pass a
+:meth:`~pyramid.config.Configurator.add_view` requires you to pass a
 :term:`dotted Python name` or a direct object reference as the class or
 function to be used as a view.  By default, the ``pyramid_starter`` paster
 template would have you add view functions to the ``views.py`` module in your
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index 3ff8af90b..c87157472 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -114,40 +114,6 @@ following kinds of resources defined in any Python package:
 - Any other resource (or set of resources) addressed by code that uses
   the setuptools :term:`pkg_resources` API.
 
-Usually, overriding a resource in an existing application means
-performing the following steps:
-
-- Create a new Python package.  The easiest way to do this is to
-  create a new :app:`Pyramid` application using the "paster"
-  template mechanism.  See :ref:`creating_a_project` for more
-  information.
-
-- Install the new package into the same Python environment as the
-  original application (e.g. ``python setup.py develop`` or ``python
-  setup.py install``).
-
-- Change the ``configure.zcml`` in the new package to include one or
-  more ``resource`` ZCML directives (see :ref:`resource_directive`
-  below).  The new package's ``configure.zcml`` should then include
-  the original :app:`Pyramid` application's ``configure.zcml`` via
-  an include statement, e.g.  ``<include
-  package="theoriginalpackage"/>``.
-
-- Add override resources to the package as necessary.
-
-- Change the Paste ``.ini`` file that starts up the original
-  application.  Add a ``configure_zcml`` statement within the
-  application's section in the file which points at your *new*
-  package's ``configure.zcml`` file.  See :ref:`environment_chapter`
-  for more information about this setting.
-
-Note that overriding resources is not the only way to extend or modify
-the behavior of an existing :app:`Pyramid` application.  A "heavier
-hammer" way to do the same thing is explained in
-:ref:`extending_chapter`.  The heavier hammer way allows you to
-replace a :term:`view` wholesale rather than resources that might be
-used by a view.
-
 .. index::
    single: override_resource
 
@@ -157,7 +123,7 @@ The ``override_resource`` API
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 An individual call to
-:meth:`pyramid.configuration.Configurator.override_resource` can
+:meth:`pyramid.config.Configurator.override_resource` can
 override a single resource.  For example:
 
 .. ignore-next-block
@@ -213,7 +179,7 @@ will need to register two overrides.
 The package name in a specification may start with a dot, meaning that
 the package is relative to the package in which the configuration
 construction file resides (or the ``package`` argument to the
-:class:`pyramid.configuration.Configurator` class construction).
+:class:`pyramid.config.Configurator` class construction).
 For example:
 
 .. ignore-next-block
@@ -245,7 +211,7 @@ The ``resource`` ZCML Directive
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Instead of using
-:meth:`pyramid.configuration.Configurator.override_resource` during
+:meth:`pyramid.config.Configurator.override_resource` during
 :term:`imperative configuration`, an equivalent can be used to perform
 all the tasks described above within :term:`ZCML`.  The ZCML
 ``resource`` tag is a frontend to using ``override_resource``.
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 2c696772a..5edbc3ec3 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -63,14 +63,14 @@ Enabling an Authorization Policy Imperatively
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Passing an ``authorization_policy`` argument to the constructor of the
-:class:`pyramid.configuration.Configurator` class enables an
+:class:`pyramid.config.Configurator` class enables an
 authorization policy.
 
 You must also enable an :term:`authentication policy` in order to
 enable the authorization policy.  This is because authorization, in
 general, depends upon authentication.  Use the
 ``authentication_policy`` argument to the
-:class:`pyramid.configuration.Configurator` class during
+:class:`pyramid.config.Configurator` class during
 application setup to specify an authentication policy.
 
 For example:
@@ -79,7 +79,7 @@ For example:
 .. code-block:: python
    :linenos:
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    from pyramid.authentication import AuthTktAuthenticationPolicy
    from pyramid.authorization import ACLAuthorizationPolicy
    authentication_policy = AuthTktAuthenticationPolicy('seekrit')
@@ -127,12 +127,12 @@ name permissions whatever you like.
 
 For example, the following view declaration protects the view named
 ``add_entry.html`` when invoked against a ``Blog`` context with the ``add``
-permission using the :meth:`pyramid.configuration.Configurator.add_view` API:
+permission using the :meth:`pyramid.config.Configurator.add_view` API:
 
 .. code-block:: python
    :linenos:
 
-   # config is an instance of pyramid.configuration.Configurator
+   # config is an instance of pyramid.config.Configurator
 
    config.add_view('mypackage.views.blog_entry_add_view',
                    name='add_entry.html', 
@@ -183,10 +183,10 @@ These APIs are in support of configuring a default permission for an
 application:
 
 - The ``default_permission`` constructor argument to the
-  :mod:`pyramid.configuration.Configurator` constructor.
+  :mod:`pyramid.config.Configurator` constructor.
 
 - The
-  :meth:`pyramid.configuration.Configurator.set_default_permission`
+  :meth:`pyramid.config.Configurator.set_default_permission`
   method.
 
 - The :ref:`default_permission_directive` ZCML directive.
@@ -582,7 +582,7 @@ that implements the following interface:
            current user on subsequent requests. """
 
 After you do so, you can pass an instance of such a class into the
-:class:`pyramid.configuration.Configurator` class at configuration
+:class:`pyramid.config.Configurator` class at configuration
 time as ``authentication_policy`` to use it.
 
 .. index::
@@ -626,5 +626,5 @@ following interface:
                 permission """
 
 After you do so, you can pass an instance of such a class into the
-:class:`pyramid.configuration.Configurator` class at configuration
+:class:`pyramid.config.Configurator` class at configuration
 time as ``authorization_policy`` to use it.
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index eea035975..8547a92cc 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -35,7 +35,7 @@ tampered with.
 
 You can configure this session factory in your :app:`Pyramid`
 application by using the ``session_factory`` argument to the
-:class:`pyramid.configuration.Configurator` class:
+:class:`pyramid.config.Configurator` class:
 
 .. code-block:: python
    :linenos:
@@ -43,7 +43,7 @@ application by using the ``session_factory`` argument to the
    from pyramid.session import UnencryptedCookieSessionFactoryConfig
    my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet')
    
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    config = Configurator(session_factory = my_session_factory)
 
 .. warning:: 
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 9103bf20f..2199f2e59 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -95,7 +95,7 @@ press ``return`` after running ``paster serve development.ini``.
    'debug_templates':'true', 'default_locale_name':'en'}``.
 
 #. The ``app`` function first constructs a
-   :class:`pyramid.configuration.Configurator` instance, passing
+   :class:`pyramid.config.Configurator` instance, passing
    ``get_root`` to it as its ``root_factory`` argument, and
    ``settings`` dictionary captured via the ``**settings`` kwarg as
    its ``settings`` argument.
@@ -112,12 +112,12 @@ press ``return`` after running ``paster serve development.ini``.
    'default_locale_name':'en'}``.
 
 #. The ``app`` function then calls various methods on the an instance of the
-   class :class:`pyramid.configuration.Configurator` method.  The intent of
+   class :class:`pyramid.config.Configurator` method.  The intent of
    calling these methods is to populate an :term:`application registry`,
    which represents the :app:`Pyramid` configuration related to the
    application.
 
-#. The :meth:`pyramid.configuration.Configurator.make_wsgi_app` method is
+#. The :meth:`pyramid.config.Configurator.make_wsgi_app` method is
    called.  The result is a :term:`router` instance.  The router is
    associated with the :term:`application registry` implied by the
    configurator previously populated by other methods run against the
@@ -146,7 +146,7 @@ Deployment Settings
 -------------------
 
 Note that an augmented version of the values passed as ``**settings`` to the
-:class:`pyramid.configuration.Configurator` constructor will be available in
+:class:`pyramid.config.Configurator` constructor will be available in
 :app:`Pyramid` :term:`view callable` code as ``request.registry.settings``.
 You can create objects you wish to access later from view code, and put them
 into the dictionary you pass to the configurator as ``settings``.  They will
diff --git a/docs/narr/static.rst b/docs/narr/static.rst
index bed922953..172fb08d4 100644
--- a/docs/narr/static.rst
+++ b/docs/narr/static.rst
@@ -13,17 +13,17 @@ how to configure :app:`Pyramid` to do so.
 Serving Static Resources
 ------------------------
 
-Use the :meth:`pyramid.configuration.Configurator.add_static_view` to
+Use the :meth:`pyramid.config.Configurator.add_static_view` to
 instruct :app:`Pyramid` to serve static resources such as JavaScript and CSS
 files. This mechanism makes static files available at a name relative to the
 application root URL, e.g. ``/static``.
 
 Note that the ``path`` provided to
-:meth:`pyramid.configuration.Configurator.add_static_view` may be a fully
+:meth:`pyramid.config.Configurator.add_static_view` may be a fully
 qualified :term:`resource specification`, or an *absolute path*.  
 
 Here's an example of a use of
-:meth:`pyramid.configuration.Configurator.add_static_view` that will serve
+:meth:`pyramid.config.Configurator.add_static_view` that will serve
 files up under the ``/static`` URL from the ``/var/www/static`` directory of
 the computer which runs the :app:`Pyramid` application using an absolute
 path.
@@ -31,11 +31,11 @@ path.
 .. code-block:: python
    :linenos:
 
-   # config is an instance of pyramid.configuration.Configurator
+   # config is an instance of pyramid.config.Configurator
    config.add_static_view(name='static', path='/var/www/static')
 
 Here's an example of
-:meth:`pyramid.configuration.Configurator.add_static_view` that will serve
+:meth:`pyramid.config.Configurator.add_static_view` that will serve
 files up under the ``/static`` URL from the ``a/b/c/static`` directory of the
 Python package named ``some_package`` using a fully qualified :term:`resource
 specification`.
@@ -43,50 +43,70 @@ specification`.
 .. code-block:: python
    :linenos:
 
-   # config is an instance of pyramid.configuration.Configurator
+   # config is an instance of pyramid.config.Configurator
    config.add_static_view(name='static', path='some_package:a/b/c/static')
 
-Whether you use a fully qualified resource specification, or an absolute
-path for ``path`` in the directive, it specifies a filesystem directory
-where static files will be served from. Once you place files there, you
-will then be able to view them from a browser at URLs prefixed with the
-directive's ``name``.  For instance, if the ``static`` directive's
-``name`` is ``static``, and the static directive's ``path`` is
-``/path/to/static/dir``, ``http://localhost:6543/static/foo.js`` will
-serve the file ``/path/to/static/dir/foo.js``.  The static directory may
-contain subdirectories recursively, and any subdirectories may hold
-files; these will be resolved by the static view as you would expect.
-
-The ``name`` argument of the call to
-:meth:`pyramid.configuration.Configurator.add_static_view` can be either
-a *view name*, or a *URL*.  In the above examples, the ``name`` argument
-is a view name.  When ``name`` is a *URL* (or any string with a slash
-(``/``) in it), static resources can be served from an external
-webserver.  In this mode, the ``name`` is used as the URL prefix when
-generating a URL using the :func:`pyramid.url.static_url` function.
-
-For example, :meth:`pyramid.configuration.Configurator.add_static_view` may
+Whether you use for ``path`` a fully qualified resource specification, or an
+absolute path, when you place your static files on the filesystem in the
+directory represented as the ``path`` of the directive, you will then be able
+to view the static files in this directory via a browser at URLs prefixed
+with the directive's ``name``.  For instance if the ``static`` directive's
+``name`` is ``static`` and the static directive's ``path`` is
+``/path/to/static``, ``http://localhost:6543/static/foo.js`` will return the
+file ``/path/to/static/dir/foo.js``.  The static directory may contain
+subdirectories recursively, and any subdirectories may hold files; these will
+be resolved by the static view as you would expect.
+
+While the ``path`` argument can be a number of different things, the ``name``
+argument of the call to
+:meth:`pyramid.config.Configurator.add_static_view` can also be one of
+a number of things: a *view name* or a *URL*.  The above examples have shown
+usage of the ``name`` argument as a view name.  When ``name`` is a *URL* (or
+any string with a slash (``/``) in it), static resources can be served from
+an external webserver.  In this mode, the ``name`` is used as the URL prefix
+when generating a URL using :func:`pyramid.url.static_url`.
+
+.. note::
+
+   Using :func:`pyramid.url.static_url` in conjunction with a
+   :meth:`pyramid.config.Configurator.add_static_view` makes it
+   possible to put static media on a separate webserver during production (if
+   the ``name`` argument to
+   :meth:`pyramid.config.Configurator.add_static_view` is a URL),
+   while keeping static media package-internal and served by the development
+   webserver during development (if the ``name`` argument to
+   :meth:`pyramid.config.Configurator.add_static_view` is a view
+   name).  To create such a circumstance, we suggest using the
+   :attr:`pyramid.registry.Registry.settings` API in conjunction with a
+   setting in the application ``.ini`` file named ``media_location``.  Then
+   set the value of ``media_location`` to either a view name or a URL
+   depending on whether the application is being run in development or in
+   production (use a different `.ini`` file for production than you do for
+   development).  This is just a suggestion for a pattern; any setting name
+   other than ``media_location`` could be used.
+
+For example, :meth:`pyramid.config.Configurator.add_static_view` may
 be fed a ``name`` argument which is ``http://example.com/images``:
 
 .. code-block:: python
    :linenos:
 
-   # config is an instance of pyramid.configuration.Configurator
+   # config is an instance of pyramid.config.Configurator
    config.add_static_view(name='http://example.com/images', 
                           path='mypackage:images')
 
-Because :meth:`pyramid.configuration.Configurator.add_static_view` is
+Because :meth:`pyramid.config.Configurator.add_static_view` is
 provided with a ``name`` argument that is the URL prefix
 ``http://example.com/images``, subsequent calls to
 :func:`pyramid.url.static_url` with paths that start with the ``path``
-argument passed to :meth:`pyramid.configuration.Configurator.add_static_view`
+argument passed to :meth:`pyramid.config.Configurator.add_static_view`
 will generate a URL something like ``http://example.com/images/logo.png``.  The
 external webserver listening on ``example.com`` must be itself configured to
 respond properly to such a request.  The :func:`pyramid.url.static_url` API
 is discussed in more detail later in this chapter.
 
 The :ref:`static_directive` ZCML directive offers an declarative equivalent
-to :meth:`pyramid.configuration.Configurator.add_static_view`.  Use of the
+to :meth:`pyramid.config.Configurator.add_static_view`.  Use of the
 :ref:`static_directive` ZCML directive is completely equivalent to using
 imperative configuration for the same purpose.
 
@@ -118,7 +138,7 @@ imperative configuration for the same purpose.
 Generating Static Resource URLs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When a :meth:`pyramid.configuration.Configurator.add_static_view` method is
+When a :meth:`pyramid.config.Configurator.add_static_view` method is
 used to register a static resource directory, a special helper API named
 :func:`pyramid.url.static_url` can be used to generate the appropriate URL for a
 package resource that lives in one of the directories named by the static
@@ -168,7 +188,7 @@ properly after the rename.
 
 URLs may also be generated by :func:`pyramid.url.static_url` to static
 resources that live *outside* the :app:`Pyramid` application.  This will
-happen when the :meth:`pyramid.configuration.Configurator.add_static_view`
+happen when the :meth:`pyramid.config.Configurator.add_static_view`
 API associated with the path fed to :func:`pyramid.url.static_url` is a *URL*
 instead of a view name.  For example, the ``name`` argument may be
 ``http://example.com`` while the the ``path`` given may be
@@ -224,7 +244,7 @@ your application root as below.
    (e.g. ``anotherpackage:some/subdirectory``).
  
 Subsequently, you may wire this view up to be accessible as ``/static`` using
-the :mod:`pyramid.configuration.Configurator.add_view` method in your
+the :mod:`pyramid.config.Configurator.add_view` method in your
 application's startup code against either the class or interface that
 represents your root object.
 
diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst
index 9b04d5914..f540fa255 100644
--- a/docs/narr/threadlocals.rst
+++ b/docs/narr/threadlocals.rst
@@ -75,8 +75,8 @@ defined entirely by the behavior of a pyramid :term:`Router`.
 
 However, during unit testing, no Router code is ever invoked, and the
 definition of "current" is defined by the boundary between calls to
-the :meth:`pyramid.configuration.Configurator.begin` and
-:meth:`pyramid.configuration.Configurator.end` methods (or between
+the :meth:`pyramid.config.Configurator.begin` and
+:meth:`pyramid.config.Configurator.end` methods (or between
 calls to the :func:`pyramid.testing.setUp` and
 :func:`pyramid.testing.tearDown` functions).  These functions push
 and pop the threadlocal stack when the system is under test.  See
@@ -156,7 +156,7 @@ place to use the ``get_current_request``.
 Use of the :func:`pyramid.threadlocal.get_current_registry`
 function should be limited to testing scenarios.  The registry made
 current by use of the
-:meth:`pyramid.configuration.Configurator.begin` method during a
+:meth:`pyramid.config.Configurator.begin` method during a
 test (or via :func:`pyramid.testing.setUp`) when you do not pass
 one in is available to you via this API.
 
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 2a10a5022..01729c4bd 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -180,7 +180,7 @@ named ``config``:
    config = Configurator(root_factory=Root)
 
 Using the ``root_factory`` argument to a
-:class:`pyramid.configuration.Configurator` constructor tells your
+:class:`pyramid.config.Configurator` constructor tells your
 :app:`Pyramid` application to call this root factory to generate a
 root object whenever a request enters the application.  This root
 factory is also known as the global root factory.  A root factory can
diff --git a/docs/narr/unittesting.rst b/docs/narr/unittesting.rst
index 26035726b..3c31f69b6 100644
--- a/docs/narr/unittesting.rst
+++ b/docs/narr/unittesting.rst
@@ -79,9 +79,18 @@ If your code uses these ``get_current_*`` functions or calls
 :app:`Pyramid` code which uses ``get_current_*`` functions, you
 will need to construct a :term:`Configurator` and call its ``begin``
 method within the ``setUp`` method of your unit test and call the same
-configurator's ``end`` method within the ``tearDown`` method of your
+Configurator's ``end`` method within the ``tearDown`` method of your
 unit test.
 
+We'll also instruct the Configurator we use during testing to *autocommit*.
+Normally when a Configurator is used by an application, it defers performing
+any "real work" until its ``.commit`` method is called (often implicitly by
+the :meth:`pyramid.config.Configurator.make_wsgi_app` method).  Passing
+``autocommit=True`` to the Configurator constructor causes the Configurator
+to perform all actions implied by methods called on it immediately, which is
+more convenient for unit-testing purposes than needing to call
+:meth:`pyramid.config.Configurator.commit` in each test.
+
 The use of a Configurator and its ``begin`` and ``end`` methods allows
 you to supply each unit test method in a test case with an environment
 that has an isolated registry and an isolated request for the duration
@@ -91,11 +100,11 @@ of a single test.  Here's an example of using this feature:
    :linenos:
 
    import unittest
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
 
    class MyTest(unittest.TestCase):
        def setUp(self):
-           self.config = Configurator()
+           self.config = Configurator(autocommit=True)
            self.config.begin()
 
        def tearDown(self):
@@ -103,13 +112,12 @@ of a single test.  Here's an example of using this feature:
 
 The above will make sure that
 :func:`pyramid.threadlocal.get_current_registry` will return the
-:term:`application registry` associated with the ``config``
-Configurator instance when
-:func:`pyramid.threadlocal.get_current_registry` is called in a
-test case method attached to ``MyTest``.  Each test case method
-attached to ``MyTest`` will use an isolated registry.
+:term:`application registry` associated with the ``config`` Configurator
+instance when :func:`pyramid.threadlocal.get_current_registry` is called in a
+test case method attached to ``MyTest``.  Each test case method attached to
+``MyTest`` will use an isolated registry.
 
-The :meth:`pyramid.configuration.Configurator.begin` method accepts
+The :meth:`pyramid.config.Configurator.begin` method accepts
 various arguments that influence the code run during the test.  See
 the :ref:`configuration_module` chapter for information about the API
 of a :term:`Configurator`, including its ``begin`` and ``end``
@@ -118,19 +126,19 @@ methods.
 If you also want to make :func:`pyramid.get_current_request`
 return something other than ``None`` during the course of a single
 test, you can pass a :term:`request` object into the
-:meth:`pyramid.configuration.Configurator.begin` method of the
+:meth:`pyramid.config.Configurator.begin` method of the
 Configurator within the ``setUp`` method of your test:
 
 .. code-block:: python
    :linenos:
 
    import unittest
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    from pyramid import testing
 
    class MyTest(unittest.TestCase):
        def setUp(self):
-           self.config = Configurator()
+           self.config = Configurator(autocommit=True)
            request = testing.DummyRequest()
            self.config.begin(request=request)
 
@@ -150,17 +158,16 @@ construct than a "real" :app:`Pyramid` request object.
 What?
 ~~~~~
 
-Thread local data structures are always a bit confusing, especially
-when they're used by frameworks.  Sorry.  So here's a rule of thumb:
-if you don't *know* whether you're calling code that uses the
+Thread local data structures are always a bit confusing, especially when
+they're used by frameworks.  Sorry.  So here's a rule of thumb: if you don't
+*know* whether you're calling code that uses the
 :func:`pyramid.threadlocal.get_current_registry` or
-:func:`pyramid.threadlocal.get_current_request` functions, or you
-don't care about any of this, but you still want to write test code,
-just always create a Configurator instance and call its ``begin``
-method within the ``setUp`` of a unit test, then subsequently call its
-``end`` method in the test's ``tearDown``.  This won't really hurt
-anything if the application you're testing does not call any
-``get_current*`` function.
+:func:`pyramid.threadlocal.get_current_request` functions, or you don't care
+about any of this, but you still want to write test code, just always create
+an autocommitting Configurator instance and call its ``begin`` method within
+the ``setUp`` of a unit test, then subsequently call its ``end`` method in
+the test's ``tearDown``.  This won't really hurt anything if the application
+you're testing does not call any ``get_current*`` function.
 
 .. index::
    single: pyramid.testing
@@ -196,7 +203,7 @@ a :term:`application registry` using :term:`configuration declaration`
 calls made against a :term:`Configurator` (sometimes deferring to the
 application's ``configure.zcml`` :term:`ZCML` file via ``load_zcml``).
 But if this application registry is not created and populated
-(e.g. with an :meth:`pyramid.configuration.Configurator.add_view`
+(e.g. with an :meth:`pyramid.config.Configurator.add_view`
 :term:`configuration declaration` or ``view`` declarations in
 :term:`ZCML`), like when you invoke application code via a unit test,
 :app:`Pyramid` API functions will tend to fail.
@@ -213,12 +220,12 @@ used the testing API.
    :linenos:
 
    import unittest
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    from pyramid import testing
 
    class MyTest(unittest.TestCase):
        def setUp(self):
-           self.config = Configurator()
+           self.config = Configurator(autocommit=True)
            self.config.begin()
 
        def tearDown(self):
@@ -249,7 +256,7 @@ The first test method, ``test_view_fn_not_submitted`` tests the
 ``view_fn`` function in the case that no "form" values (represented by
 request.params) have been submitted.  Its first line registers a
 "dummy template renderer" named ``templates/show.pt`` via the
-:meth:`pyramid.configuration.Configurator.testing_add_renderer`
+:meth:`pyramid.config.Configurator.testing_add_renderer`
 method; this method returns a
 :class:`pyramid.testing.DummyTemplateRenderer` instance which we
 hang on to for later.
@@ -281,10 +288,10 @@ attribute is ``Yo``, as this is what is expected of the view function
 in the branch it's testing.
 
 Note that the test calls the
-:meth:`pyramid.configuration.Configurator.begin` method in its
+:meth:`pyramid.config.Configurator.begin` method in its
 ``setUp`` method and the ``end`` method of the same in its
 ``tearDown`` method.  If you use any of the
-:class:`pyramid.configuration.Configurator` APIs during testing, be
+:class:`pyramid.config.Configurator` APIs during testing, be
 sure to use this pattern in your test case's ``setUp`` and
 ``tearDown``; these methods make sure you're using a "fresh"
 :term:`application registry` per test run.
@@ -335,7 +342,7 @@ environment.
 
    import unittest
 
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
    from pyramid import testing
 
    class ViewIntegrationTests(unittest.TestCase):
@@ -345,7 +352,7 @@ environment.
            (including dependent registrations for pyramid itself).
            """
            import myapp
-           self.config = Configurator(package=myapp)
+           self.config = Configurator(package=myapp, autocommit=True)
            self.config.begin()
            self.config.load_zcml('myapp:configure.zcml')
 
@@ -367,7 +374,7 @@ environment.
                                                    str(len(body))))
 
 Unless you cannot avoid it, you should prefer writing unit tests that
-use the :class:`pyramid.configuration.Configurator` API to set up
+use the :class:`pyramid.config.Configurator` API to set up
 the right "mock" registrations rather than creating an integration
 test.  Unit tests will run faster (because they do less for each test)
 and the result of a unit test is usually easier to make assertions
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 209c4f4d2..c84a5ca06 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -35,7 +35,7 @@ a more natural fit for creating an application that manipulates "flat"
 data.
 
 The presence of calls to the
-:meth:`pyramid.configuration.Configurator.add_route` method in imperative
+:meth:`pyramid.config.Configurator.add_route` method in imperative
 configuration within your application is a sign that you're using :term:`URL
 dispatch`.
 
@@ -81,7 +81,7 @@ predicate` parameters, and a set of :term:`view` parameters.
 Configuring a Route via The ``add_route`` Configurator Method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :meth:`pyramid.configuration.Configurator.add_route` method
+The :meth:`pyramid.config.Configurator.add_route` method
 adds a single :term:`route configuration` to the :term:`application
 registry`.  Here's an example:
 
@@ -89,7 +89,7 @@ registry`.  Here's an example:
 .. code-block:: python
 
    # "config" below is presumed to be an instance of the
-   # pyramid.configuration.Configurator class; "myview" is assumed
+   # pyramid.config.Configurator class; "myview" is assumed
    # to be a "view callable" function
    from views import myview
    config.add_route('myroute', '/prefix/{one}/{two}', view=myview)
@@ -118,7 +118,7 @@ Here's an example route configuration that references a view callable:
    :linenos:
 
    # "config" below is presumed to be an instance of the
-   # pyramid.configuration.Configurator class; "myview" is assumed
+   # pyramid.config.Configurator class; "myview" is assumed
    # to be a "view callable" function
    from myproject.views import myview
    config.add_route('myroute', '/prefix/{one}/{two}', view=myview)
@@ -130,7 +130,7 @@ rather than an actual callable:
    :linenos:
 
    # "config" below is presumed to be an instance of the
-   # pyramid.configuration.Configurator class; "myview" is assumed
+   # pyramid.config.Configurator class; "myview" is assumed
    # to be a "view callable" function
    from myproject.views import myview
    config.add_route('myroute', '/prefix/{one}/{two}', 
@@ -377,7 +377,7 @@ they are added to the application at startup time.  This is unlike
 :term:`traversal`, which depends on emergent behavior which happens as
 a result of traversing a graph.
 
-For routes added via the :mod:`pyramid.configuration.Configurator.add_route`
+For routes added via the :mod:`pyramid.config.Configurator.add_route`
 method, the order that routes are evaluated is the order in which they are
 added to the configuration imperatively.
 
@@ -657,7 +657,7 @@ Custom Route Predicates
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Each of the predicate callables fed to the ``custom_predicates`` argument of
-:meth:`pyramid.configuration.Configurator.add_route` must be a callable
+:meth:`pyramid.config.Configurator.add_route` must be a callable
 accepting two arguments.  The first argument passed to a custom predicate is
 a dictionary conventionally named ``info``.  The second argument is the
 current :term:`request` object.
@@ -692,7 +692,7 @@ generate a predicate function named ``num_one_two_or_three``, which
 ensures that the ``num`` segment is one of the values ``one``,
 ``two``, or ``three`` , and use the result as a custom predicate by
 feeding it inside a tuple to the ``custom_predicates`` argument to
-:meth:`pyramid.configuration.Configurator.add_route`.
+:meth:`pyramid.config.Configurator.add_route`.
 
 A custom route predicate may also *modify* the ``match`` dictionary.
 For instance, a predicate might do some type conversion of values:
@@ -968,7 +968,7 @@ factory` configured at startup time (the ``root_factory`` argument to the
 :term:`Configurator` used to configure the application).
 
 You can override this behavior by passing in a ``factory`` argument to the
-:meth:`pyramid.configuration.Configurator.add_route` method for a particular
+:meth:`pyramid.config.Configurator.add_route` method for a particular
 route.  The ``factory`` should be a callable that accepts a :term:`request`
 and returns an instance of a class that will be the context used by the view.
 
@@ -1033,7 +1033,7 @@ Matching the Root URL
 
 It's not entirely obvious how to use a route pattern to match the root URL
 ("/").  To do so, give the empty string as a pattern in a call to
-:meth:`pyramid.configuration.Configurator.add_route`:
+:meth:`pyramid.config.Configurator.add_route`:
 
 .. code-block:: python
    :linenos:
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index d30fcdae5..8a689be21 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -338,7 +338,7 @@ within :ref:`the_response`.
 
 View configuration can vary the renderer associated with a view callable via
 the ``renderer`` attribute.  For example, this call to
-:meth:`pyramid.configuration.Configurator.add_view` associates the ``json``
+:meth:`pyramid.config.Configurator.add_view` associates the ``json``
 renderer with a view callable:
 
 .. code-block:: python
@@ -469,7 +469,7 @@ contain values serializable by :func:`json.dumps`.
 
 You can configure a view to use the JSON renderer by naming ``json`` as the
 ``renderer`` argument of a view configuration, e.g. by using
-:meth:`pyramid.configuration.Configurator.add_view`:
+:meth:`pyramid.config.Configurator.add_view`:
 
 .. code-block:: python
    :linenos:
@@ -537,7 +537,7 @@ renderer:
 .. code-block:: python
    :linenos:
 
-    # config is an instance of pyramid.configuration.Configurator
+    # config is an instance of pyramid.config.Configurator
 
     config.add_view('myproject.views.hello_world',
                     name='hello',
@@ -588,7 +588,7 @@ Here's an example view configuration which uses a relative path:
 .. code-block:: python
    :linenos:
 
-    # config is an instance of pyramid.configuration.Configurator
+    # config is an instance of pyramid.config.Configurator
 
     config.add_view('myproject.views.hello_world',
                     name='hello',
@@ -689,7 +689,7 @@ override an existing :term:`renderer factory`, and which add a new renderer
 factory.
 
 Renderers can be registered imperatively using the
-:meth:`pyramid.configuration.Configurator.add_renderer` API.
+:meth:`pyramid.config.Configurator.add_renderer` API.
 
 .. note:: The tasks described in this section can also be performed via
    :term:`declarative configuration`.  See
@@ -768,12 +768,12 @@ There are essentially two different kinds of renderer factories:
    ``my.package`` Python :term:`package`.
 
 Here's an example of the registration of a simple renderer factory via
-:meth:`pyramid.configuration.Configurator.add_renderer`:
+:meth:`pyramid.config.Configurator.add_renderer`:
 
 .. code-block:: python
    :linenos:
 
-   # config is an instance of pyramid.configuration.Configurator
+   # config is an instance of pyramid.config.Configurator
 
    config.add_renderer(name='amf', factory='my.package.MyAMFRenderer')
 
@@ -836,7 +836,7 @@ to the ``Jinja2Renderer`` constructor will be the full value that was
 set as ``renderer=`` in the view configuration.
 
 See also :ref:`renderer_directive` and
-:meth:`pyramid.configuration.Configurator.add_renderer`.
+:meth:`pyramid.config.Configurator.add_renderer`.
 
 Overriding an Existing Renderer
 +++++++++++++++++++++++++++++++
@@ -845,7 +845,7 @@ You can associate more than one filename extension with the same existing
 renderer implementation as necessary if you need to use a different file
 extension for the same kinds of templates.  For example, to associate the
 ``.zpt`` extension with the Chameleon ZPT renderer factory, use the
-:meth:`pyramid.configuration.Configurator.add_renderer` method:
+:meth:`pyramid.config.Configurator.add_renderer` method:
 
 .. code-block:: python
    :linenos:
@@ -1145,8 +1145,8 @@ View configuration is performed in one of these ways:
   object as per :class:`pyramid.view.view_config` and
   :ref:`mapping_views_using_a_decorator_section`.
 
-- by using the :meth:`pyramid.configuration.Configurator.add_view`
-  method as per :meth:`pyramid.configuration.Configurator.add_view`
+- by using the :meth:`pyramid.config.Configurator.add_view`
+  method as per :meth:`pyramid.config.Configurator.add_view`
   and :ref:`mapping_views_using_imperative_config_section`.
 
 Both of these mechanisms is completely equivalent to the other.
@@ -1157,7 +1157,7 @@ Both of these mechanisms is completely equivalent to the other.
 
 A view configuration might also be performed by virtue of :term:`route
 configuration`.  View configuration via route configuration is performed by
-using the :meth:`pyramid.configuration.Configurator.add_route` method to
+using the :meth:`pyramid.config.Configurator.add_route` method to
 create a route with a ``view`` argument.
 
 .. note:: ZCML users can use :ref:`route_directive` to perform the same task.
@@ -1458,7 +1458,7 @@ configuration`, like ZCML, but in decorator form.
 :class:`pyramid.view.view_config` can be used to associate :term:`view
 configuration` information -- as done via the equivalent imperative code or
 ZCML -- with a function that acts as a :app:`Pyramid` view callable.  All
-arguments to the :meth:`pyramid.configuration.Configurator.add_view` method
+arguments to the :meth:`pyramid.config.Configurator.add_view` method
 (save for the ``view`` argument) are available in decorator form and mean
 precisely the same thing.
 
@@ -1512,13 +1512,13 @@ perform view configuration.  All that the decorator does is "annotate"
 the function with your configuration declarations, it doesn't process
 them. To make :app:`Pyramid` process your
 :class:`pyramid.view.view_config` declarations, you *must* do use the
-``scan`` method of a :class:`pyramid.configuration.Configurator`:
+``scan`` method of a :class:`pyramid.config.Configurator`:
 
 .. code-block:: python
    :linenos:
 
    # config is assumed to be an instance of the
-   # pyramid.configuration.Configurator class
+   # pyramid.config.Configurator class
    config.scan()
 
 .. note:: See :ref:`zcml_scanning` for information about how to invoke a scan
@@ -1529,7 +1529,7 @@ about what happens when code is scanned for configuration declarations
 resulting from use of decorators like :class:`pyramid.view.view_config`.
 
 See :ref:`configuration_module` for additional API arguments to the
-:meth:`pyramid.configuration.Configurator.scan` method.  For example, the
+:meth:`pyramid.config.Configurator.scan` method.  For example, the
 method allows you to supply a ``package`` argument to better control exactly
 *which* code will be scanned.
 
@@ -1661,7 +1661,7 @@ equivalently as the below:
 View Configuration Using the ``add_view`` Method of a Configurator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :meth:`pyramid.configuration.Configurator.add_view` method
+The :meth:`pyramid.config.Configurator.add_view` method
 within :ref:`configuration_module` is used to configure a view
 imperatively.  The arguments to this method are very similar to the
 arguments that you provide to the ``@view_config`` decorator.  For
@@ -1676,13 +1676,13 @@ example:
        return Response('hello!')
 
    # config is assumed to be an instance of the
-   # pyramid.configuration.Configurator class
+   # pyramid.config.Configurator class
    config.add_view(hello_world, name='hello.html')
 
 The first argument, ``view``, is required.  It must either be a Python
 object which is the view itself or a :term:`dotted Python name` to
 such an object.  All other arguments are optional.  See
-:meth:`pyramid.configuration.Configurator.add_view` for more
+:meth:`pyramid.config.Configurator.add_view` for more
 information.
 
 .. index::
@@ -1758,7 +1758,7 @@ this interface.
 .. code-block:: python
    :linenos:
 
-   # config is an instance of pyramid.configuration.Configurator
+   # config is an instance of pyramid.config.Configurator
 
    config.add_view('mypackage.views.hello_world', name='hello.html',
                    context='mypackage.models.IHello')
@@ -1787,6 +1787,7 @@ view configuration, see :ref:`models_which_implement_interfaces`.
 Configuring View Security
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+<<<<<<< HEAD
 If an :term:`authorization policy` is active, any :term:`permission`
 attached to a :term:`view configuration` found during view lookup will
 be verified.  This will ensure that the currently authenticated user
@@ -1794,11 +1795,19 @@ possesses that permission against the :term:`context` before the view
 function is actually called.  Here's an example of specifying a
 permission in a view configuration using
 :meth:`pyramid.configuration.Configurator.add_view`:
+=======
+If a :term:`authorization policy` is active, any :term:`permission` attached
+to a :term:`view configuration` found during view lookup will be consulted to
+ensure that the currently authenticated user possesses that permission
+against the :term:`context` before the view function is actually called.
+Here's an example of specifying a permission in a view configuration using
+:meth:`pyramid.config.Configurator.add_view`:
+>>>>>>> fee38663daccc0130d0c34dbc5a14e67bef2e183
 
 .. code-block:: python
    :linenos:
 
-   # config is an instance of pyramid.configuration.Configurator
+   # config is an instance of pyramid.config.Configurator
 
    config.add_view('myproject.views.add_entry', name='add.html',
                    context='myproject.models.IBlog', permission='add')
diff --git a/docs/narr/zca.rst b/docs/narr/zca.rst
index 7c7617a3d..c930ecc50 100644
--- a/docs/narr/zca.rst
+++ b/docs/narr/zca.rst
@@ -93,7 +93,7 @@ component registry associated with your :app:`Pyramid` application.
 
 There are three ways to fix this: by disusing the ZCA global API
 entirely, by using
-:meth:`pyramid.configuration.Configurator.hook_zca` or by passing
+:meth:`pyramid.config.Configurator.hook_zca` or by passing
 the ZCA global registry to the :term:`Configurator` constructor at
 startup time.  We'll describe all three methods in this section.
 
@@ -154,7 +154,7 @@ Consider the following bit of idiomatic :app:`Pyramid` startup code:
    :linenos:
 
    from zope.component import getGlobalSiteManager
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
 
    def app(global_settings, **settings):
        config = Configurator(settings=settings)
@@ -186,14 +186,14 @@ always return the global ZCA registry (the one in
 
 To "fix" this and make the ZCA global APIs use the "current" BFG
 registry, you need to call
-:meth:`pyramid.configuration.Configurator.hook_zca` within your
+:meth:`pyramid.config.Configurator.hook_zca` within your
 setup code.  For example:
 
 .. code-block:: python
    :linenos:
 
    from zope.component import getGlobalSiteManager
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
 
    def app(global_settings, **settings):
        config = Configurator(settings=settings)
@@ -243,7 +243,7 @@ registry at startup time instead of constructing a new one:
    :linenos:
 
    from zope.component import getGlobalSiteManager
-   from pyramid.configuration import Configurator
+   from pyramid.config import Configurator
 
    def app(global_settings, **settings):
        globalreg = getGlobalSiteManager()
@@ -282,7 +282,7 @@ they should actually be calling ``zope.component.getSiteManager``.
 
 ``zope.component.getSiteManager`` can be overridden by
 :app:`Pyramid` via
-:meth:`pyramid.configuration.Configurator.hook_zca`, while
+:meth:`pyramid.config.Configurator.hook_zca`, while
 ``zope.component.getGlobalSiteManager`` cannot.  Directives that use
 ``zope.component.getGlobalSiteManager`` are effectively broken; no
 ZCML directive should be using this function to find a registry to
diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
index a94a1632d..3dbf10bd8 100644
--- a/docs/tutorials/wiki/basiclayout.rst
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -50,10 +50,10 @@ entry point happens to be the ``app`` function within the file named
 
 #. *Line 16*.  Load the
    ``configure.zcml`` file from our package using the
-   :meth:`pyramid.configuration.Configurator.load_zcml` method.
+   :meth:`pyramid.config.Configurator.load_zcml` method.
 
 #. *Line 17*.  Use the
-   :meth:`pyramid.configuration.Configurator.make_wsgi_app` method
+   :meth:`pyramid.config.Configurator.make_wsgi_app` method
    to return a :term:`WSGI` application.
 
 Configuration With ``configure.zcml``
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki/src/authorization/tutorial/__init__.py
index a8a3c513e..742627a3f 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/authorization/tutorial/__init__.py
@@ -1,4 +1,4 @@
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from repoze.zodbconn.finder import PersistentApplicationFinder
 from tutorial.models import appmaker
 
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py
index 45e4d722b..8325865c0 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py
@@ -1,4 +1,4 @@
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from repoze.zodbconn.finder import PersistentApplicationFinder
 from tutorial.models import appmaker
 
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py b/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py
index e11b3625e..a43b917a8 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py
@@ -1,11 +1,11 @@
 import unittest
 
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from pyramid import testing
 
 class ViewTests(unittest.TestCase):
     def setUp(self):
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
diff --git a/docs/tutorials/wiki/src/models/tutorial/__init__.py b/docs/tutorials/wiki/src/models/tutorial/__init__.py
index 66e2f05ee..cf0d14b2d 100644
--- a/docs/tutorials/wiki/src/models/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/models/tutorial/__init__.py
@@ -1,4 +1,4 @@
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from repoze.zodbconn.finder import PersistentApplicationFinder
 from tutorial.models import appmaker
 
diff --git a/docs/tutorials/wiki/src/models/tutorial/tests.py b/docs/tutorials/wiki/src/models/tutorial/tests.py
index 2f5bc48e3..25cb04cc6 100644
--- a/docs/tutorials/wiki/src/models/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/models/tutorial/tests.py
@@ -1,6 +1,6 @@
 import unittest
 
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from pyramid import testing
 
 class PageModelTests(unittest.TestCase):
@@ -50,7 +50,7 @@ class AppmakerTests(unittest.TestCase):
 
 class ViewTests(unittest.TestCase):
     def setUp(self):
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
diff --git a/docs/tutorials/wiki/src/viewdecorators/tutorial/__init__.py b/docs/tutorials/wiki/src/viewdecorators/tutorial/__init__.py
index 66e2f05ee..cf0d14b2d 100644
--- a/docs/tutorials/wiki/src/viewdecorators/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/viewdecorators/tutorial/__init__.py
@@ -1,4 +1,4 @@
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from repoze.zodbconn.finder import PersistentApplicationFinder
 from tutorial.models import appmaker
 
diff --git a/docs/tutorials/wiki/src/views/tutorial/__init__.py b/docs/tutorials/wiki/src/views/tutorial/__init__.py
index 66e2f05ee..cf0d14b2d 100644
--- a/docs/tutorials/wiki/src/views/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/views/tutorial/__init__.py
@@ -1,4 +1,4 @@
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from repoze.zodbconn.finder import PersistentApplicationFinder
 from tutorial.models import appmaker
 
diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index b7e20a95b..8d30ab807 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -68,7 +68,7 @@ represents.
 .. note: Although we don't use the functionality here, the ``factory`` used
    to create route contexts may differ per-route as opposed to globally.  See
    the ``factory`` argument to
-   :meth:`pyramid.configuration.Configurator.add_route` for more info.
+   :meth:`pyramid.config.Configurator.add_route` for more info.
 
 We'll pass the ``RootFactory`` we created in the step above in as the
 ``root_factory`` argument to a :term:`Configurator`.  
@@ -85,7 +85,7 @@ For any :app:`Pyramid` application to perform authorization, we need to add a
 We'll change our ``__init__.py`` file to enable an
 ``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to enable
 declarative security checking.  We'll also change ``__init__.py`` to add a
-:meth:`pyramid.configuration.Configurator.add_view` call to points at our
+:meth:`pyramid.config.Configurator.add_view` call to points at our
 ``login`` :term:`view callable`, also known as a :term:`forbidden view`.
 This configures our newly created login view to show up when :app:`Pyramid`
 detects that a view invocation can not be authorized.  Also, we'll add
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index a9f7b2282..565bd0e96 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -47,7 +47,7 @@ function:
    ``db_string``, etc.
 
 #. *Line 12*.  We call
-   :meth:`pyramid.configuration.Configurator.add_static_view` with the
+   :meth:`pyramid.config.Configurator.add_static_view` with the
    arguments ``static`` (the name), and ``tutorial:static`` (the path).  This
    registers a static resource view which will match any URL that starts with
    ``/static/``.  This will serve up static resources for us from within the
@@ -59,13 +59,13 @@ function:
    such as a CSS file.
 
 #. *Lines 13-14*.  Register a :term:`route configuration` via the
-   :meth:`pyramid.configuration.Configurator.add_route` method that will be
+   :meth:`pyramid.config.Configurator.add_route` method that will be
    used when the URL is ``/``.  Since this route has an ``pattern`` equalling
    ``/`` it is the "default" route. The argument named ``view`` with the
    value ``tutorial.views.my_view`` is the dotted name to a *function* we
    write (generated by the ``pyramid_routesalchemy`` template) that is given
    a ``request`` object and which returns a response or a dictionary.  You
-   will use :meth:`pyramid.configuration.Configurator.add_route` statements
+   will use :meth:`pyramid.config.Configurator.add_route` statements
    in a :term:`URL dispatch` based application to map URLs to code.  This
    route also names a ``view_renderer``, which is a template which lives in
    the ``templates`` subdirectory of the package.  When the
@@ -73,7 +73,7 @@ function:
    will use this template to create a response.
 
 #. *Line 15*.  We use the
-   :meth:`pyramid.configuration.Configurator.make_wsgi_app` method to return
+   :meth:`pyramid.config.Configurator.make_wsgi_app` method to return
    a :term:`WSGI` application.
 
 Content Models with ``models.py``
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index 0f446bb4e..e3d611136 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -23,7 +23,7 @@ assumed to return a :term:`response` object.
 The request passed to every view that is called as the result of a route
 match has an attribute named ``matchdict`` that contains the elements placed
 into the URL by the ``pattern`` of a ``route`` statement.  For instance, if a
-call to :meth:`pyramid.configuration.Configurator.add_route` in
+call to :meth:`pyramid.config.Configurator.add_route` in
 ``__init__.py`` had the pattern ``{one}/{two}``, and the URL at
 ``http://example.com/foo/bar`` was invoked, matching this pattern, the
 matchdict dictionary attached to the request passed to the view would have a
@@ -255,7 +255,7 @@ body of this guide, however it is available `online
 
 This CSS file will be accessed via
 e.g. ``http://localhost:6543/static/style.css`` by virtue of the call we've
-made to :meth:`pyramid.configuration.Configurator.add_static_view` within our
+made to :meth:`pyramid.config.Configurator.add_static_view` within our
 ``__init__.py`` file.  Any number and type of static resources can be placed
 in this directory (or subdirectories) and are just referred to by URL within
 templates.
@@ -264,7 +264,7 @@ Mapping Views to URLs in ``__init__.py``
 ========================================
 
 The ``__init__.py`` file contains
-:meth:`pyramid.configuration.Configurator.add_route` calls which serve to map
+:meth:`pyramid.config.Configurator.add_route` calls which serve to map
 URLs via :term:`url dispatch` to view functions.  First, we’ll get rid of the
 existing route created by the template using the name ``home``. It’s only an
 example and isn’t relevant to our application.
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
index dbac349b9..025b94927 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
@@ -1,4 +1,4 @@
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from pyramid.authentication import AuthTktAuthenticationPolicy
 from pyramid.authorization import ACLAuthorizationPolicy
 
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/tests.py b/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
index c78899797..1020a8b99 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
@@ -1,6 +1,6 @@
 import unittest
 
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from pyramid import testing
 
 def _initTestingDB():
@@ -20,7 +20,7 @@ def _registerRoutes(config):
 
 class ViewWikiTests(unittest.TestCase):
     def setUp(self):
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
@@ -36,7 +36,7 @@ class ViewWikiTests(unittest.TestCase):
 class ViewPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
@@ -71,7 +71,7 @@ class ViewPageTests(unittest.TestCase):
 class AddPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
@@ -104,7 +104,7 @@ class AddPageTests(unittest.TestCase):
 class EditPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
index 5236a538d..d27b891c0 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
@@ -1,4 +1,4 @@
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from sqlalchemy import engine_from_config
 
 from tutorial.models import initialize_sql
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
index 2db1bc5b6..fa3788340 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
@@ -1,5 +1,5 @@
 import unittest
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from pyramid import testing
 
 def _initTestingDB():
@@ -10,7 +10,7 @@ def _initTestingDB():
 
 class TestMyView(unittest.TestCase):
     def setUp(self):
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
         _initTestingDB()
 
diff --git a/docs/tutorials/wiki2/src/models/tutorial/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
index e1baa2d64..c912a015b 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
@@ -1,4 +1,4 @@
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from sqlalchemy import engine_from_config
 
 from tutorial.models import initialize_sql
diff --git a/docs/tutorials/wiki2/src/models/tutorial/tests.py b/docs/tutorials/wiki2/src/models/tutorial/tests.py
index 72f0c89d8..42b0aaada 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/tests.py
@@ -1,5 +1,5 @@
 import unittest
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from pyramid import testing
 
 def _initTestingDB():
@@ -9,7 +9,7 @@ def _initTestingDB():
 
 class TestMyView(unittest.TestCase):
     def setUp(self):
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
         _initTestingDB()
 
diff --git a/docs/tutorials/wiki2/src/views/tutorial/__init__.py b/docs/tutorials/wiki2/src/views/tutorial/__init__.py
index 91c299e24..334fde814 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/__init__.py
@@ -1,4 +1,4 @@
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from sqlalchemy import engine_from_config
 
 from tutorial.models import initialize_sql
diff --git a/docs/tutorials/wiki2/src/views/tutorial/tests.py b/docs/tutorials/wiki2/src/views/tutorial/tests.py
index 435e4b588..7b770f927 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/tests.py
@@ -1,6 +1,6 @@
 import unittest
 
-from pyramid.configuration import Configurator
+from pyramid.config import Configurator
 from pyramid import testing
 
 def _initTestingDB():
@@ -20,7 +20,7 @@ def _registerRoutes(config):
 
 class ViewWikiTests(unittest.TestCase):
     def setUp(self):
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
@@ -36,7 +36,7 @@ class ViewWikiTests(unittest.TestCase):
 class ViewPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
@@ -71,7 +71,7 @@ class ViewPageTests(unittest.TestCase):
 class AddPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
@@ -104,7 +104,7 @@ class AddPageTests(unittest.TestCase):
 class EditPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
-        self.config = Configurator()
+        self.config = Configurator(autocommit=True)
         self.config.begin()
 
     def tearDown(self):
diff --git a/docs/tutorials/zeo/index.rst b/docs/tutorials/zeo/index.rst
index 229ec2ffc..b47c6c477 100644
--- a/docs/tutorials/zeo/index.rst
+++ b/docs/tutorials/zeo/index.rst
@@ -164,7 +164,7 @@ Configuration
 
     .. code-block:: python
 
-       from pyramid.configuration import Configurator
+       from pyramid.config import Configurator
        from repoze.zodbconn.finder import PersistentApplicationFinder
        from myapp.models import appmaker
        import transaction
diff --git a/docs/zcml.rst b/docs/zcml.rst
index 60bbbf574..5913f9460 100644
--- a/docs/zcml.rst
+++ b/docs/zcml.rst
@@ -16,6 +16,7 @@ documentation is organized alphabetically by directive name.
    zcml/configure
    zcml/default_permission
    zcml/forbidden
+   zcml/handler
    zcml/include
    zcml/localenegotiator
    zcml/notfound
diff --git a/docs/zcml/aclauthorizationpolicy.rst b/docs/zcml/aclauthorizationpolicy.rst
index 7eecf6c6e..2c66da0c8 100644
--- a/docs/zcml/aclauthorizationpolicy.rst
+++ b/docs/zcml/aclauthorizationpolicy.rst
@@ -24,7 +24,7 @@ Alternatives
 
 You may create an instance of the
 :class:`pyramid.authorization.ACLAuthorizationPolicy` and pass it
-to the :class:`pyramid.configuration.Configurator` constructor as
+to the :class:`pyramid.config.Configurator` constructor as
 the ``authorization_policy`` argument during initial application
 configuration.
 
diff --git a/docs/zcml/authtktauthenticationpolicy.rst b/docs/zcml/authtktauthenticationpolicy.rst
index 1119de9b0..25be4186c 100644
--- a/docs/zcml/authtktauthenticationpolicy.rst
+++ b/docs/zcml/authtktauthenticationpolicy.rst
@@ -91,7 +91,7 @@ Alternatives
 
 You may create an instance of the
 :class:`pyramid.authentication.AuthTktAuthenticationPolicy` and
-pass it to the :class:`pyramid.configuration.Configurator`
+pass it to the :class:`pyramid.config.Configurator`
 constructor as the ``authentication_policy`` argument during initial
 application configuration.
 
diff --git a/docs/zcml/default_permission.rst b/docs/zcml/default_permission.rst
index beb60db1a..54e720ea6 100644
--- a/docs/zcml/default_permission.rst
+++ b/docs/zcml/default_permission.rst
@@ -43,11 +43,11 @@ Alternatives
 ~~~~~~~~~~~~
 
 Using the ``default_permission`` argument to the
-:class:`pyramid.configuration.Configurator` constructor can be used
+:class:`pyramid.config.Configurator` constructor can be used
 to achieve the same purpose.
 
 Using the 
-:meth:`pyramid.configuration.Configurator.set_default_permission`
+:meth:`pyramid.config.Configurator.set_default_permission`
 method can be used to achieve the same purpose when using imperative
 configuration.
 
diff --git a/docs/zcml/forbidden.rst b/docs/zcml/forbidden.rst
index f5b1b4644..7ea6b85fd 100644
--- a/docs/zcml/forbidden.rst
+++ b/docs/zcml/forbidden.rst
@@ -68,7 +68,7 @@ Alternatives
 Use the :ref:`view_directive` directive with a ``context`` that names
 the :exc:`pyramid.exceptions.Forbidden` class.
 
-Use the :meth:`pyramid.configuration.Configurator.add_view` method,
+Use the :meth:`pyramid.config.Configurator.add_view` method,
 passing it a ``context`` which is the
 :exc:`pyramid.exceptions.Forbidden` class.
 
diff --git a/docs/zcml/handler.rst b/docs/zcml/handler.rst
new file mode 100644
index 000000000..301bf7895
--- /dev/null
+++ b/docs/zcml/handler.rst
@@ -0,0 +1,158 @@
+.. _handler_directive:
+
+``handler``
+-----------
+
+The ``handler`` directive adds the configuration of a :term:`view handler` to
+the :term:`application registry`.
+
+Attributes
+~~~~~~~~~~
+
+``route_name``
+  The name of the route, e.g. ``myroute``.  This attribute is required.  It
+  must be unique among all defined handler and route names in a given
+  configuration.
+
+``pattern``
+  The pattern of the route e.g. ``ideas/{idea}``.  This attribute is
+  required.  See :ref:`route_pattern_syntax` for information about the syntax
+  of route patterns.  The name ``{action}`` is treated specially in handler
+  patterns.  See :ref:`using_add_handler` for a discussion of how
+  ``{action}`` in handler patterns is treated.
+
+``action``
+  If the action name is not specified in the ``pattern``, use this name as the 
+  handler action (method name).
+
+``factory``
+  The :term:`dotted Python name` to a function that will generate a
+  :app:`Pyramid` context object when the associated route matches.
+  e.g. ``mypackage.models.MyFactoryClass``.  If this argument is not
+  specified, a default root factory will be used.
+
+``xhr``
+  This value should be either ``True`` or ``False``.  If this value is
+  specified and is ``True``, the :term:`request` must possess an
+  ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this
+  route to match.  This is useful for detecting AJAX requests issued
+  from jQuery, Prototype and other Javascript libraries.  If this
+  predicate returns false, route matching continues.
+
+``traverse``
+  If you would like to cause the :term:`context` to be something other
+  than the :term:`root` object when this route matches, you can spell
+  a traversal pattern as the ``traverse`` argument.  This traversal
+  pattern will be used as the traversal path: traversal will begin at
+  the root object implied by this route (either the global root, or
+  the object returned by the ``factory`` associated with this route).
+
+  The syntax of the ``traverse`` argument is the same as it is for
+  ``pattern``. For example, if the ``pattern`` provided to the
+  ``route`` directive is ``articles/{article}/edit``, and the
+  ``traverse`` argument provided to the ``route`` directive is
+  ``/{article}``, when a request comes in that causes the route to
+  match in such a way that the ``article`` match value is '1' (when
+  the request URI is ``/articles/1/edit``), the traversal path will be
+  generated as ``/1``.  This means that the root object's
+  ``__getitem__`` will be called with the name ``1`` during the
+  traversal phase.  If the ``1`` object exists, it will become the
+  :term:`context` of the request.  :ref:`traversal_chapter` has more
+  information about traversal.
+
+  If the traversal path contains segment marker names which are not
+  present in the ``pattern`` argument, a runtime error will occur.
+  The ``traverse`` pattern should not contain segment markers that do
+  not exist in the ``pattern``.
+
+  A similar combining of routing and traversal is available when a
+  route is matched which contains a ``*traverse`` remainder marker in
+  its ``pattern`` (see :ref:`using_traverse_in_a_route_pattern`).  The
+  ``traverse`` argument to the ``route`` directive allows you to
+  associate route patterns with an arbitrary traversal path without
+  using a a ``*traverse`` remainder marker; instead you can use other
+  match information.
+
+  Note that the ``traverse`` argument to the ``handler`` directive is
+  ignored when attached to a route that has a ``*traverse`` remainder
+  marker in its pattern.
+
+``request_method``
+  A string representing an HTTP method name, e.g. ``GET``, ``POST``,
+  ``HEAD``, ``DELETE``, ``PUT``.  If this argument is not specified,
+  this route will match if the request has *any* request method.  If
+  this predicate returns false, route matching continues.
+
+``path_info``
+  The value of this attribute represents a regular expression pattern
+  that will be tested against the ``PATH_INFO`` WSGI environment
+  variable.  If the regex matches, this predicate will be true.  If
+  this predicate returns false, route matching continues.
+
+``request_param``
+  This value can be any string.  A view declaration with this
+  attribute ensures that the associated route will only match when the
+  request has a key in the ``request.params`` dictionary (an HTTP
+  ``GET`` or ``POST`` variable) that has a name which matches the
+  supplied value.  If the value supplied to the attribute has a ``=``
+  sign in it, e.g. ``request_params="foo=123"``, then the key
+  (``foo``) must both exist in the ``request.params`` dictionary, and
+  the value must match the right hand side of the expression (``123``)
+  for the route to "match" the current request.  If this predicate
+  returns false, route matching continues.
+
+``header``
+  The value of this attribute represents an HTTP header name or a
+  header name/value pair.  If the value contains a ``:`` (colon), it
+  will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*``
+  or ``Host:localhost``).  The *value* of an attribute that represent
+  a name/value pair should be a regular expression.  If the value does
+  not contain a colon, the entire value will be considered to be the
+  header name (e.g. ``If-Modified-Since``).  If the value evaluates to
+  a header name only without a value, the header specified by the name
+  must be present in the request for this predicate to be true.  If
+  the value evaluates to a header name/value pair, the header
+  specified by the name must be present in the request *and* the
+  regular expression specified as the value must match the header
+  value.  Whether or not the value represents a header name or a
+  header name/value pair, the case of the header name is not
+  significant.  If this predicate returns false, route matching
+  continues.
+
+``accept``
+  The value of this attribute represents a match query for one or more
+  mimetypes in the ``Accept`` HTTP request header.  If this value is
+  specified, it must be in one of the following forms: a mimetype
+  match token in the form ``text/plain``, a wildcard mimetype match
+  token in the form ``text/*`` or a match-all wildcard mimetype match
+  token in the form ``*/*``.  If any of the forms matches the
+  ``Accept`` header of the request, this predicate will be true.  If
+  this predicate returns false, route matching continues.
+
+``custom_predicates``
+  This value should be a sequence of references to custom predicate
+  callables.  Use custom predicates when no set of predefined
+  predicates does what you need.  Custom predicates can be combined
+  with predefined predicates as necessary.  Each custom predicate
+  callable should accept two arguments: ``info`` and ``request``
+  and should return either ``True`` or ``False`` after doing arbitrary
+  evaluation of the info and/or the request.  If all custom and
+  non-custom predicate callables return ``True`` the associated route
+  will be considered viable for a given request.  If any predicate
+  callable returns ``False``, route matching continues.  Note that the
+  value ``info`` passed to a custom route predicate is a dictionary
+  containing matching information; see :ref:`custom_route_predicates`
+  for more information about ``info``.
+
+
+Alternatives
+~~~~~~~~~~~~
+
+You can also add a :term:`route configuration` via:
+
+- Using the :meth:`pyramid.config.Configurator.add_handler` method.
+
+See Also
+~~~~~~~~
+
+See also :ref:`handlers_chapter`.
diff --git a/docs/zcml/localenegotiator.rst b/docs/zcml/localenegotiator.rst
index 100fa837a..c90e649f6 100644
--- a/docs/zcml/localenegotiator.rst
+++ b/docs/zcml/localenegotiator.rst
@@ -29,7 +29,7 @@ Example
 Alternatives
 ~~~~~~~~~~~~
 
-Use :meth:`pyramid.configuration.Configurator.set_locale_negotiator`
+Use :meth:`pyramid.config.Configurator.set_locale_negotiator`
 method instance during initial application setup.
 
 See Also
diff --git a/docs/zcml/notfound.rst b/docs/zcml/notfound.rst
index 54826ea17..a2ed95bc4 100644
--- a/docs/zcml/notfound.rst
+++ b/docs/zcml/notfound.rst
@@ -67,7 +67,7 @@ Alternatives
 Use the :ref:`view_directive` directive with a ``context`` that names
 the :exc:`pyramid.exceptions.NotFound` class.
 
-Use the :meth:`pyramid.configuration.Configurator.add_view` method,
+Use the :meth:`pyramid.config.Configurator.add_view` method,
 passing it a ``context`` which is the
 :exc:`pyramid.exceptions.NotFound` class.
 
diff --git a/docs/zcml/remoteuserauthenticationpolicy.rst b/docs/zcml/remoteuserauthenticationpolicy.rst
index d21cd99d2..56e73ee7a 100644
--- a/docs/zcml/remoteuserauthenticationpolicy.rst
+++ b/docs/zcml/remoteuserauthenticationpolicy.rst
@@ -40,7 +40,7 @@ Alternatives
 
 You may create an instance of the
 :class:`pyramid.authentication.RemoteUserAuthenticationPolicy` and
-pass it to the :class:`pyramid.configuration.Configurator`
+pass it to the :class:`pyramid.config.Configurator`
 constructor as the ``authentication_policy`` argument during initial
 application configuration.
 
diff --git a/docs/zcml/renderer.rst b/docs/zcml/renderer.rst
index 67c2a7f0c..c7beead32 100644
--- a/docs/zcml/renderer.rst
+++ b/docs/zcml/renderer.rst
@@ -42,7 +42,7 @@ Examples
 Alternatives
 ~~~~~~~~~~~~
 
-The :meth:`pyramid.configuration.Configurator.add_renderer` method
+The :meth:`pyramid.config.Configurator.add_renderer` method
 is equivalent to the ``renderer`` ZCML directive.
 
 See Also
diff --git a/docs/zcml/repozewho1authenticationpolicy.rst b/docs/zcml/repozewho1authenticationpolicy.rst
index e5152f2e1..11907ce31 100644
--- a/docs/zcml/repozewho1authenticationpolicy.rst
+++ b/docs/zcml/repozewho1authenticationpolicy.rst
@@ -42,7 +42,7 @@ Alternatives
 
 You may create an instance of the
 :class:`pyramid.authentication.RepozeWho1AuthenticationPolicy` and
-pass it to the :class:`pyramid.configuration.Configurator`
+pass it to the :class:`pyramid.config.Configurator`
 constructor as the ``authentication_policy`` argument during initial
 application configuration.
 
diff --git a/docs/zcml/resource.rst b/docs/zcml/resource.rst
index 4cf5ef400..3f7c58faa 100644
--- a/docs/zcml/resource.rst
+++ b/docs/zcml/resource.rst
@@ -53,7 +53,7 @@ Examples
 Alternatives
 ~~~~~~~~~~~~
 
-The :meth:`pyramid.configuration.Configurator.override_resource`
+The :meth:`pyramid.config.Configurator.override_resource`
 method can be used instead of the ``resource`` ZCML directive.
 
 See Also
diff --git a/docs/zcml/route.rst b/docs/zcml/route.rst
index c3bec72df..4f7cdb955 100644
--- a/docs/zcml/route.rst
+++ b/docs/zcml/route.rst
@@ -215,7 +215,7 @@ Alternatives
 
 You can also add a :term:`route configuration` via:
 
-- Using the :meth:`pyramid.configuration.Configurator.add_route` method.
+- Using the :meth:`pyramid.config.Configurator.add_route` method.
 
 See Also
 ~~~~~~~~
diff --git a/docs/zcml/scan.rst b/docs/zcml/scan.rst
index cbf797e1c..df2cdd281 100644
--- a/docs/zcml/scan.rst
+++ b/docs/zcml/scan.rst
@@ -25,7 +25,7 @@ Example
 Alternatives
 ~~~~~~~~~~~~
 
-The :meth:`pyramid.configuration.Configurator.scan` method performs
+The :meth:`pyramid.config.Configurator.scan` method performs
 the same job as the ``scan`` ZCML directive.
 
 See Also
diff --git a/docs/zcml/static.rst b/docs/zcml/static.rst
index 164e7400c..9538d18f0 100644
--- a/docs/zcml/static.rst
+++ b/docs/zcml/static.rst
@@ -79,7 +79,7 @@ Examples
 Alternatives
 ~~~~~~~~~~~~
 
-:meth:`pyramid.configuration.configurator.add_static_view` can also
+:meth:`pyramid.config.Configurator.add_static_view` can also
 be used to add a static view.
 
 See Also
diff --git a/docs/zcml/subscriber.rst b/docs/zcml/subscriber.rst
index d584f1e02..25c4abf2e 100644
--- a/docs/zcml/subscriber.rst
+++ b/docs/zcml/subscriber.rst
@@ -37,7 +37,7 @@ Alternatives
 ~~~~~~~~~~~~
 
 You can also register an event listener by using the
-:meth:`pyramid.configuration.Configurator.add_subscriber` method.
+:meth:`pyramid.config.Configurator.add_subscriber` method.
 
 See Also
 ~~~~~~~~
diff --git a/docs/zcml/translationdir.rst b/docs/zcml/translationdir.rst
index 56c0977db..5cf615d26 100644
--- a/docs/zcml/translationdir.rst
+++ b/docs/zcml/translationdir.rst
@@ -55,7 +55,7 @@ Example 3
 Alternatives
 ~~~~~~~~~~~~
 
-Use :meth:`pyramid.configuration.Configurator.add_translation_dirs`
+Use :meth:`pyramid.config.Configurator.add_translation_dirs`
 method instance during initial application setup.
 
 See Also
diff --git a/docs/zcml/view.rst b/docs/zcml/view.rst
index 6e67b4c56..74d497cb3 100644
--- a/docs/zcml/view.rst
+++ b/docs/zcml/view.rst
@@ -244,7 +244,7 @@ You can also add a :term:`view configuration` via:
 
 - Using the :class:`pyramid.view.view_config` class as a decorator.
 
-- Using the :meth:`pyramid.configuration.Configurator.add_view` method.
+- Using the :meth:`pyramid.config.Configurator.add_view` method.
 
 See Also
 ~~~~~~~~