more documentation fallout from allowing predicates access to route matching information

5 files changed, 50 insertions, 20 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 0780e94d3..d56f51e4e 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -65,8 +65,8 @@ Documentation
   http://docs.repoze.org/bfgwiki-1.3 and
   http://docs.repoze.org/bfgwiki2-1.3/ respectively.
 
-- A section named ``Custom Predicates`` was added to the URL Dispatch
-  narrative chapter.
+- A section named ``Custom Route Predicates`` was added to the URL
+  Dispatch narrative chapter.
 
 1.3a3 (2010-05-01)
 ==================
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 2f96ca26c..4e49ac4b3 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -571,8 +571,10 @@ represent neither predicates nor view configuration information.
   try to fall back to using a view that otherwise matches the context,
   request, and view name (but does not match the route name predicate).
 
-Custom Predicates
-~~~~~~~~~~~~~~~~~
+.. _custom_route_predicates:
+
+Custom Route Predicates
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Each of the predicate callables fed to the ``custom_predicates``
 argument of :meth:`repoze.bfg.configuration.Configurator.add_route` or
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index b02ade4c3..17be94c9d 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -125,6 +125,21 @@ Minor Feature Additions
   conventions as objects that can be supplied directly to BFG as a
   view callable.
 
+- Prior to 1.3, a *route predicate* had no access to route pattern
+  matching information and had no way to know which route was matched.
+  Now, each of the predicate callables fed to the
+  ``custom_predicates`` argument of
+  :meth:`repoze.bfg.configuration.Configurator.add_route` or the
+  ``custom_predicates`` ZCML attribute can 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.  The ``info`` dictionary has a
+  number of contained values: ``match`` is a dictionary: it represents
+  the arguments matched in the URL by the route.  ``route`` is an
+  object representing the route which was matched.  See also
+  :ref:`custom_route_predicates`.  In prior versions, the ``info``
+  argument was always ``None``.
+
 Backwards Incompatibilites
 --------------------------
 
diff --git a/docs/zcml/route.rst b/docs/zcml/route.rst
index 8bee3c14f..cf765e04f 100644
--- a/docs/zcml/route.rst
+++ b/docs/zcml/route.rst
@@ -103,20 +103,28 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``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: ``context`` and ``request``
+  callable should accept two arguments: ``info`` and ``request``
   and should return either ``True`` or ``False`` after doing arbitrary
-  evaluation of the context and/or the request.  If all callables
-  return ``True``, the associated route will be considered viable for
-  a given request.  If any custom predicate returns ``False``, route
-  matching continues.  Note that the value ``context`` will always be
-  ``None`` when passed to a custom route predicate.
+  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``.
 
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.2.
 
+  .. note:: The ``info`` argument passed to a custom predicate in
+            versions prior to :mod:`repoze.bfg` 1.3 was always
+            ``None``.
+
+
 ``view_context``
   The :term:`dotted Python name` to a class or an interface that the
   :term:`context` of the view should match for the view named by the
diff --git a/repoze/bfg/configuration.py b/repoze/bfg/configuration.py
index 546a6978b..937a7c5d2 100644
--- a/repoze/bfg/configuration.py
+++ b/repoze/bfg/configuration.py
@@ -932,8 +932,7 @@ class Configurator(object):
                   request_param=None,
                   custom_predicates=(),
                   view_permission=None,
-                  renderer=None,
-                  view_renderer=None,
+                  renderer=None,                  view_renderer=None,
                   view_context=None,
                   view_attr=None,
                   use_global_views=False,
@@ -1051,17 +1050,23 @@ class Configurator(object):
           predefined predicates does what you need.  Custom predicates
           can be combined with predefined predicates as necessary.
           Each custom predicate callable should accept two arguments:
-          ``context`` and ``request`` and should return either
-          ``True`` or ``False`` after doing arbitrary evaluation of
-          the context and/or the request.  If all callables return
-          ``True``, the associated route will be considered viable for
-          a given request.  If any custom predicate returns ``False``,
-          route matching continues.  Note that the value ``context``
-          will always be ``None`` when passed to a custom route
-          predicate.
+          ``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``.
 
           .. note:: This feature is new as of :mod:`repoze.bfg` 1.2.
 
+          .. note:: The ``info`` argument passed to a custom predicate
+                    in versions prior to :mod:`repoze.bfg` 1.3 was
+                    always ``None``.
+
         View-Related Arguments
 
         view