diff options
Diffstat (limited to 'docs/narr')
| -rw-r--r-- | docs/narr/models.rst | 21 | ||||
| -rw-r--r-- | docs/narr/security.rst | 48 |
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 --------------------------- |