- The ``repoze.bfg.location.LocationProxy`` class and the

  ``repoze.bfg.location.ClassAndInstanceDescr`` class have both been
  removed in order to be able to eventually shed a dependency on
  ``zope.proxy``.  Neither of these classes was ever an API.

- In all previous releases, the ``repoze.bfg.location.locate``
  function worked like so: if a model did not explicitly provide the
  ``repoze.bfg.interfaces.ILocation`` interface, ``locate`` returned a
  ``LocationProxy`` object representing ``model`` with its
  ``__parent__`` attribute assigned to ``parent`` and a ``__name__``
  attribute assigned to ``__name__``.  In this release, the
  ``repoze.bfg.location.locate`` function simply jams the ``__name__``
  and ``__parent__`` attributes on to the supplied model
  unconditionally, no matter if the object implements ILocation or
  not, and it never returns a proxy.  This was done because the
  LocationProxy behavior has now moved into an add-on package
  (``repoze.bfg.traversalwrapper``), in order to eventually be able to
  shed a dependency on ``zope.proxy``.

- In all previous releases, by default, if traversal was used (as
  opposed to URL-dispatch), and the root object supplied
  the``repoze.bfg.interfaces.ILocation`` interface, but the children
  returned via its ``__getitem__`` returned an object that did not
  implement the same interface, :mod:`repoze.bfg` provided some
  implicit help during traversal.  This traversal feature wrapped
  subobjects from the root (and thereafter) that did not implement
  ``ILocation`` in proxies which automatically provided them with a
  ``__name__`` and ``__parent__`` attribute based on the name being
  traversed and the previous object traversed.  This feature has now
  been removed from the base ``repoze.bfg`` package for purposes of
  eventually shedding a dependency on ``zope.proxy``.

  In order to re-enable the wrapper behavior for older applications
  which cannot be changed, register the "traversalwrapper"
  ``ModelGraphTraverser`` as the traversal policy, rather than the
  default ``ModelGraphTraverser``. To use this feature, you will need
  to install the ``repoze.bfg.traversalwrapper`` package (an add-on
  package, available at
  http://svn.repoze.org/repoze.bfg.traversalwrapper) Then change your
  application's ``configure.zcml`` to include the following stanza:

    <adapter
        factory="repoze.bfg.traversalwrapper.ModelGraphTraverser"
        provides="repoze.bfg.interfaces.ITraverserFactory"
        for="*"
        />

   When this ITraverserFactory is used instead of the default, no
   object in the graph (even the root object) must supply a
   ``__name__`` or ``__parent__`` attribute.  Even if subobjects
   returned from the root *do* implement the ILocation interface,
   these will still be wrapped in proxies that override the object's
   "real" ``__parent__`` and ``__name__`` attributes.

   See also changes to the "Models" chapter of the documentation (in
   the "Location-Aware Model Instances") section.

1 files changed, 22 insertions, 16 deletions

diff --git a/docs/narr/models.rst b/docs/narr/models.rst
index 624a29002..61e313830 100644
--- a/docs/narr/models.rst
+++ b/docs/narr/models.rst
@@ -124,31 +124,37 @@ and so on.
 .. note::
 
   If you'd rather not manage the ``__name__`` and ``__parent__``
-  attributes of your models "by hand", :mod:`repoze.bfg`` can help you
-  do this.
-
-  In order to use this helper feature, you must first register the
-  ``WrappingModelGraphTraverser`` as the traversal policy, rather than
-  the default ``ModelGraphTraverser``. To register the
-  ``WrappingModelGraphTraverser`` as the traversal policy, your
-  application will need to have the following in its
-  ``configure.zcml`` file:
+  attributes of your models "by hand", an add-on package to
+  :mod:`repoze.bfg`` named :mod:`repoze.bfg.traversalwrapper` can help
+  you do this.
+
+  In order to use this helper feature, you must first install the
+  :mod:`repoze.bfg.traversalwrapper` package (available from
+  `http://svn.repoze.org/repoze.bfg.traversalwrapper
+  <http://svn.repoze.org/repoze.bfg.traversalwrapper>`_), then
+  register its ``ModelGraphTraverser`` as the traversal policy, rather
+  than the default BFG ``ModelGraphTraverser``. To register the
+  :mod:`repoze.bfg.traversalwrapper` ``ModelGraphTraverser`` as the
+  traversal policy, your application will need to have the following
+  in its ``configure.zcml`` file:
 
   .. code-block:: xml
 
     <adapter
-        factory="repoze.bfg.traversal.WrappingModelGraphTraverser"
+        factory="repoze.bfg.traversalwrapper.ModelGraphTraverser"
         provides="repoze.bfg.interfaces.ITraverserFactory"
         for="*"
     />
 
-  If this statement is made in ZCML, you don't need to manage the
-  ``__parent__`` and ``__name__`` attributes on graph objects "by
+  If this statement is made in ZCML, you will no longer need to manage
+  the ``__parent__`` and ``__name__`` attributes on graph objects "by
   hand".  Instead, as necessary, during traversal :mod:`repoze.bfg`
-  will wrap each object in a ``LocationProxy`` which will dynamically
-  assign a ``__name__`` and a ``__parent__`` to the traversed object
-  (based on the last traversed object and the name supplied to
-  ``__getitem__``).
+  will wrap each object (even the root object) in a ``LocationProxy``
+  which will dynamically assign a ``__name__`` and a ``__parent__`` to
+  the traversed object (based on the last traversed object and the
+  name supplied to ``__getitem__``).  The root object will have a
+  ``__name__`` attribute of ``None`` and a ``__parent__`` attribute
+  of ``None``.
 
 :mod:`repoze.bfg` API Functions That Act Against Models
 -------------------------------------------------------