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, 13 insertions, 29 deletions

diff --git a/repoze/bfg/router.py b/repoze/bfg/router.py
index 5278da892..614d32aa2 100644
--- a/repoze/bfg/router.py
+++ b/repoze/bfg/router.py
@@ -15,7 +15,6 @@ from repoze.bfg.interfaces import IRequestFactory
 from repoze.bfg.interfaces import IRootFactory
 from repoze.bfg.interfaces import IRouter
 from repoze.bfg.interfaces import IRoutesMapper
-from repoze.bfg.interfaces import ITraverserFactory
 from repoze.bfg.interfaces import ISecurityPolicy
 from repoze.bfg.interfaces import ISettings
 from repoze.bfg.interfaces import IUnauthorizedAppFactory
@@ -35,6 +34,7 @@ from repoze.bfg.settings import Settings
 
 from repoze.bfg.urldispatch import RoutesRootFactory
 
+from repoze.bfg.traversal import _traverse
 from repoze.bfg.view import _view_execution_permitted
 from repoze.bfg.wsgi import Unauthorized
 from repoze.bfg.wsgi import NotFound
@@ -99,25 +99,15 @@ class Router(object):
             
             registry.has_listeners and registry.notify(NewRequest(request))
             root = self.root_factory(environ)
-            traverser = registry.getAdapter(root, ITraverserFactory)
-            vals = traverser(environ)
-
-            try:
-                context, view_name, subpath, traversed, vroot, vroot_path = vals
-            except ValueError:
-                if not (traverser.__class__ in self.traverser_warned):
-                    self.logger and self.logger.warn(
-                        '%s is an pre-0.7.1-style ITraverser returning only '
-                        '3 arguments; please update it to the new '
-                        '6-argument-returning interface for improved '
-                        'functionality.  See the repoze.bfg.interfaces module '
-                        'for the new ITraverser interface '
-                        'definition' % traverser)
-                    self.traverser_warned[traverser.__class__] = True
-                context, view_name, subpath = vals
-                traversed = []
-                vroot = root
-                vroot_path = []
+            tdict = _traverse(root, environ)
+            if '_deprecation_warning' in tdict:
+                warning = tdict.pop('_deprecation_warning')
+                if not warning in self.traverser_warned:
+                    self.logger and self.logger.warn(warning)
+            context, view_name, subpath, traversed, vroot, vroot_path = (
+                tdict['context'], tdict['view_name'], tdict['subpath'],
+                tdict['traversed'], tdict['virtual_root'],
+                tdict['virtual_root_path'])
 
             if isinstance(request, WebObRequest):
                 # webob.Request's __setattr__ (as of 0.9.5 and lower)
@@ -125,13 +115,7 @@ class Router(object):
                 # webob.Request, go around its back and set stuff into
                 # the environ directly
                 attrs = environ.setdefault('webob.adhoc_attrs', {})
-                attrs['root'] = root
-                attrs['context'] = context
-                attrs['view_name'] = view_name
-                attrs['subpath'] = subpath
-                attrs['traversed'] = traversed
-                attrs['virtual_root'] = vroot
-                attrs['virtual_root_path'] = vroot_path
+                attrs.update(tdict)
             else:
                 request.root = root
                 request.context = context
@@ -181,9 +165,9 @@ class Router(object):
                     msg = (
                         'debug_notfound of url %s; path_info: %r, context: %r, '
                         'view_name: %r, subpath: %r, traversed: %r, '
-                        'vroot: %r,  vroot_path: %r' % (
+                        'root: %r, vroot: %r,  vroot_path: %r' % (
                         request.url, request.path_info, context, view_name,
-                        subpath, traversed, vroot, vroot_path)
+                        subpath, traversed, root, vroot, vroot_path)
                         )
                     logger and logger.debug(msg)
                 else: