updated from / synced with IZCatalog.py

lib/python/Products/ZCatalog/help/ZCatalog.py

@@ -12,21 +12,14 @@
 ##############################################################################
 
 def manage_addZCatalog(id, title, vocab_id=None):
-    """
-
-    Add a ZCatalog object.
+    """Add a ZCatalog object.
 
     'vocab_id' -- this argument is deprecated and ignored.
-
     """
 
 
-
-
 class ZCatalog:
-    """
-
-    ZCatalog object
+    """ZCatalog object
 
     A ZCatalog contains arbitrary index like references to Zope
     objects.  ZCatalog's can index object attribute using a variety
@@ -74,75 +67,71 @@ class ZCatalog:
 
     """
 
-    __constructor__=manage_addZCatalog
+    def catalog_object(obj, uid, idxs=None, update_metadata=1):
+        """Catalogs the object 'obj' with the unique identifier 'uid'.
 
-    def catalog_object(obj, uid):
-        """
+        The uid must be a physical path, either absolute or relative to
+        the catalog.
 
-        Catalogs the object 'obj' with the unique identifier 'uid'.
+        If provided, idxs specifies the names of indexes to update.
 
+        If update_metadata is specified (the default), the object's metadata
+        is updated.  If it is not, the metadata is left untouched.  This
+        flag has no effect if the object is not yet cataloged (metadata
+        is always added for new objects).
         """
 
     def uncatalog_object(uid):
-        """
-
-        Uncatalogs the object with the unique identifier 'uid'.
+        """Uncatalogs the object with the unique identifier 'uid'.
 
+        The uid must be a physical path, either absolute or relative to
+        the catalog.
         """
 
     def uniqueValuesFor(name):
-        """
-
-        returns the unique values for a given FieldIndex named 'name'.
-
+        """returns the unique values for a given FieldIndex named 'name'.
         """
 
     def getpath(rid):
+        """Return the path to a cataloged object given a 'data_record_id_'
         """
 
-        Return the path to a cataloged object given a
-        'data_record_id_'
-
+    def getrid(rid):
+        """Return the 'data_record_id_' to a cataloged object given a path
         """
 
-
     def getobject(rid, REQUEST=None):
-        """
-
-        Return a cataloged object given a 'data_record_id_'
-
+        """Return a cataloged object given a 'data_record_id_'
         """
 
     def schema():
-        """
+        """Get the meta-data schema
 
         Returns a sequence of names that correspond to columns in the
         meta-data table.
 
         """
 
-    def index_objects():
+    def indexes():
+        """Returns a sequence of names that correspond to indexes.
         """
 
-        Returns a sequence of actual index objects.
+    def index_objects():
+        """Returns a sequence of actual index objects.
 
         NOTE: This returns unwrapped indexes! You should probably use
         getIndexObjects instead. Some indexes expect to be wrapped.
-
         """
 
     def getIndexObjects():
-        """
-
-        Returns a list of acquisition wrapped index objects
-
+        """Returns a list of acquisition wrapped index objects
         """
 
     def searchResults(REQUEST=None, **kw):
-        """
+        """Search the catalog.
 
-        Search the catalog.  Search terms can be passed in the REQUEST
-        or as keyword arguments.
+        Search terms can be passed in the REQUEST or as keyword
+        arguments.
 
         Search queries consist of a mapping of index names to search
         parameters.  You can either pass a mapping to searchResults as
@@ -178,7 +167,7 @@ class ZCatalog:
 
           sort_order -- You can specify 'reverse' or 'descending'.
           Default behavior is to sort ascending.
-          
+
           sort_limit -- An optimization hint to tell the catalog how many
           results you are really interested in. See the limit argument
           to the search method for more details.
@@ -186,8 +175,7 @@ class ZCatalog:
         There are some rules to consider when querying this method:
 
             - an empty query mapping (or a bogus REQUEST) returns all
-              items in the
-            catalog.
+              items in the catalog.
 
             - results from a query involving only field/keyword
               indexes, e.g.  {'id':'foo'} and no 'sort_on' will be
@@ -212,29 +200,36 @@ class ZCatalog:
         """
 
     def __call__(REQUEST=None, **kw):
-        """
-        Search the catalog, the same way as 'searchResults'.
+        """Search the catalog, the same way as 'searchResults'.
         """
 
     def search(query_request, sort_index=None, reverse=0, limit=None, merge=1):
         """Programmatic search interface, use for searching the catalog from
         scripts.
-            
-        query_request -- Dictionary containing catalog query. This uses the 
+
+        query_request -- Dictionary containing catalog query. This uses the
         same format as searchResults.
-        
+
         sort_index -- Name of sort index
-        
+
         reverse -- Boolean, reverse sort order (defaults to false)
-        
+
         limit -- Limit sorted result count to the n best records. This is an
         optimization hint used in conjunction with a sort_index. If possible
         ZCatalog will use a different sort algorithm that uses much less memory
         and scales better then a full sort. The actual number of records
         returned is not guaranteed to be <= limit. You still need to apply the
-        same batching to the results.
+        same batching to the results. Since the len() of the results will no
+        longer be the actual result count, you can use the
+        "actual_result_count" attribute of the lazy result object instead to
+        determine the size of the full result set.
 
-        merge -- Return merged, lazy results (like searchResults) or raw 
+        merge -- Return merged, lazy results (like searchResults) or raw
         results for later merging. This can be used to perform multiple
         queries (even across catalogs) and merge and sort the combined results.
         """
+
+    def refreshCatalog():
+        """Reindex every object we can find, removing the unreachable
+        ones from the index.
+        """