Features

   - A ``repoze.bfg.location`` API module was added.

  Backwards incompatibilities

   - Applications must now use the ``repoze.bfg.interfaces.ILocation``
     interface rather than ``zope.location.interfaces.ILocation`` to
     represent that a model object is "location-aware".  We've removed
     a dependency on ``zope.location`` for cleanliness purposes: as
     new versions of zope libraries are released which have improved
     dependency information, getting rid of our dependence on
     ``zope.location`` will prevent a newly installed repoze.bfg
     application from requiring the ``zope.security``, egg, which not
     truly used at all in a "stock" repoze.bfg setup.  These
     dependencies are still required by the stack at this time; this
     is purely a futureproofing move.

     The security and model documentation for previous versions of
     ``repoze.bfg`` recommended using the
     ``zope.location.interfaces.ILocation`` interface to represent
     that a model object is "location-aware".  This documentation has
     been changed to reflect that this interface should now be
     imported from ``repoze.bfg.interfaces.ILocation`` instead.

2 files changed, 49 insertions, 20 deletions

diff --git a/docs/narr/models.rst b/docs/narr/models.rst
index 7df265657..e627a682c 100644
--- a/docs/narr/models.rst
+++ b/docs/narr/models.rst
@@ -74,7 +74,7 @@ by via ``__getitem__``.
 If you choose not to manage the ``__name__`` and ``__parent__``
 attributes of your models "by hand", :mod:`repoze.bfg`` is willing to
 help you do this.  If your "root" node claims it implements the
-interface ``zope.location.interfaces.ILocation``, you don't need to
+interface ``repoze.bfg.interfaces.ILocation``, you don't need to
 manage these attributes by hand.  During :term:`traversal`, if the
 root node says it implements the ``ILocation`` :term:`interface`,
 :mod:`repoze.bfg` will wrap each child in a ``LocationProxy`` which
@@ -84,7 +84,20 @@ recursively.
 If you choose to make use of the location-based dynamic assignment of
 ``__parent__`` and ``__name__``, the root node must have a
 ``__parent__`` and a ``__name__`` that are both ``None``, and it must
-provide the ``ILocation`` interface.  The easiest way to do this is to
-claim that the class representing the root node
-``implements(ILocation)``, as above.
+provide the ``repoze.bfg.interfaces.ILocation`` interface.  The
+easiest way to do this is to claim that the class representing the
+root node ``implements(ILocation)``:
+
+.. code-block::
+   :linenos:
+
+   from repoze.bfg.interfaces import ILocation
+   from zope.interface import implements
+
+   class MyRootObject(object):
+       implements(ILocation)
+       __parent__ = None
+       __name__ = ''
+
+
 
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 48c88cbde..76f488f43 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -84,19 +84,17 @@ class:
 
    from repoze.bfg.security import Everyone
    from repoze.bfg.security import Allow
-   from zope.location.interfaces import ILocation
-   from zope.location.location import Location
 
    class IBlog(Interface):
        pass
 
-   class Blog(dict, Location):
+   class Blog(dict):
        __acl__ = [
            (Allow, Everyone, 'view'),
            (Allow, 'group:editors', 'add'),
            (Allow, 'group:editors', 'edit'),
            ]
-       implements(IBlog, ILocation)
+       implements(IBlog)
 
 The above ACL indicates that the ``Everyone`` principal (a special
 system-defined principal indicating, literally, everyone) is allowed
@@ -128,26 +126,44 @@ Location-Awareness
 ------------------
 
 In order to allow the security machinery to perform ACL inheritance,
-model objects should provide *location-awareness*.
+model objects must provide *location-awareness*.  Providing
+location-awareness means two things: the root object in the graph must
+have a ``_name__`` and a ``__parent__`` attribute and the root object
+must be declared to implement the ``repoze.bfg.interfaces.ILocation``
+interface.  For example:
 
-Objects have parents when they define an ``__parent__`` attribute
-which points at their parent object.  The root object's ``__parent__``
-is ``None``.  An object with a ``__parent__`` attribute and a
-``__name__`` attribute is said to be *location-aware*.
+.. code-block::
+   :linenos:
+
+   from repoze.bfg.interfaces import ILocation
+   from zope.interface import implements
+
+   class Blog(object):
+       implements(ILocation)
+       __name__ = ''
+       __parent__ = None
+
+An object with a ``__parent__`` attribute and a ``__name__`` attribute
+is said to be *location-aware*.  Location-aware objects define an
+``__parent__`` attribute which points at their parent object.  The
+root object's ``__parent__`` is ``None``.
 
 If the root object in a :mod:`repoze.bfg` application declares that it
-implements the ``ILocation`` interface, it is assumed that the objects
-in the rest of the model are location-aware.  Even if they are not
-explictly, if the root object is marked as ``ILocation``, the bfg
-framework will wrap each object during traversal in a *location
-proxy*, which will wrap each object found during traversal in a proxy
-object that has both the ``__name__`` and ``__parent__`` attributes,
-but otherwise acts the same as your model object.
+implements the ``repoze.bfg.interfaces.ILocation`` interface, it is
+assumed that the objects in the rest of the model are location-aware.
+If those objects are not explictly location-aware, if the root object
+is marked as ``ILocation``, the bfg framework will wrap each object
+during traversal in a *location proxy* that has both the ``__name__``
+and ``__parent__`` attributes, but otherwise acts the same as your
+model object.
 
 You can of course supply ``__name__`` and ``__parent__`` attributes
 explicitly on all of your model objects, and no location proxying will
 be performed.
 
+See :ref:`location_module` for documentations of functions which use
+location-awareness.
+
 Debugging Security Failures
 ---------------------------