Update doc strings to ReST

browser/adding.py

@@ -18,6 +18,8 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 from warnings import warn
 import zope.security.checker
 from zope.interface import implements
@@ -200,7 +202,7 @@ def isSingleMenuItem(self):
         return len(self.addingInfo()) == 1
 
     def hasCustomAddView(self):
-       "This should be called only if there is singleMenuItem else return 0"
+       "This should be called only if there is `singleMenuItem` else return 0"
        if self.isSingleMenuItem():
            menu_item = self.addingInfo()[0]
            if 'has_custom_add_view' in menu_item:

browser/contents.py

@@ -15,6 +15,7 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
 
 from zope.exceptions import NotFoundError
 from zope.security.interfaces import Unauthorized
@@ -348,7 +349,7 @@ def pasteObjects(self):
 
 
     def hasClipboardContents(self):
-        """ interogates the PrinicipalAnnotation to see if
+        """ interogates the `PrinicipalAnnotation` to see if
            clipboard contents exist """
 
         if not self.supportsPaste:

browser/find.py

@@ -15,6 +15,8 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 from zope.app.container.find import SimpleIdFindFilter
 from zope.app.container.interfaces import IFind
 from zope.app.traversing.api import getName
@@ -25,7 +27,7 @@
 class Find(BrowserView):
 
     def findByIds(self, ids):
-        """Do a find for the ids listed in ids, which is a string."""
+        """Do a find for the `ids` listed in `ids`, which is a string."""
         finder = IFind(self.context)
         ids = ids.split()
         # if we don't have any ids listed, don't search at all

browser/metaconfigure.py

@@ -11,11 +11,12 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""Container-specific ``browser`` ZCML namespace directive handlers
+"""Container-specific browser ZCML namespace directive handlers
 
 $Id$
 """
 __docformat__ = 'restructuredtext'
+
 from zope.interface import Interface
 from zope.configuration.fields import GlobalObject
 from zope.schema import Id
@@ -26,7 +27,7 @@
 from zope.app.security.fields import Permission
 
 class IContainerViews(Interface):
-    """Define several container views for an ``IContainer`` implementation."""
+    """Define several container views for an `IContainer` implementation."""
 
     for_ = GlobalObject(
         title=u"The interface this containerViews are for.",

btree.py

@@ -20,6 +20,7 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
 
 from persistent import Persistent
 from BTrees.OOBTree import OOBTree

contained.py

@@ -11,10 +11,11 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""Classes to support implenting IContained
+"""Classes to support implenting `IContained`
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
 
 from zope.exceptions import DuplicationError
 from zope.security.checker import selectChecker, CombinedChecker
@@ -39,7 +40,7 @@
 from zope.app.container._zope_app_container_contained import getProxiedObject
 
 class Contained(object):
-    """Stupid mix-in that defines __parent__ and __name__ attributes
+    """Stupid mix-in that defines `__parent__` and `__name__` attributes
     """
 
     zope.interface.implements(IContained)
@@ -210,11 +211,11 @@ def containedEvent(object, container, name=None):
     """Establish the containment of the object in the container
 
     The object and necessary event are returned. The object may be a
-    ContainedProxy around the original object. The event is an added
+    `ContainedProxy` around the original object. The event is an added
     event, a moved event, or None.
 
-    If the object implements IContained, simply set its __parent__
-    and __name__ attributes:
+    If the object implements `IContained`, simply set its `__parent__`
+    and `__name__` attributes:
 
         >>> container = {}
         >>> item = Contained()
@@ -270,9 +271,9 @@ def containedEvent(object, container, name=None):
         >>> event.oldName
         u'foo'
 
-    If the object implements ILocation, but not IContained, set it's
-    __parent__ and __name__ attributes *and* declare that it
-    implements IContained:
+    If the `object` implements `ILocation`, but not `IContained`, set it's
+    `__parent__` and `__name__` attributes *and* declare that it
+    implements `IContained`:
 
         >>> from zope.app.location import Location
         >>> item = Location()
@@ -289,8 +290,8 @@ def containedEvent(object, container, name=None):
         True
 
 
-    If the object doesn't even implement ILocation, put a
-    ContainedProxy around it:
+    If the `object` doesn't even implement `ILocation`, put a
+    `ContainedProxy` around it:
 
         >>> item = []
         >>> x, event = containedEvent(item, container, 'foo')
@@ -331,7 +332,7 @@ def contained(object, container, name=None):
     Just return the contained object without an event. This is a convenience
     "macro" for:
 
-       containedEvent(object, container, name)[0]
+       ``containedEvent(object, container, name)[0]``
 
     This function is only used for tests.
     """
@@ -341,10 +342,10 @@ def setitem(container, setitemf, name, object):
     """Helper function to set an item and generate needed events
 
     This helper is needed, in part, because the events need to get
-    published after the object has been added to the container.
+    published after the `object` has been added to the `container`.
 
-    If the item implements IContained, simply set it's __parent__
-    and __name attributes:
+    If the item implements `IContained`, simply set it's `__parent__`
+    and `__name__` attributes:
 
     >>> class IItem(zope.interface.Interface):
     ...     pass
@@ -376,7 +377,7 @@ def setitem(container, setitemf, name, object):
     >>> item.__name__
     u'c'
 
-    If we run this using the testing framework, we'll use getEvents to
+    If we run this using the testing framework, we'll use `getEvents` to
     track the events generated:
 
     >>> from zope.app.event.tests.placelesssetup import getEvents
@@ -410,8 +411,8 @@ def setitem(container, setitemf, name, object):
     >>> item.moved is event
     1
 
-    We can suppress events and hooks by setting the __parent__ and
-    __name__ first:
+    We can suppress events and hooks by setting the `__parent__` and
+    `__name__` first:
 
     >>> item = Item()
     >>> item.__parent__, item.__name__ = container, 'c2'
@@ -465,9 +466,9 @@ def setitem(container, setitemf, name, object):
     3
 
 
-    If the object implements ILocation, but not IContained, set it's
-    __parent__ and __name__ attributes *and* declare that it
-    implements IContained:
+    If the object implements `ILocation`, but not `IContained`, set it's
+    `__parent__` and `__name__` attributes *and* declare that it
+    implements `IContained`:
 
     >>> from zope.app.location import Location
     >>> item = Location()
@@ -490,8 +491,8 @@ def setitem(container, setitemf, name, object):
     >>> len(getEvents(IObjectModifiedEvent))
     4
 
-    If the object doesn't even implement ILocation, put a
-    ContainedProxy around it:
+    If the object doesn't even implement `ILocation`, put a
+    `ContainedProxy` around it:
 
     >>> item = []
     >>> setitem(container, container.__setitem__, u'i', item)
@@ -569,9 +570,10 @@ def setitem(container, setitemf, name, object):
 
 fixing_up = False
 def uncontained(object, container, name=None):
-    """Clear the containment relationship between the object amd the container
+    """Clear the containment relationship between the `object` and
+    the `container'
 
-    If we run this using the testing framework, we'll use getEvents to
+    If we run this using the testing framework, we'll use `getEvents` to
     track the events generated:
 
     >>> from zope.app.event.tests.placelesssetup import getEvents
@@ -629,7 +631,7 @@ def uncontained(object, container, name=None):
     >>> len(getEvents(IObjectModifiedEvent))
     1
 
-    But, if either the name or parent are not None and they are not
+    But, if either the name or parent are not ``None`` and they are not
     the container and the old name, we'll get a modified event but not
     a removed event.
 

dependency.py

@@ -15,6 +15,7 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
 
 from zope.app import zapi
 from zope.app.dependable.interfaces import IDependable, DependencyError

directory.py

@@ -14,30 +14,32 @@
 This module includes two adapters (adapter factories, really) for
 providing a file-system representation for containers:
 
-noop
-  Factory that "adapts" IContainer to IWriteDirectory.
+`noop`
+  Factory that "adapts" `IContainer` to `IWriteDirectory`.
   This is a lie, since it just returns the original object.
 
-Cloner
-  An IDirectoryFactory adapter that just clones the original object.
+`Cloner`
+  An `IDirectoryFactory` adapter that just clones the original object.
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 import zope.app.filerepresentation.interfaces
 from zope.security.proxy import removeSecurityProxy
 from zope.interface import implements
 
 def noop(container):
-    """Adapt an IContainer to an IWriteDirectory by just returning it
+    """Adapt an `IContainer` to an `IWriteDirectory` by just returning it
 
-    This "works" because IContainer and IWriteDirectory have the same
-    methods, however, the output doesn't actually implement IWriteDirectory.
+    This "works" because `IContainer` and `IWriteDirectory` have the same
+    methods, however, the output doesn't actually implement `IWriteDirectory`.
     """
     return container
 
 
 class Cloner(object):
-    """IContainer to IDirectoryFactory adapter that clones
+    """`IContainer` to `IDirectoryFactory` adapter that clones
 
     This adapter provides a factory that creates a new empty container
     of the same class as it's context.

find.py

@@ -0,0 +1,76 @@
+##############################################################################
+#
+# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Find Support
+
+$Id$
+"""
+__docformat__ = 'restructuredtext'
+
+from zope.interface import implements
+from interfaces import IFind, IIdFindFilter
+from interfaces import IReadContainer
+
+class FindAdapter(object):
+
+    implements(IFind)
+
+    __used_for__ = IReadContainer
+
+    def __init__(self, context):
+        self._context = context
+
+    def find(self, id_filters=None, object_filters=None):
+        'See IFind'
+        id_filters = id_filters or []
+        object_filters = object_filters or []
+        result = []
+        container = self._context
+        for id, object in container.items():
+            _find_helper(id, object, container,
+                         id_filters, object_filters,
+                         result)
+        return result
+
+
+def _find_helper(id, object, container, id_filters, object_filters, result):
+    for id_filter in id_filters:
+        if not id_filter.matches(id):
+            break
+    else:
+        # if we didn't break out of the loop, all name filters matched
+        # now check all object filters
+        for object_filter in object_filters:
+            if not object_filter.matches(object):
+                break
+        else:
+            # if we didn't break out of the loop, all filters matched
+            result.append(object)
+
+    if not IReadContainer.providedBy(object):
+        return
+
+    container = object
+    for id, object in container.items():
+        _find_helper(id, object, container, id_filters, object_filters, result)
+
+class SimpleIdFindFilter(object):
+
+    implements(IIdFindFilter)
+
+    def __init__(self, ids):
+        self._ids = ids
+
+    def matches(self, id):
+        'See INameFindFilter'
+        return id in self._ids