Features

--------

- Added a ``traverse`` function to the ``repoze.bfg.traversal``
  module.  This function may be used to retrieve certain values
  computed during path resolution.  See the Traversal API chapter of
  the documentation for more information about this function.

Deprecations
------------

- Internal: ``ITraverser`` callables should now return a dictionary
  rather than a tuple.  Up until 0.7.0, all ITraversers were assumed
  to return a 3-tuple.  In 0.7.1, ITraversers were assumed to return a
  6-tuple.  As (by evidence) it's likely we'll need to add further
  information to the return value of an ITraverser callable, 0.8
  assumes that an ITraverser return a dictionary with certain elements
  in it.  See the ``repoze.bfg.interfaces.ITraverser`` interface for
  the list of keys that should be present in the dictionary.
  ``ITraversers`` which return tuples will still work, although a
  deprecation warning will be issued.

Backwards Incompatibilities
---------------------------

- If your code used the ITraverser interface directly (not via an API
  function such as ``find_model``) via an adapter lookup, you'll need
  to change your code to expect a dictionary rather than a 3- or
  6-tuple if your code ever gets return values from the default
  ModelGraphTraverser or RoutesModelTraverser adapters.

1 files changed, 15 insertions, 14 deletions

diff --git a/repoze/bfg/interfaces.py b/repoze/bfg/interfaces.py
index 5dadd252a..cecc3a397 100644
--- a/repoze/bfg/interfaces.py
+++ b/repoze/bfg/interfaces.py
@@ -59,20 +59,21 @@ deprecated('IRootPolicy',
 
 class ITraverser(Interface):
     def __call__(environ):
-        """ Return a tuple in the form ``(context, view_name, subpath,
-        traversed, virtual_root, virtual_root_path)`` , typically the
-        result of an object graph traversal.  ``context`` will be a
-        model object, ``view_name`` will be the view name used (a
-        Unicode name), ``subpath`` will be a sequence of Unicode names
-        that followed the view name but were not traversed,
-        ``traversed`` will be a sequence of Unicode names that were
-        traversed (including the virtual root path, if any) or
-        ``None`` if no traversal was performed, ``virtual_root`` will
-        be a model object representing the virtual root (or the
-        physical root if traversal was not performed), and
-        ``virtual_root_path`` will be a sequence representing the
-        virtual root path (a sequence of Unicode names) or None if
-        traversal was not performed."""
+        """ Return a dictionary with the keys ``root``, ``context``,
+        ``view_name``, ``subpath``, ``traversed``, ``vroot``, and
+        ``vroot_path``.  These values are typically the result of an
+        object graph traversal.  ``root`` is the physical root object,
+        ``context`` will be a model object, ``view_name`` will be the
+        view name used (a Unicode name), ``subpath`` will be a
+        sequence of Unicode names that followed the view name but were
+        not traversed, ``traversed`` will be a sequence of Unicode
+        names that were traversed (including the virtual root path, if
+        any) or ``None`` if no traversal was performed,
+        ``virtual_root`` will be a model object representing the
+        virtual root (or the physical root if traversal was not
+        performed), and ``virtual_root_path`` will be a sequence
+        representing the virtual root path (a sequence of Unicode
+        names) or None if traversal was not performed."""
 
 class ITraverserFactory(Interface):
     def __call__(context):