- The ``__call__`` of a plugin "traverser" implementation (registered

  as an adapter for ``ITraverser`` or ``ITraverserFactory``) will now
  receive a *request* as the single argument to its ``__call__``
  method.  In previous versions it was passed a WSGI ``environ``
  object.  The request object passed to the factory implements
  dictionary-like methods in such a way that existing traverser code
  which expects to be passed an environ will continue to work.

- Fix docs.

1 files changed, 11 insertions, 1 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index d2020af0d..0fea7c64e 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -231,7 +231,7 @@ a class that implements the following interface:
        def __init__(self, root):
            """ Accept the root object returned from the root factory """
 
-       def __call__(self, environ):
+       def __call__(self, request):
            """ Return a dictionary with (at least) the keys ``root``,
            ``context``, ``view_name``, ``subpath``, ``traversed``,
            ``virtual_root``, and ``virtual_root_path``.  These values are
@@ -255,6 +255,16 @@ a class that implements the following interface:
            as attributes of the ``request`` object.
            """
 
+.. warning:: In :mod:`repoze.bfg.` 1.0 and previous versions, the
+     traverser ``__call__`` method accepted a WSGI *environment*
+     dictionary rather than a :term:`request` object.  The request
+     object passed to the traverser implements a dictionary-like API
+     which mutates and queries the environment, as a backwards
+     compatibility shim, in order to allow older code to work.
+     However, for maximum forward compatibility, traverser code
+     targeting :mod:`repoze.bfg` 1.1 and higher should expect a
+     request object directly.
+
 More than one traversal algorithm can be active at the same time.  For
 instance, if your :term:`root factory` returns more than one type of
 object conditionally, you could claim that an alternate traverser is