From 7f12438f7900cbb5a56233aa2ad832196fe4c249 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 May 2009 22:17:32 +0000 Subject: Docs tweak. --- repoze/bfg/traversal.py | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/repoze/bfg/traversal.py b/repoze/bfg/traversal.py index 705934196..7f05ea63c 100644 --- a/repoze/bfg/traversal.py +++ b/repoze/bfg/traversal.py @@ -149,10 +149,10 @@ def traverse(model, path): the value of the ``model`` argument passed to this function is returned. - - ``root``: The root model object found via traversal or url - dispatch. If the ``model`` passed in was found via url - dispatch, the value of the ``model`` argument passed to this - function is returned. + - ``root``: The model object at which traversal begins. If the + ``model`` passed in was found via url dispatch or if the + ``path`` passed in was relative (non-absolute), the value of the + ``model`` argument passed to this function is returned. - ``view_name``: The 'view name' found during traversal or url dispatch; if the ``model`` was found via traversal, this is @@ -178,20 +178,23 @@ def traverse(model, path): of values discerned from ``*subpath`` in the route pattern matched or the empty sequence. - - ``traversed``: The sequence of path elements traversed to find - the ``context`` object. Each of these items is a Unicode - object. If no path segments were traversed to find the + - ``traversed``: The sequence of path elements traversed from the + root to find the ``context`` object. Each of these items is a + Unicode object. If no path segments were traversed to find the ``context`` object (e.g. if the ``path`` provided is the empty string), the ``traversed`` value will be the empty list. If the - ``model`` is a model found via urldispatch, traversed will be None. + ``model`` is a model found via urldispatch, traversed will be + None. - ``virtual_root``: A model object representing the 'virtual' root of the object graph being traversed. See :ref:`vhosting_chapter` for a definition of the virtual root - object. If no virtual hosting is in effect or if the ``model`` - passed in was found via URL dispatch, the ``virtual_root`` will - always be the physical root of the object graph (the object at - which traversal begins). + object. If no virtual hosting is in effect, and the ``path`` + passed in was absolute, the ``virtual_root`` will be the + *physical* root object (the object at which traversal begins). + If the ``model`` passed in was found via URL dispatch or if the + ``path`` passed in was relative, the ``virtual_root`` will + always equal the ``root`` object (the model passed in). - ``virtual_root_path`` -- If traversal was used to find the ``model``, this will be the sequence of path elements traversed -- cgit v1.2.3