Commits

Matt Chaput committed 0373136

Added docs fixes from Wouter Bolsterlee. Fixes issue #184.

Comments (0)

Files changed (4)

docs/source/api/matching.rst

 ===================
-``postings`` module
+``matching`` module
 ===================
 
 .. automodule:: whoosh.matching

docs/source/api/scoring.rst

 .. autoclass:: Weighting
     :members:
 
+.. autoclass:: BaseScorer
+.. autoclass:: WeightScorer
+.. autoclass:: WeightLengthScorer
+
 .. autoclass:: BM25F
 
 .. autoclass:: TF_IDF

src/whoosh/formats.py

     def decode_position_boosts(self, valuestring):
         return [(pos, boost) for pos, _, _, boost
                 in self.decode_character_boosts(valuestring)]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

src/whoosh/matching.py

 # those of the authors and should not be interpreted as representing official
 # policies, either expressed or implied, of Matt Chaput.
 
-from itertools import repeat
-import sys
-
-from whoosh.compat import izip, xrange
-from whoosh.util import abstractmethod
-
 """
 This module contains "matcher" classes. Matchers deal with posting lists. The
 most basic matcher, which reads the list of postings for a term, will be
 provided by the backend implementation (for example,
-``whoosh.filedb.filepostings.FilePostingReader``). The classes in this module
-provide additional functionality, such as combining the results of two
+:class:`whoosh.filedb.filepostings.FilePostingReader`). The classes in this
+module provide additional functionality, such as combining the results of two
 matchers, or modifying the results of a matcher.
 
 You do not need to deal with the classes in this module unless you need to
 write your own Matcher implementation to provide some new functionality. These
 classes are not instantiated by the user. They are usually created by a
-:class:`~whoosh.query.Query` object's ``matcher()`` method, which returns the
-appropriate matcher to implement the query (for example, the ``Or`` query's
-``matcher()`` method returns a ``UnionMatcher`` object).
+:class:`~whoosh.query.Query` object's :meth:`~whoosh.query.Query.matcher()`
+method, which returns the appropriate matcher to implement the query (for
+example, the :class:`~whoosh.query.Or` query's
+:meth:`~whoosh.query.Or.matcher()` method returns a
+:py:class:`~whoosh.matching.UnionMatcher` object).
 
 Certain backends support "quality" optimizations. These backends have the
 ability to skip ahead if it knows the current block of postings can't
 contribute to the top N documents. If the matcher tree and backend support
-these optimizations, the matcher's ``supports_block_quality()`` method will
-return ``True``.
+these optimizations, the matcher's :meth:`Matcher.supports_block_quality()`
+method will return ``True``.
 """
 
+import sys
+from itertools import repeat
+
+from whoosh.compat import izip, xrange
+from whoosh.util import abstractmethod
+
 
 class ReadTooFar(Exception):
-    """Raised when next() or skip_to() is called on an inactive matchers.
+    """Raised when :meth:`~whoosh.matching.Matcher.next()` or
+    :meth:`~whoosh.matching.Matcher.skip_to()` are called on an inactive
+    matcher.
     """
 
 
     @abstractmethod
     def reset(self):
         """Returns to the start of the posting list.
-        
-        Note that reset() may not do what you've used Matcher.replace() and
-        therefore aren't actually calling reset() on the original matcher.
+
+        Note that reset() may not do what you expect after you call
+        :meth:`Matcher.replace()`, since this can mean calling reset() not on
+        the original matcher, but on an optimized replacement.
         """
 
         raise NotImplementedError
 
     def term(self):
-        """Returns a ("fieldname", "termtext") tuple for the term this matcher
+        """Returns a ``("fieldname", "termtext")`` tuple for the term this matcher
         matches, or None if this matcher is not a term matcher.
         """
 
                     yield m
 
     def matching_terms(self, id=None):
-        """Returns an iterator of ("fieldname", "termtext") tuples for the
-        CURRENTLY MATCHING term matchers in this tree.
+        """Returns an iterator of ``("fieldname", "termtext")`` tuples for the
+        **currently matching** term matchers in this tree.
         """
 
         if not self.is_active():
 
     def all_ids(self):
         """Returns a generator of all IDs in the matcher.
-        
+
         What this method returns for a matcher that has already read some
         postings (whether it only yields the remaining postings or all postings
         from the beginning) is undefined, so it's best to only use this method
 
     def all_items(self):
         """Returns a generator of all (ID, encoded value) pairs in the matcher.
-        
+
         What this method returns for a matcher that has already read some
         postings (whether it only yields the remaining postings or all postings
         from the beginning) is undefined, so it's best to only use this method
 
     def items_as(self, astype):
         """Returns a generator of all (ID, decoded value) pairs in the matcher.
-        
+
         What this method returns for a matcher that has already read some
         postings (whether it only yields the remaining postings or all postings
         from the beginning) is undefined, so it's best to only use this method
             format of the field.
         :param scorer: a :class:`whoosh.scoring.BaseScorer` object for scoring
             the postings.
-        :param term: a ("fieldname", "text") tuple, or None if this is not a
-            term matcher.
+        :param term: a ``("fieldname", "text")`` tuple, or None if this is not
+            a term matcher.
         """
 
         self._ids = ids
         :param child: the child matcher.
         :param ids: a set of IDs to filter by.
         :param exclude: by default, only IDs from the wrapped matcher that are
-            IN the set are used. If this argument is True, only IDs from the
-            wrapped matcher that are NOT IN the set are used.
+            **in** the set are used. If this argument is True, only IDs from
+            the wrapped matcher that are **not in** the set are used.
         """
 
         super(FilterMatcher, self).__init__(child)
 #    """Matches postings where a list of sub-matchers occur next to each other
 #    in order.
 #    """
-#    
+#
 #    def __init__(self, wordmatchers, slop=1, boost=1.0):
 #        self.wordmatchers = wordmatchers
 #        self.child = make_binary_tree(IntersectionMatcher, wordmatchers)
 #        self.boost = boost
 #        self._spans = None
 #        self._find_next()
-#    
+#
 #    def copy(self):
 #        return self.__class__(self.wordmatchers[:], slop=self.slop,
 #                              boost=self.boost)
-#    
+#
 #    def replace(self, minquality=0):
 #        if not self.is_active():
 #            return NullMatcher()
 #        return self
-#    
+#
 #    def all_ids(self):
 #        # Need to redefine this because the WrappingMatcher parent class
 #        # forwards to the submatcher, which in this case is just the
 #        while self.is_active():
 #            yield self.id()
 #            self.next()
-#    
+#
 #    def next(self):
 #        ri = self.child.next()
 #        rn = self._find_next()
 #        return ri or rn
-#    
+#
 #    def skip_to(self, id):
 #        rs = self.child.skip_to(id)
 #        rn = self._find_next()
 #        return rs or rn
-#    
+#
 #    def skip_to_quality(self, minquality):
 #        skipped = 0
 #        while self.is_active() and self.quality() <= minquality:
 #            skipped += self.child.skip_to_quality(minquality/self.boost)
 #            self._find_next()
 #        return skipped
-#    
+#
 #    def positions(self):
 #        if not self.is_active():
 #            raise ReadTooFar
 #        if not self.wordmatchers:
 #            return []
 #        return self.wordmatchers[0].positions()
-#    
+#
 #    def _find_next(self):
 #        isect = self.child
 #        slop = self.slop
-#        
+#
 #        # List of "active" positions
 #        current = []
-#        
+#
 #        while not current and isect.is_active():
 #            # [[list of positions for word 1],
 #            #  [list of positions for word 2], ...]
 #            poses = [m.positions() for m in self.wordmatchers]
-#            
+#
 #            # Set the "active" position list to the list of positions of the
 #            # first word. We well then iteratively update this list with the
 #            # positions of subsequent words if they are within the "slop"
 #            # distance of the positions in the active list.
 #            current = poses[0]
-#            
+#
 #            # For each list of positions for the subsequent words...
 #            for poslist in poses[1:]:
 #                # A list to hold the new list of active positions
 #                newposes = []
-#                
+#
 #                # For each position in the list of positions in this next word
 #                for newpos in poslist:
 #                    # Use bisect to only check the part of the current list
 #                    # of the new position
 #                    start = bisect_left(current, newpos - slop)
 #                    end = bisect_right(current, newpos)
-#                    
-#                    # 
+#
+#                    #
 #                    for curpos in current[start:end]:
 #                        delta = newpos - curpos
 #                        if delta > 0 and delta <= slop:
 #                            newposes.append(newpos)
-#                    
+#
 #                current = newposes
 #                if not current: break
-#            
+#
 #            if not current:
 #                isect.next()
-#        
+#
 #        self._count = len(current)
 #
 #
 #    """Phrase matcher for fields with a vector with positions (i.e. Positions
 #    or CharacterPositions format).
 #    """
-#    
+#
 #    def __init__(self, searcher, fieldname, words, isect, slop=1, boost=1.0):
 #        """
 #        :param searcher: a Searcher object.
 #        :param words: a sequence of token texts representing the words in the
 #            phrase.
 #        :param isect: an intersection matcher for the words in the phrase.
-#        :param slop: 
+#        :param slop:
 #        """
-#        
+#
 #        decodefn = searcher.field(fieldname).vector.decoder("positions")
 #        self.reader = searcher.reader()
 #        self.fieldname = fieldname
 #        self.sortedwords = sorted(self.words)
 #        super(VectorPhraseMatcher, self).__init__(isect, decodefn, slop=slop,
 #                                                  boost=boost)
-#    
+#
 #    def _poses(self):
 #        vreader = self.reader.vector(self.child.id(), self.fieldname)
 #        poses = {}