From cbdc36976c18a0812f921ee3b7b92ed2dd823ed0 Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@agendaless.com>
Date: Sun, 28 Sep 2008 02:17:36 +0000
Subject:   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.
---
 docs/narr/security.rst | 48 ++++++++++++++++++++++++++++++++----------------
 1 file changed, 32 insertions(+), 16 deletions(-)

(limited to 'docs/narr/security.rst')

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
 ---------------------------
 
-- 
cgit v1.2.3