[Checkins] SVN: zope.index/branches/nadako-sorting/ Add limit and reverse to the sort method of IIndexSort interface.

[Dan Korostelev]

Log message for revision 94381:
  Add limit and reverse to the sort method of IIndexSort interface.
  
  Simplify FieldIndex's sort method, make it a generator and implement new interface features.
  
  Mention that in the CHANGES.txt :)

Changed:
  U   zope.index/branches/nadako-sorting/CHANGES.txt
  U   zope.index/branches/nadako-sorting/src/zope/index/field/README.txt
  U   zope.index/branches/nadako-sorting/src/zope/index/field/index.py
  U   zope.index/branches/nadako-sorting/src/zope/index/interfaces.py

-=-
Modified: zope.index/branches/nadako-sorting/CHANGES.txt
===================================================================
--- zope.index/branches/nadako-sorting/CHANGES.txt	2008-12-27 13:32:43 UTC (rev 94380)
+++ zope.index/branches/nadako-sorting/CHANGES.txt	2008-12-27 13:55:32 UTC (rev 94381)
@@ -1,15 +1,17 @@
 Changes
 =======
 
-3.4.2 (unreleased)
+3.5.0 (unreleased)
 ------------------
 
-Remove zope.testing from dependencies, as it's not really needed.
+- Remove zope.testing from dependencies, as it's not really needed.
+- Define IIndexSort interface for indexes that support sorting and
+  implement it in the FieldIndex.
 
 3.4.1 (2007-09-28)
 ------------------
 
-Fixed bug in package metadata (wrong homepage URL).
+- Fixed bug in package metadata (wrong homepage URL).
 
 3.4.0 (2007-09-28)
 ------------------

Modified: zope.index/branches/nadako-sorting/src/zope/index/field/README.txt
===================================================================
--- zope.index/branches/nadako-sorting/src/zope/index/field/README.txt	2008-12-27 13:32:43 UTC (rev 94380)
+++ zope.index/branches/nadako-sorting/src/zope/index/field/README.txt	2008-12-27 13:55:32 UTC (rev 94381)
@@ -125,13 +125,24 @@
     >>> index.index_doc(8, 2)
     >>> index.index_doc(9, 1)
 
-    >>> index.sort([4, 2, 9, 7, 4, 1, 5])
-    [9, 7, 5, 4, 2, 1]
+    >>> list(index.sort([4, 2, 9, 7, 4, 1, 5]))
+    [9, 7, 5, 4, 4, 2, 1]
 
+We can also specify the ``reverse`` argument to reverse results:
+
+    >>> list(index.sort([4, 2, 9, 7, 4, 1, 5], reverse=True))
+    [1, 2, 4, 4, 5, 7, 9]
+
+And as per IIndexSort, we can limit results by specifying the ``limit``
+argument:
+
+    >>> list(index.sort([4, 2, 9, 7, 4, 1, 5], limit=3)) 
+    [9, 7, 5]
+
 If we pass an id that is not indexed by this index, the
 KeyError is raised as Interface declares:
 
-    >>> index.sort([10])
+    >>> list(index.sort([10]))
     Traceback (most recent call last):
     ...
     KeyError: 'docid 10 is not indexed by <zope.index.field.index.FieldIndex object at 0x...>'

Modified: zope.index/branches/nadako-sorting/src/zope/index/field/index.py
===================================================================
--- zope.index/branches/nadako-sorting/src/zope/index/field/index.py	2008-12-27 13:32:43 UTC (rev 94380)
+++ zope.index/branches/nadako-sorting/src/zope/index/field/index.py	2008-12-27 13:55:32 UTC (rev 94381)
@@ -109,22 +109,18 @@
         return self.family.IF.multiunion(
             self._fwd_index.values(*query))
 
-    def sort(self, docids):
-        values = self._rev_index
-        sorted = self.family.OO.BTree()
+    def sort(self, docids, limit=None, reverse=False):
+        if (limit is not None) and (limit < 1):
+            raise ValueError('limit value must be 1 or greater')
 
-        for docid in docids:
-            value = values.get(docid, None)
-            if value is None:
-                raise KeyError('docid %d is not indexed by %s' % (docid, self))
-            ids = sorted.get(value, None)
-            if ids is None:
-                ids = self.family.OO.Set()
-                sorted[value] = ids
-            ids.insert(docid)
+        marker = object()
+        getValue = self._rev_index.get
         
-        result = []
-        for _, ids in sorted.items():
-            result.extend(ids)
-
-        return result
+        n = 0
+        for docid in sorted(docids, key=getValue, reverse=reverse):
+            if getValue(docid, marker) is marker:
+                raise KeyError('docid %d is not indexed by %s' % (docid, self))
+            n += 1
+            yield docid
+            if limit and n >= limit:
+                raise StopIteration()

Modified: zope.index/branches/nadako-sorting/src/zope/index/interfaces.py
===================================================================
--- zope.index/branches/nadako-sorting/src/zope/index/interfaces.py	2008-12-27 13:32:43 UTC (rev 94380)
+++ zope.index/branches/nadako-sorting/src/zope/index/interfaces.py	2008-12-27 13:55:32 UTC (rev 94381)
@@ -84,17 +84,15 @@
 
 class IIndexSort(Interface):
 
-    def sort(docids):
+    def sort(docids, limit=None, reverse=False):
         """Sort document ids sequence using indexed values
         
         If some of docids are not in index, KeyError is 
         raised.
         
-        Return an ordered sequence of document ids. 
-        
-        XXX Should this method be a generator and accept
-        limit and reverse options?
-        
+        Return an iterable of document ids. Limited by
+        value of the "limit" argument and optionally
+        reversed, using the "reverse" argument.
         """
 
 class IStatistics(Interface):