From 1df49d959a4887e8b77924c1a70ed8a039b2a228 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 22 Dec 2009 03:41:11 +0000 Subject: Roles. --- docs/narr/models.rst | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/narr/models.rst b/docs/narr/models.rst index e1d2fd635..5002101d5 100644 --- a/docs/narr/models.rst +++ b/docs/narr/models.rst @@ -70,15 +70,16 @@ sole argument). An interface simply tags the model object with a "type" that can be referred to within the :term:`application registry`. A model object can implement zero or more interfaces. The interface must be an -instance of a class that inherits from ``zope.interface.Interface``. +instance of a class that inherits from +:class:`zope.interface.Interface`. You specify that a model *implements* an interface by using the -``zope.interface.implements`` function at class scope. The above +:func:`zope.interface.implements` function at class scope. The above ``BlogEntry`` model implements the ``IBlogEntry`` interface. You can also specify that a *particular* model instance provides an interface (as opposed to its class). To do so, use the -``zope.interface.directlyProvides`` API: +:func:`zope.interface.directlyProvides` function: .. code-block:: python :linenos: @@ -101,7 +102,7 @@ interface (as opposed to its class). To do so, use the If a model object already has instance-level interface declarations that you don't want to disturb, use the -``zope.interface.alsoProvides`` API: +:func:`zope.interface.alsoProvides` function: .. code-block:: python :linenos: @@ -144,13 +145,13 @@ policy on model instance nodes in the graph: - Nodes which contain other nodes (aka "container" nodes) must supply a ``__getitem__`` method which is willing to resolve a unicode name to a subobject. If a subobject by that name does not exist in the - container, ``__getitem__`` must raise a ``KeyError``. If a + container, ``__getitem__`` must raise a :exc:`KeyError`. If a subobject by that name *does* exist, the container should return the subobject (another model instance). - Nodes which do not contain other nodes (aka "leaf" nodes) must not implement a ``__getitem__``, or if they do, their ``__getitem__`` - method must raise a ``KeyError``. + method must raise a :exc:`KeyError`. See :ref:`traversal_chapter` for more information about how traversal works against model instances. @@ -192,7 +193,7 @@ traversal functions (such as the functions exposed in :ref:`location_module`, :ref:`traversal_module`, and :ref:`url_module` as well as certain functions in :ref:`security_module` ) to work properly against a instances in an object graph, all nodes in the -graph must be "location-aware". This means they must have two +graph must be :term:`location` -aware. This means they must have two attributes: ``__parent__`` and ``__name__``. The ``__parent__`` attribute should be a reference to the node's @@ -221,12 +222,12 @@ and so on. .. warning:: If your root model object has a ``__name__`` argument that is not ``None`` or the empty string, URLs returned by the - ``repoze.bfg.url.model_url`` function and paths generated by the - ``repoze.bfg.traversal.model_path`` and - ``repoze.bfg.traversal.model_path_tuple`` APIs will be generated - improperly. The value of ``__name__`` will be prepended to every - path and URL generated (as opposed to a single leading slash or - empty tuple element). + :func:`repoze.bfg.url.model_url` function and paths generated by + the :func:`repoze.bfg.traversal.model_path` and + :func:`repoze.bfg.traversal.model_path_tuple` APIs will be + generated improperly. The value of ``__name__`` will be prepended + to every path and URL generated (as opposed to a single leading + slash or empty tuple element). :mod:`repoze.bfg` API Functions That Act Against Models @@ -245,8 +246,9 @@ instances. These can be used to walk down an object graph, or conveniently locate one object "inside" another. Some APIs in :ref:`security_module` accept a model object as a -parameter. For example, the ``has_permission`` API accepts a -"context" (a model object) as one of its arguments; the ACL is -obtained from this model or one of its ancestors. Other APIs in the -same module also accept :term:`context` as an argument, and a context -is always a model. +parameter. For example, the +:func:`repoze.bfg.security.has_permission` API accepts a "context" (a +model object) as one of its arguments; the ACL is obtained from this +model or one of its ancestors. Other APIs in the +:mod:`repoze.bfg.security` module also accept :term:`context` as an +argument, and a context is always a model. -- cgit v1.2.3