- Added ``Changing the Traverser`` and ``Changing How

  :mod:`repoze.bfg.url.model_url` Generates a URL`` to the "Hooks"
  narrative chapter of the docs.

1 files changed, 22 insertions, 14 deletions

diff --git a/repoze/bfg/interfaces.py b/repoze/bfg/interfaces.py
index 5d8394484..ad61ac9e5 100644
--- a/repoze/bfg/interfaces.py
+++ b/repoze/bfg/interfaces.py
@@ -57,20 +57,28 @@ class IDefaultRootFactory(Interface):
 
 class ITraverser(Interface):
     def __call__(environ):
-        """ Return a dictionary with the keys ``root``, ``context``,
-        ``view_name``, ``subpath``, ``traversed``, ``virtual_root``,
-        and ``virtual_root_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) ``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 (at least) the keys ``root``,
+        ``context``, ``view_name``, ``subpath``, ``traversed``,
+        ``virtual_root``, and ``virtual_root_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) ``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.
+
+        Extra keys for special purpose functionality can be added as
+        necessary.
+
+        All values returned in the dictionary will be made available
+        as attributes of the ``request`` object.
+        """
 
 class ITraverserFactory(Interface):
     def __call__(context):