classification
Title: difflib.SequenceMatcher and Match: code and doc bugs
Type: behavior Stage:
Components: Documentation, Library (Lib) Versions: Python 3.3, Python 3.2, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: rhettinger, terry.reedy
Priority: low Keywords:

Created on 2011-06-21 20:00 by terry.reedy, last changed 2011-06-26 14:17 by rhettinger.

Messages (3)
msg138799 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-06-21 20:00
The basic problem: in 2.6, a namedtuple was introduced to difflib

from collections import namedtuple as _namedtuple
Match = _namedtuple('Match', 'a b size')

and used for the return values of SeqeunceMatcher.get_longest_match and .get_matching_blocks. Code, docstrings, and docs were only partially updated to match.

Code:

    def get_matching_blocks(self):
        """Return list of triples describing matching subsequences.
        Each triple is of the form (i, j, n), and means that
        ...'''
        if self.matching_blocks is not None:
            return self.matching_blocks
        ...
        self.matching_blocks = non_adjacent
        return map(Match._make, self.matching_blocks)

The two returns are different because only the second was changed.
The obvious fix is to change the first to match. Or perhaps self.matching_blocks (an undocumented cache) should be the map object.

Docstring and doc for .find_longest_match():

Both start
 "Find longest matching block ... returns (i, j, k) such that ... "
Doc (bug not docstring) explicitly says at the *bottom* of the entry "This method returns a named tuple Match(a, b, size)."
which is different from (i,j,n). For 2.7, the note is preceded by "Changed in version 2.6:"
The examples show the change before it is described.

I think that the current return should be accurately described at the *top* of the entry, not the bottom. 2.7 would then end with "Changed in version 2.6: return Match instead of tuple."

Docstring and doc for .get_matching_blocks():

See code snippet above for beginning of text. Unlike .find_longest_match, there is no mention of the changed return.

In 2.7, it is a list of Match triples.
In 3.x, it is an iterable (Map) of Match triples, because of the change in map() return.

For the latter reason, the example in the 3.x doc must be changed to
>>> list(s.get_matching_blocks())

The docstring was already changed to pass doctest. The untested doc was not.

I am not sure how to properly document the use of a namedtuple in the stdlib. Raymond, what do you think?
msg138804 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-06-21 22:15
I'll take a look at this when I get a chance (est. two weeks).
msg139179 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-06-26 14:17
Go head an patch the first self.matching_blocks to also return a named tuple.  Also, correct any doctests or examples using these.

The docs could also mention that list of namedtuples with fields a, b, and size is returned by get_matching_blocks().
History
Date User Action Args
2011-06-26 14:17:16rhettingersetpriority: normal -> low
assignee: rhettinger -> terry.reedy
messages: + msg139179
2011-06-21 22:15:25rhettingersetmessages: + msg138804
2011-06-21 20:00:41terry.reedycreate