more doc strings

lib/python/Products/ZCatalog/Catalog.py

@@ -94,7 +94,6 @@ from Missing import MV
 
 from Lazy import LazyMap, LazyFilter, LazyCat
 
-
 class NoBrainer:
     """ This is the default class that gets instantiated for records
     returned by a __getitem__ on the Catalog.  By default, no special
@@ -102,7 +101,6 @@ class NoBrainer:
     """
     pass
 
-
 def orify(seq,
           query_map={
               type(regex.compile('')): Query.Regex,
@@ -116,13 +114,15 @@ def orify(seq,
     return apply(Query.Or,tuple(subqueries))
     
 
-
 class Catalog(Persistent, Acquisition.Implicit):
     """ An Object Catalog
 
     An Object Catalog maintains a table of object metadata, and a
     series of manageable indexes to quickly search for objects
     (references in the metadata) that satisfy a search query.
+
+    This class is not Zope specific, and can be used in any python
+    program to build catalogs of objects.
     """
 
     _v_brains = NoBrainer
@@ -152,7 +152,6 @@ class Catalog(Persistent, Acquisition.Implicit):
             
         self.useBrains(self._v_brains)
 
-
     def __getitem__(self, index):
         """ Returns instances of self._v_brains, or whatever is passed 
         into self.useBrains.
@@ -161,7 +160,6 @@ class Catalog(Persistent, Acquisition.Implicit):
         r.data_record_id_ = index
         return r
 
-
     def __setstate__(self, state):
         Persistent.__setstate__(self, state)
         self.useBrains(self._v_brains)
@@ -187,7 +185,6 @@ class Catalog(Persistent, Acquisition.Implicit):
         self._v_brains = brains
         self._v_result_class=mybrains
 
-
     def addColumn(self, name, default_value=None):
         """ adds a row to the meta data schema """
         
@@ -218,7 +215,6 @@ class Catalog(Persistent, Acquisition.Implicit):
         self.useBrains(self._v_brains)
             
         self.__changed__(1)    #why?
-
             
     def delColumn(self, name):
         """ deletes a row from the meta data schema """
@@ -246,7 +242,6 @@ class Catalog(Persistent, Acquisition.Implicit):
             rec = list(self.data[key])
             rec.remove(rec[_index])
             self.data[key] = tuple(rec)
-            
 
     def addIndex(self, name, type):
         """ adds an index """
@@ -271,7 +266,6 @@ class Catalog(Persistent, Acquisition.Implicit):
         del indexes[name]
         self.indexes = indexes
 
-
     # the cataloging API
 
     def catalogObject(self, object, uid, threshold=None):
@@ -311,7 +305,6 @@ class Catalog(Persistent, Acquisition.Implicit):
         self.data = data
 
         return total
-                                          
 
     def uncatalogObject(self, uid):
         """ 
@@ -341,7 +334,6 @@ class Catalog(Persistent, Acquisition.Implicit):
         del self.uids[uid]
         del self.paths[rid]
 
-
     def clear(self):
 
         """ clear catalog """
@@ -353,7 +345,6 @@ class Catalog(Persistent, Acquisition.Implicit):
         for x in self.indexes.values():
             x.clear()
 
-
     def uniqueValuesFor(self, name):
         """ return unique values for FieldIndex name """
         return self.indexes[name].uniqueValues()
@@ -365,7 +356,6 @@ class Catalog(Persistent, Acquisition.Implicit):
         else:
             return None
 
-
     def recordify(self, object):
         """ turns an object into a record tuple """
 
@@ -383,16 +373,13 @@ class Catalog(Persistent, Acquisition.Implicit):
 
         return tuple(record)
 
-
     def instantiate(self, record):
 
         r=self._v_result_class(record[1])
         r.data_record_id_ = record[0]
         return r.__of__(self)
 
-
-
-# searching VOODOO follows
+## Searching engine
 
     def _indexedSearch(self, args, sort_index, append, used):
 
@@ -432,8 +419,6 @@ class Catalog(Persistent, Acquisition.Implicit):
 
         return used
 
-
-
     def searchResults(self, REQUEST=None, used=None,
                       query_map={
                           type(regex.compile('')): Query.Regex,
@@ -505,7 +490,6 @@ class Catalog(Persistent, Acquisition.Implicit):
 
         return r
 
-
     __call__ = searchResults
 
 

lib/python/Products/ZCatalog/ZCatalog.py

@@ -110,7 +110,24 @@ def manage_addZCatalog(self,id,title,REQUEST=None):
 
 
 class ZCatalog(Folder, FindSupport, Persistent, Implicit):
-    """ZCatalog object"""
+    """ZCatalog object
+
+    A ZCatalog contains arbirary index like references to Zope
+    objects.  ZCatalog's can index either 'Field' values of object, or 
+    'Text' values.
+
+    ZCatalog does not store references to the objects themselves, but
+    rather to a unique identifier that defines how to get to the
+    object.  In Zope, this unique idenfier is the object's relative
+    path to the ZCatalog (since two Zope object's cannot have the same 
+    URL, this is an excellent unique qualifier in Zope).
+
+    Most of the dirty work is done in the _catalog object, which is an
+    instance of the Catalog class.  An interesting feature of this
+    class is that it is not Zope specific.  You can use it in any
+    Python program to catalog objects.
+
+    """
 
     meta_type = "ZCatalog"
     icon='misc_/ZCatalog/ZCatalog.gif'
@@ -131,7 +148,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
          'target':'manage_main'},
         )
 
-    
     __ac_permissions__=(
 
         ('Manage ZCatalog Entries',
@@ -163,7 +179,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
     manage_catalogIndexes = HTMLFile('catalogIndexes', globals())
     manage_catalogStatus = HTMLFile('catalogStatus', globals())
 
-
     def __init__(self,id,title=''):
         self.id=id
         self.title=title
@@ -186,7 +201,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
         self._catalog.addColumn('summary')
         self._catalog.addIndex('PrincipiaSearchSource', 'TextIndex')
         
-        
     def manage_edit(self, threshold=1000, REQUEST=None):
         """ edit the catalog """
         self.threshold = threshold
@@ -195,7 +209,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
         return self.manage_main(self, REQUEST,
                                 manage_tabs_message=message)
 
-
     def manage_catalogObject(self, REQUEST, urls=None, blah=None):
         """ index all Zope objects that 'urls' point to """
         if urls:
@@ -214,7 +227,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
         return self.manage_main(self, REQUEST,
                                 manage_tabs_message=message)
 
-
     def manage_uncatalogObject(self, REQUEST, urls=None):
         """ removes Zope object 'urls' from catalog """
 
@@ -230,7 +242,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
         return self.manage_main(self, REQUEST,
                                 manage_tabs_message=message)
 
-
     def manage_catalogReindex(self, REQUEST):
         """ iterate over the whole catalog, deleting inexistent
         references and refreshing objects"""
@@ -249,7 +260,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
         return self.manage_catalogView(self, REQUEST,
                                 manage_tabs_message=message)
 
-
     def manage_catalogClear(self, REQUEST):
         """ clears the whole enchelada """
         self._catalog.clear()
@@ -258,7 +268,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
         return self.manage_main(self, REQUEST,
                                 manage_tabs_message=message)
 
-
     def manage_catalogFoundItems(self, REQUEST, obj_metatypes=None,
                                  obj_ids=None, obj_searchterm=None,
                                  obj_expr=None, obj_mtime=None,
@@ -286,7 +295,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
         return self.manage_catalogView(self, REQUEST,
                                 manage_tabs_message=message)
 
-
     def manage_addColumn(self, name, REQUEST):
         """ add a column """
         self._catalog.addColumn(name)
@@ -332,18 +340,14 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
             get_transaction().commit(1)
             self._v_total = 0
 
-
     def uncatalog_object(self, uid):
         """ wrapper around catalog """
-            
         self._catalog.uncatalogObject(uid)
 
-
     def uniqueValuesFor(self, name):
         """ returns the unique values for a given FieldIndex """
         return self._catalog.uniqueValuesFor(name)
 
-
     def getpath(self, rid):
         """
         Return the path to a cataloged object given a 'data_record_id_'
@@ -369,7 +373,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
     def index_objects(self):
         return self._catalog.indexes.values()
 
-
     def _searchable_arguments(self):
         r = {}
         n={'optional':1}
@@ -377,7 +380,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
             r[name]=n
         return r
 
-
     def _searchable_result_columns(self):
         r = []
         for name in self._catalog.indexes.keys():
@@ -389,7 +391,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
             r.append(i)
         return r
 
-
     def searchResults(self, REQUEST=None, used=None,
                       query_map={
                           type(regex.compile('')): Query.Regex,
@@ -407,7 +408,6 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
 
     __call__=searchResults
 
-
 ## this stuff is so the find machinery works
 
     meta_types=() # Sub-object types that are specific to this object
@@ -441,9 +441,10 @@ class ZCatalog(Folder, FindSupport, Persistent, Implicit):
         return roles
 
 ## stolen from ZPublisher and modified slightly
-
+## Note: do not use, this method is depricated.  Use 'getobject'
+    
     def resolve_url(self, path, REQUEST):
-	""" The use of this function is depricated """
+	""" The use of this function is depricated.  Use 'getobject' """
         # Attempt to resolve a url into an object in the Zope
         # namespace. The url must be a fully-qualified url. The
         # method will return the requested object if it is found