Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libdifflib.tex @ 16682:3cb00cbe7455 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documentation for the difflib module, converted from the module docstrings.
author Fred Drake <fdrake@acm.org>
date Mon, 19 Feb 2001 16:31:02 +0000
parents
children 8172906c6dc8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{difflib} ---
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2 Helpers for computing deltas}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{standard}{difflib}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 \modulesynopsis{Helpers for computing differences between objects.}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \moduleauthor{Tim Peters}{tim.one@home.com}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7 \sectionauthor{Tim Peters}{tim.one@home.com}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8 % LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 \begin{funcdesc}{get_close_matches}{word, possibilities\optional{,
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 n\optional{, cutoff}}}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 Return a list of the best ``good enough'' matches. \var{word} is a
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13 sequence for which close matches are desired (typically a string),
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14 and \var{possibilities} is a list of sequences against which to
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15 match \var{word} (typically a list of strings).
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17 Optional argument \var{n} (default \code{3}) is the maximum number
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18 of close matches to return; \var{n} must be greater than \code{0}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20 Optional argument \var{cutoff} (default \code{0.6}) is a float in
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21 the range [0, 1]. Possibilities that don't score at least that
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 similar to \var{word} are ignored.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24 The best (no more than \var{n}) matches among the possibilities are
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25 returned in a list, sorted by similarity score, most similar first.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 >>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 ['apple', 'ape']
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 >>> import keyword
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 >>> get_close_matches('wheel', keyword.kwlist)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32 ['while']
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 >>> get_close_matches('apple', keyword.kwlist)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34 []
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 >>> get_close_matches('accept', keyword.kwlist)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 ['except']
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38 \end{funcdesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40 \begin{classdesc}{SequenceMatcher}{\unspecified}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41 This is a flexible class for comparing pairs of sequences of any
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 type, so long as the sequence elements are hashable. The basic
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43 algorithm predates, and is a little fancier than, an algorithm
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 published in the late 1980's by Ratcliff and Obershelp under the
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45 hyperbolic name ``gestalt pattern matching.'' The idea is to find
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 the longest contiguous matching subsequence that contains no
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47 ``junk'' elements (the Ratcliff and Obershelp algorithm doesn't
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
48 address junk). The same idea is then applied recursively to the
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 pieces of the sequences to the left and to the right of the matching
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50 subsequence. This does not yield minimal edit sequences, but does
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 tend to yield matches that ``look right'' to people.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 \strong{Timing:} The basic Ratcliff-Obershelp algorithm is cubic
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 time in the worst case and quadratic time in the expected case.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 \class{SequenceMatcher} is quadratic time for the worst case and has
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 expected-case behavior dependent on how many elements the sequences
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 have in common; best case time (no elements in common) is linear.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 \end{classdesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 \subsection{SequenceMatcher Objects \label{sequence-matcher}}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 \begin{classdesc}{SequenceMatcher}{\optional{isjunk\optional{,
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 a\optional{, b}}}}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 Optional argument \var{isjunk} must be \code{None} (the default) or
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 a one-argument function that takes a sequence element and returns
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 true if and only if the element is ``junk'' and should be ignored.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 \code{None} is equivalent to passing \code{lambda x: 0}, i.e.\ no
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 elements are ignored. For example, pass
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 lambda x: x in " \\t"
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 if you're comparing lines as sequences of characters, and don't want
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 to synch up on blanks or hard tabs.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 The optional arguments \var{a} and \var{b} are sequences to be
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 compared; both default to empty strings. The elements of both
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 sequences must be hashable.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 \end{classdesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 \class{SequenceMatcher} objects have the following methods:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 \begin{methoddesc}{set_seqs}{a, b}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87 Set the two sequences to be compared.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90 \class{SequenceMatcher} computes and caches detailed information about
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 the second sequence, so if you want to compare one sequence against
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
92 many sequences, use \method{set_seq2()} to set the commonly used
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93 sequence once and call \method{set_seq1()} repeatedly, once for each
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94 of the other sequences.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 \begin{methoddesc}{set_seq1}{a}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
97 Set the first sequence to be compared. The second sequence to be
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98 compared is not changed.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
99 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
100
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
101 \begin{methoddesc}{set_seq2}{b}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
102 Set the second sequence to be compared. The first sequence to be
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 compared is not changed.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
105
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
106 \begin{methoddesc}{find_longest_match}{alo, ahi, blo, bhi}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 Find longest matching block in \code{\var{a}[\var{alo}:\var{ahi}]}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 and \code{\var{b}[\var{blo}:\var{bhi}]}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 If \var{isjunk} was omitted or \code{None},
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 \method{get_longest_match()} returns \code{(\var{i}, \var{j},
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112 \var{k})} such that \code{\var{a}[\var{i}:\var{i}+\var{k}]} is equal
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113 to \code{\var{b}[\var{j}:\var{j}+\var{k}]}, where
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 \code{\var{alo} <= \var{i} <= \var{i}+\var{k} <= \var{ahi}} and
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 \code{\var{blo} <= \var{j} <= \var{j}+\var{k} <= \var{bhi}}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116 For all \code{(\var{i'}, \var{j'}, \var{k'})} meeting those
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 conditions, the additional conditions
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118 \code{\var{k} >= \var{k'}},
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119 \code{\var{i} <= \var{i'}},
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 and if \code{\var{i} == \var{i'}}, \code{\var{j} <= \var{j'}}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121 are also met.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 In other words, of all maximal matching blocks, return one that
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123 starts earliest in \var{a}, and of all those maximal matching blocks
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124 that start earliest in \var{a}, return the one that starts earliest
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 in \var{b}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128 >>> s = SequenceMatcher(None, " abcd", "abcd abcd")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
129 >>> s.find_longest_match(0, 5, 0, 9)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130 (0, 4, 5)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
132
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
133 If \var{isjunk} was provided, first the longest matching block is
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
134 determined as above, but with the additional restriction that no
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
135 junk element appears in the block. Then that block is extended as
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
136 far as possible by matching (only) junk elements on both sides.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
137 So the resulting block never matches on junk except as identical
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
138 junk happens to be adjacent to an interesting match.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
139
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
140 Here's the same example as before, but considering blanks to be junk.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
141 That prevents \code{' abcd'} from matching the \code{ abcd} at the
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
142 tail end of the second sequence directly. Instead only the
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
143 \code{'abcd'} can match, and matches the leftmost \code{'abcd'} in
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
144 the second sequence:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
145
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
146 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
147 >>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
148 >>> s.find_longest_match(0, 5, 0, 9)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
149 (1, 0, 4)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
150 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
151
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
152 If no blocks match, this returns \code{(\var{alo}, \var{blo}, 0)}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
154
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
155 \begin{methoddesc}{get_matching_blocks}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
156 Return list of triples describing matching subsequences.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
157 Each triple is of the form \code{(\var{i}, \var{j}, \var{n})}, and
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
158 means that \code{\var{a}[\var{i}:\var{i}+\var{n}] ==
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
159 \var{b}[\var{j}:\var{j}+\var{n}]}. The triples are monotonically
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
160 increasing in \var{i} and \var{j}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
161
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
162 The last triple is a dummy, and has the value \code{(len(\var{a}),
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
163 len(\var{b}), 0)}. It is the only triple with \code{\var{n} == 0}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164 % Explain why a dummy is used!
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
166 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167 >>> s = SequenceMatcher(None, "abxcd", "abcd")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168 >>> s.get_matching_blocks()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
169 [(0, 0, 2), (3, 2, 2), (5, 4, 0)]
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173 \begin{methoddesc}{get_opcodes}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174 Return list of 5-tuples describing how to turn \var{a} into \var{b}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 Each tuple is of the form \code{(\var{tag}, \var{i1}, \var{i2},
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
176 \var{j1}, \var{j2})}. The first tuple has \code{\var{i1} ==
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
177 \var{j1} == 0}, and remaining tuples have \var{i1} equal to the
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
178 \var{i2} from the preceeding tuple, and, likewise, \var{j1} equal to
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
179 the previous \var{j2}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
181 The \var{tag} values are strings, with these meanings:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
182
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
183 \begin{tableii}{l|l}{code}{Value}{Meaning}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
184 \lineii{'replace'}{\code{\var{a}[\var{i1}:\var{i2}]} should be
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
185 replaced by \code{\var{b}[\var{j1}:\var{j2}]}.}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
186 \lineii{'delete'}{\code{\var{a}[\var{i1}:\var{i2}]} should be
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
187 deleted. Note that \code{\var{j1} == \var{j2}} in
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 this case.}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
189 \lineii{'insert'}{\code{\var{b}[\var{j1}:\var{j2}]} should be
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
190 inserted at \code{\var{a}[\var{i1}:\var{i1}]}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
191 Note that \code{\var{i1} == \var{i2}} in this
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
192 case.}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
193 \lineii{'equal'}{\code{\var{a}[\var{i1}:\var{i2}] ==
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
194 \var{b}[\var{j1}:\var{j2}]} (the sub-sequences are
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
195 equal).}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
196 \end{tableii}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
197
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
198 For example:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
199
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
200 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
201 >>> a = "qabxcd"
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
202 >>> b = "abycdf"
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
203 >>> s = SequenceMatcher(None, a, b)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
204 >>> for tag, i1, i2, j1, j2 in s.get_opcodes():
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
205 ... print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
206 ... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
207 delete a[0:1] (q) b[0:0] ()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
208 equal a[1:3] (ab) b[0:2] (ab)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
209 replace a[3:4] (x) b[2:3] (y)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
210 equal a[4:6] (cd) b[3:5] (cd)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
211 insert a[6:6] () b[5:6] (f)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
212 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
213 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
214
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
215 \begin{methoddesc}{ratio}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
216 Return a measure of the sequences' similarity as a float in the
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
217 range [0, 1].
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
218
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
219 Where T is the total number of elements in both sequences, and M is
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
220 the number of matches, this is 2,0*M / T. Note that this is \code{1}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
221 if the sequences are identical, and \code{0} if they have nothing in
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
222 common.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
223
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
224 This is expensive to compute if \method{get_matching_blocks()} or
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
225 \method{get_opcodes()} hasn't already been called, in which case you
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
226 may want to try \method{quick_ratio()} or
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
227 \method{real_quick_ratio()} first to get an upper bound.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
228 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
229
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
230 \begin{methoddesc}{quick_ratio}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
231 Return an upper bound on \method{ratio()} relatively quickly.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
232
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
233 This isn't defined beyond that it is an upper bound on
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
234 \method{ratio()}, and is faster to compute.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
235 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
236
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
237 \begin{methoddesc}{real_quick_ratio}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
238 Return an upper bound on \method{ratio()} very quickly.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
239
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240 This isn't defined beyond that it is an upper bound on
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
241 \method{ratio()}, and is faster to compute than either
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
242 \method{ratio()} or \method{quick_ratio()}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
243 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
244
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
245 The three methods that return the ratio of differences to similarities
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
246 can give different results due to differing levels of approximation:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
247
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
248 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
249 >>> s = SequenceMatcher(None, "abcd", "bcde")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
250 >>> s.ratio()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
251 0.75
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
252 >>> s.quick_ratio()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
253 0.75
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
254 >>> s.real_quick_ratio()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
255 1.0
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
256 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
257
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
258
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
259 \subsection{Examples \label{difflib-examples}}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
260
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
261
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
262 This example compares two strings, considering blanks to be ``junk:''
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
263
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
264 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
265 >>> s = SequenceMatcher(lambda x: x == " ",
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
266 ... "private Thread currentThread;",
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
267 ... "private volatile Thread currentThread;")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
268 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
269
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
270 \method{ratio()} returns a float in [0, 1], measuring the similarity
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
271 of the sequences. As a rule of thumb, a \method{ratio()} value over
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
272 0.6 means the sequences are close matches:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
273
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
274 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
275 >>> print round(s.ratio(), 3)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
276 0.866
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
277 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
278
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
279 If you're only interested in where the sequences match,
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
280 \method{get_matching_blocks()} is handy:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
281
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
282 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
283 >>> for block in s.get_matching_blocks():
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
284 ... print "a[%d] and b[%d] match for %d elements" % block
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
285 a[0] and b[0] match for 8 elements
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
286 a[8] and b[17] match for 6 elements
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
287 a[14] and b[23] match for 15 elements
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
288 a[29] and b[38] match for 0 elements
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
289 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
290
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
291 Note that the last tuple returned by \method{get_matching_blocks()} is
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
292 always a dummy, \code{(len(\var{a}), len(\var{b}), 0)}, and this is
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
293 the only case in which the last tuple element (number of elements
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
294 matched) is \code{0}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
295
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
296 If you want to know how to change the first sequence into the second,
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
297 use \method{get_opcodes()}:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
298
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
299 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
300 >>> for opcode in s.get_opcodes():
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
301 ... print "%6s a[%d:%d] b[%d:%d]" % opcode
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
302 equal a[0:8] b[0:8]
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
303 insert a[8:8] b[8:17]
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
304 equal a[8:14] b[17:23]
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
305 equal a[14:29] b[23:38]
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
306 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
307
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
308 See \file{Tools/scripts/ndiff.py} from the Python source distribution
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
309 for a fancy human-friendly file differencer, which uses
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
310 \class{SequenceMatcher} both to view files as sequences of lines, and
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
311 lines as sequences of characters.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
312
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
313 See also the function \function{get_close_matches()} in this module,
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
314 which shows how simple code building on \class{SequenceMatcher} can be
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
315 used to do useful work.