fix merge conflicts

17 files changed, 175 insertions, 17 deletions

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
 ~~~~~~~~