From cbdc36976c18a0812f921ee3b7b92ed2dd823ed0 Mon Sep 17 00:00:00 2001 From: Chris McDonough 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/api/location.rst | 14 ++++++++++++++ docs/index.rst | 1 + docs/narr/models.rst | 21 +++++++++++++++++---- docs/narr/security.rst | 48 ++++++++++++++++++++++++++++++++---------------- 4 files changed, 64 insertions(+), 20 deletions(-) create mode 100644 docs/api/location.rst (limited to 'docs') diff --git a/docs/api/location.rst b/docs/api/location.rst new file mode 100644 index 000000000..dc7d50a2f --- /dev/null +++ b/docs/api/location.rst @@ -0,0 +1,14 @@ +.. _location_module: + +:mod:`repoze.bfg.location` +-------------------------- + +.. automodule:: repoze.bfg.location + + .. autofunction:: lineage + + .. autofunction:: inside + + .. autofunction:: locate + + diff --git a/docs/index.rst b/docs/index.rst index 8c0660246..594add0cb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -72,6 +72,7 @@ Per-module :mod:`repoze.bfg` API documentation. api/security api/template api/traversal + api/location api/urldispatch api/view api/wsgi 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 --------------------------- -- cgit v1.2.3