- 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, 5 insertions, 1 deletions

diff --git a/repoze/bfg/interfaces.py b/repoze/bfg/interfaces.py
index cb0220a2e..537bb4455 100644
--- a/repoze/bfg/interfaces.py
+++ b/repoze/bfg/interfaces.py
@@ -179,6 +179,8 @@ class IWSGIApplicationCreatedEvent(IObjectEvent):
     
     app = Attribute(u"Published application")
 
+# this interface, even if it becomes unused within BFG, is imported by
+# other packages (such as repoze.bfg.traversalwrapper)
 class ILocation(Interface):
     """Objects that have a structural location"""
 
@@ -223,4 +225,6 @@ class IContextURL(Interface):
     def __call__():
         """ Return a URL that points to the context """
 
-VH_ROOT_KEY = 'HTTP_X_VHM_ROOT'
+# VH_ROOT_KEY is an interface; its imported from other packages (e.g.
+# traversalwrapper)
+VH_ROOT_KEY = 'HTTP_X_VHM_ROOT'