Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libdifflib.tex @ 31411:bbc944e1fecc 2.3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add direct link to the article in DDJ closes SF bug #871402
author Fred Drake <fdrake@acm.org>
date Wed, 21 Jan 2004 18:31:16 +0000
parents 8c5a6853a02a
children
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
17388
e4abe74bc973 Add note that difflib was added in Python 2.1.
Fred Drake <fdrake@acm.org>
parents: 17382
diff changeset
10 \versionadded{2.1}
e4abe74bc973 Add note that difflib was added in Python 2.1.
Fred Drake <fdrake@acm.org>
parents: 17382
diff changeset
11
e4abe74bc973 Add note that difflib was added in Python 2.1.
Fred Drake <fdrake@acm.org>
parents: 17382
diff changeset
12
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
13 \begin{classdesc*}{SequenceMatcher}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
14 This is a flexible class for comparing pairs of sequences of any
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
15 type, so long as the sequence elements are hashable. The basic
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
16 algorithm predates, and is a little fancier than, an algorithm
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
17 published in the late 1980's by Ratcliff and Obershelp under the
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
18 hyperbolic name ``gestalt pattern matching.'' The idea is to find
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
19 the longest contiguous matching subsequence that contains no
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
20 ``junk'' elements (the Ratcliff and Obershelp algorithm doesn't
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
21 address junk). The same idea is then applied recursively to the
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
22 pieces of the sequences to the left and to the right of the matching
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
23 subsequence. This does not yield minimal edit sequences, but does
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
24 tend to yield matches that ``look right'' to people.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
25
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
26 \strong{Timing:} The basic Ratcliff-Obershelp algorithm is cubic
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
27 time in the worst case and quadratic time in the expected case.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
28 \class{SequenceMatcher} is quadratic time for the worst case and has
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
29 expected-case behavior dependent in a complicated way on how many
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
30 elements the sequences have in common; best case time is linear.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
31 \end{classdesc*}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
32
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
33 \begin{classdesc*}{Differ}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
34 This is a class for comparing sequences of lines of text, and
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
35 producing human-readable differences or deltas. Differ uses
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
36 \class{SequenceMatcher} both to compare sequences of lines, and to
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
37 compare sequences of characters within similar (near-matching)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
38 lines.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
39
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
40 Each line of a \class{Differ} delta begins with a two-letter code:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
41
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
42 \begin{tableii}{l|l}{code}{Code}{Meaning}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
43 \lineii{'- '}{line unique to sequence 1}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
44 \lineii{'+ '}{line unique to sequence 2}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
45 \lineii{' '}{line common to both sequences}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
46 \lineii{'? '}{line not present in either input sequence}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
47 \end{tableii}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
48
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
49 Lines beginning with `\code{?~}' attempt to guide the eye to
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
50 intraline differences, and were not present in either input
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
51 sequence. These lines can be confusing if the sequences contain tab
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
52 characters.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
53 \end{classdesc*}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
54
29398
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
55 \begin{funcdesc}{context_diff}{a, b\optional{, fromfile\optional{, tofile
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
56 \optional{, fromfiledate\optional{, tofiledate\optional{, n
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
57 \optional{, lineterm}}}}}}}
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
58
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
59 Compare \var{a} and \var{b} (lists of strings); return a
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
60 delta (a generator generating the delta lines) in context diff
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
61 format.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
62
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
63 Context diffs are a compact way of showing just the lines that have
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
64 changed plus a few lines of context. The changes are shown in a
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
65 before/after style. The number of context lines is set by \var{n}
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
66 which defaults to three.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
67
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
68 By default, the diff control lines (those with \code{***} or \code{---})
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
69 are created with a trailing newline. This is helpful so that inputs created
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
70 from \function{file.readlines()} result in diffs that are suitable for use
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
71 with \function{file.writelines()} since both the inputs and outputs have
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
72 trailing newlines.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
73
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
74 For inputs that do not have trailing newlines, set the \var{lineterm}
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
75 argument to \code{""} so that the output will be uniformly newline free.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
76
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
77 The context diff format normally has a header for filenames and
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
78 modification times. Any or all of these may be specified using strings for
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
79 \var{fromfile}, \var{tofile}, \var{fromfiledate}, and \var{tofiledate}.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
80 The modification times are normally expressed in the format returned by
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
81 \function{time.ctime()}. If not specified, the strings default to blanks.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
82
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
83 \file{Tools/scripts/diff.py} is a command-line front-end for this
29404
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
84 function.
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
85
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
86 \versionadded{2.3}
29398
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
87 \end{funcdesc}
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
88
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 \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
90 n\optional{, cutoff}}}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 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
92 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
93 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
94 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
95
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 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
97 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
98
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
99 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
100 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
101 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
102
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 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
104 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
105
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
106 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 >>> 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
108 ['apple', 'ape']
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 >>> import keyword
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 >>> 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
111 ['while']
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112 >>> 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
113 []
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 >>> 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
115 ['except']
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 \end{funcdesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
119 \begin{funcdesc}{ndiff}{a, b\optional{, linejunk\optional{,
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
120 charjunk}}}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
121 Compare \var{a} and \var{b} (lists of strings); return a
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
122 \class{Differ}-style delta (a generator generating the delta lines).
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
123
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
124 Optional keyword parameters \var{linejunk} and \var{charjunk} are
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
125 for filter functions (or \code{None}):
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
126
23300
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
127 \var{linejunk}: A function that accepts a single string
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
128 argument, and returns true if the string is junk, or false if not.
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
129 The default is (\code{None}), starting with Python 2.3. Before then,
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
130 the default was the module-level function
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
131 \function{IS_LINE_JUNK()}, which filters out lines without visible
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
132 characters, except for at most one pound character (\character{\#}).
23300
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
133 As of Python 2.3, the underlying \class{SequenceMatcher} class
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
134 does a dynamic analysis of which lines are so frequent as to
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
135 constitute noise, and this usually works better than the pre-2.3
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
136 default.
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
137
23300
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
138 \var{charjunk}: A function that accepts a character (a string of
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
139 length 1), and returns if the character is junk, or false if not.
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
140 The default is module-level function \function{IS_CHARACTER_JUNK()},
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
141 which filters out whitespace characters (a blank or tab; note: bad
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
142 idea to include newline in this!).
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
143
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
144 \file{Tools/scripts/ndiff.py} is a command-line front-end to this
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
145 function.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
146
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
147 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
148 >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
26556
242ad5c592cc Remove extra ")" in example.
Fred Drake <fdrake@acm.org>
parents: 23300
diff changeset
149 ... 'ore\ntree\nemu\n'.splitlines(1))
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
150 >>> print ''.join(diff),
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
151 - one
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
152 ? ^
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
153 + ore
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
154 ? ^
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
155 - two
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
156 - three
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
157 ? -
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
158 + tree
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
159 + emu
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
160 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
161 \end{funcdesc}
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
162
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
163 \begin{funcdesc}{restore}{sequence, which}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
164 Return one of the two sequences that generated a delta.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
165
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
166 Given a \var{sequence} produced by \method{Differ.compare()} or
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
167 \function{ndiff()}, extract lines originating from file 1 or 2
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
168 (parameter \var{which}), stripping off line prefixes.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
169
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
170 Example:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
171
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
172 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
173 >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
174 ... 'ore\ntree\nemu\n'.splitlines(1))
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
175 >>> diff = list(diff) # materialize the generated delta into a list
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
176 >>> print ''.join(restore(diff, 1)),
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
177 one
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
178 two
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
179 three
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
180 >>> print ''.join(restore(diff, 2)),
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
181 ore
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
182 tree
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
183 emu
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
184 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
185
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
186 \end{funcdesc}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
187
29398
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
188 \begin{funcdesc}{unified_diff}{a, b\optional{, fromfile\optional{, tofile
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
189 \optional{, fromfiledate\optional{, tofiledate\optional{, n
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
190 \optional{, lineterm}}}}}}}
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
191
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
192 Compare \var{a} and \var{b} (lists of strings); return a
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
193 delta (a generator generating the delta lines) in unified diff
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
194 format.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
195
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
196 Unified diffs are a compact way of showing just the lines that have
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
197 changed plus a few lines of context. The changes are shown in a
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
198 inline style (instead of separate before/after blocks). The number
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
199 of context lines is set by \var{n} which defaults to three.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
200
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
201 By default, the diff control lines (those with \code{---}, \code{+++},
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
202 or \code{@@}) are created with a trailing newline. This is helpful so
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
203 that inputs created from \function{file.readlines()} result in diffs
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
204 that are suitable for use with \function{file.writelines()} since both
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
205 the inputs and outputs have trailing newlines.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
206
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
207 For inputs that do not have trailing newlines, set the \var{lineterm}
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
208 argument to \code{""} so that the output will be uniformly newline free.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
209
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
210 The context diff format normally has a header for filenames and
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
211 modification times. Any or all of these may be specified using strings for
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
212 \var{fromfile}, \var{tofile}, \var{fromfiledate}, and \var{tofiledate}.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
213 The modification times are normally expressed in the format returned by
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
214 \function{time.ctime()}. If not specified, the strings default to blanks.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
215
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
216 \file{Tools/scripts/diff.py} is a command-line front-end for this
29404
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
217 function.
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
218
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
219 \versionadded{2.3}
29398
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
220 \end{funcdesc}
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
221
20677
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
222 \begin{funcdesc}{IS_LINE_JUNK}{line}
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
223 Return true for ignorable lines. The line \var{line} is ignorable
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
224 if \var{line} is blank or contains a single \character{\#},
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
225 otherwise it is not ignorable. Used as a default for parameter
23300
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
226 \var{linejunk} in \function{ndiff()} before Python 2.3.
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
227 \end{funcdesc}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
228
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
229
20677
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
230 \begin{funcdesc}{IS_CHARACTER_JUNK}{ch}
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
231 Return true for ignorable characters. The character \var{ch} is
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
232 ignorable if \var{ch} is a space or tab, otherwise it is not
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
233 ignorable. Used as a default for parameter \var{charjunk} in
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
234 \function{ndiff()}.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
235 \end{funcdesc}
16682
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
17382
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
238 \begin{seealso}
31411
bbc944e1fecc add direct link to the article in DDJ
Fred Drake <fdrake@acm.org>
parents: 29404
diff changeset
239 \seetitle[http://www.ddj.com/documents/s=1103/ddj8807c/]
bbc944e1fecc add direct link to the article in DDJ
Fred Drake <fdrake@acm.org>
parents: 29404
diff changeset
240 {Pattern Matching: The Gestalt Approach}{Discussion of a
17382
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
241 similar algorithm by John W. Ratcliff and D. E. Metzener.
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
242 This was published in
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
243 \citetitle[http://www.ddj.com/]{Dr. Dobb's Journal} in
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
244 July, 1988.}
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
245 \end{seealso}
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
246
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
247
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
248 \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
249
17780
a1575dbf7d81 Replace "\begin{classdesc}{SomeClass}{\unspecified}" with
Fred Drake <fdrake@acm.org>
parents: 17388
diff changeset
250 The \class{SequenceMatcher} class has this constructor:
a1575dbf7d81 Replace "\begin{classdesc}{SomeClass}{\unspecified}" with
Fred Drake <fdrake@acm.org>
parents: 17388
diff changeset
251
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
252 \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
253 a\optional{, b}}}}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
254 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
255 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
256 true if and only if the element is ``junk'' and should be ignored.
20677
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
257 Passing \code{None} for \var{b} is equivalent to passing
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
258 \code{lambda x: 0}; in other words, no elements are ignored. For
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
259 example, pass:
16682
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 \begin{verbatim}
16758
8996288a8873 Fix extra backslash in example.
Fred Drake <fdrake@acm.org>
parents: 16703
diff changeset
262 lambda x: x in " \t"
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
263 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
264
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
265 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
266 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
267
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
268 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
269 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
270 sequences must be hashable.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
271 \end{classdesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
272
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 \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
275
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
276 \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
277 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
278 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
279
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
280 \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
281 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
282 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
283 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
284 of the other sequences.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
285
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
286 \begin{methoddesc}{set_seq1}{a}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
287 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
288 compared is not changed.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
289 \end{methoddesc}
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 \begin{methoddesc}{set_seq2}{b}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
292 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
293 compared is not changed.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
294 \end{methoddesc}
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 \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
297 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
298 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
299
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
300 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
301 \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
302 \var{k})} such that \code{\var{a}[\var{i}:\var{i}+\var{k}]} is equal
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
303 to \code{\var{b}[\var{j}:\var{j}+\var{k}]}, where
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
304 \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
305 \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
306 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
307 conditions, the additional conditions
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
308 \code{\var{k} >= \var{k'}},
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
309 \code{\var{i} <= \var{i'}},
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
310 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
311 are also met.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
312 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
313 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
314 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
315 in \var{b}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
316
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
317 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
318 >>> 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
319 >>> 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
320 (0, 4, 5)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
321 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
322
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
323 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
324 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
325 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
326 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
327 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
328 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
329
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
330 Here's the same example as before, but considering blanks to be junk.
16703
8172906c6dc8 Improve accuracy. In the .tex file, note the new "% BUG:" comments: an
Tim Peters <tim.peters@gmail.com>
parents: 16682
diff changeset
331 That prevents \code{' abcd'} from matching the \code{' abcd'} at the
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
332 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
333 \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
334 the second sequence:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
335
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
336 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
337 >>> 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
338 >>> 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
339 (1, 0, 4)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
340 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
341
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
342 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
343 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
344
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
345 \begin{methoddesc}{get_matching_blocks}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
346 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
347 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
348 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
349 \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
350 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
351
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
352 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
353 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
354 % 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
355
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
356 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
357 >>> s = SequenceMatcher(None, "abxcd", "abcd")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
358 >>> s.get_matching_blocks()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
359 [(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
360 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
361 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
362
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
363 \begin{methoddesc}{get_opcodes}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
364 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
365 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
366 \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
367 \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
368 \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
369 the previous \var{j2}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
370
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
371 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
372
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
373 \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
374 \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
375 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
376 \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
377 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
378 this case.}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
379 \lineii{'insert'}{\code{\var{b}[\var{j1}:\var{j2}]} should be
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
380 inserted at \code{\var{a}[\var{i1}:\var{i1}]}.
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
381 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
382 case.}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
383 \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
384 \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
385 equal).}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
386 \end{tableii}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
387
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
388 For example:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
389
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
390 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
391 >>> a = "qabxcd"
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
392 >>> b = "abycdf"
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
393 >>> s = SequenceMatcher(None, a, b)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
394 >>> 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
395 ... 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
396 ... (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
397 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
398 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
399 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
400 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
401 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
402 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
403 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
404
29404
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
405 \begin{methoddesc}{get_grouped_opcodes}{\optional{n}}
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
406 Return a generator of groups with up to \var{n} lines of context.
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
407
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
408 Starting with the groups returned by \method{get_opcodes()},
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
409 this method splits out smaller change clusters and eliminates
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
410 intervening ranges which have no changes.
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
411
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
412 The groups are returned in the same format as \method{get_opcodes()}.
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
413 \versionadded{2.3}
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
414 \end{methoddesc}
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
415
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
416 \begin{methoddesc}{ratio}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
417 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
418 range [0, 1].
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
419
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
420 Where T is the total number of elements in both sequences, and M is
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
421 the number of matches, this is 2.0*M / T. Note that this is
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
422 \code{1.0} if the sequences are identical, and \code{0.0} if they
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
423 have nothing in common.
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
424
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
425 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
426 \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
427 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
428 \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
429 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
430
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
431 \begin{methoddesc}{quick_ratio}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
432 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
433
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
434 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
435 \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
436 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
437
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
438 \begin{methoddesc}{real_quick_ratio}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
439 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
440
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
441 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
442 \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
443 \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
444 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
445
16703
8172906c6dc8 Improve accuracy. In the .tex file, note the new "% BUG:" comments: an
Tim Peters <tim.peters@gmail.com>
parents: 16682
diff changeset
446 The three methods that return the ratio of matching to total characters
8172906c6dc8 Improve accuracy. In the .tex file, note the new "% BUG:" comments: an
Tim Peters <tim.peters@gmail.com>
parents: 16682
diff changeset
447 can give different results due to differing levels of approximation,
8172906c6dc8 Improve accuracy. In the .tex file, note the new "% BUG:" comments: an
Tim Peters <tim.peters@gmail.com>
parents: 16682
diff changeset
448 although \method{quick_ratio()} and \method{real_quick_ratio()} are always
8172906c6dc8 Improve accuracy. In the .tex file, note the new "% BUG:" comments: an
Tim Peters <tim.peters@gmail.com>
parents: 16682
diff changeset
449 at least as large as \method{ratio()}:
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
450
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
451 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
452 >>> s = SequenceMatcher(None, "abcd", "bcde")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
453 >>> s.ratio()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
454 0.75
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
455 >>> s.quick_ratio()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
456 0.75
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
457 >>> s.real_quick_ratio()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
458 1.0
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
459 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
460
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
461
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
462 \subsection{SequenceMatcher Examples \label{sequencematcher-examples}}
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
463
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
464
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
465 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
466
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
467 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
468 >>> s = SequenceMatcher(lambda x: x == " ",
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
469 ... "private Thread currentThread;",
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
470 ... "private volatile Thread currentThread;")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
471 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
472
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
473 \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
474 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
475 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
476
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
477 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
478 >>> print round(s.ratio(), 3)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
479 0.866
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
480 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
481
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
482 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
483 \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
484
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
485 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
486 >>> 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
487 ... 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
488 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
489 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
490 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
491 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
492 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
493
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
494 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
495 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
496 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
497 matched) is \code{0}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
498
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
499 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
500 use \method{get_opcodes()}:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
501
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
502 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
503 >>> 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
504 ... 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
505 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
506 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
507 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
508 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
509 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
510
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
511 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
512 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
513 used to do useful work.
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
514
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
515
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
516 \subsection{Differ Objects \label{differ-objects}}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
517
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
518 Note that \class{Differ}-generated deltas make no claim to be
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
519 \strong{minimal} diffs. To the contrary, minimal diffs are often
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
520 counter-intuitive, because they synch up anywhere possible, sometimes
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
521 accidental matches 100 pages apart. Restricting synch points to
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
522 contiguous matches preserves some notion of locality, at the
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
523 occasional cost of producing a longer diff.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
524
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
525 The \class{Differ} class has this constructor:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
526
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
527 \begin{classdesc}{Differ}{\optional{linejunk\optional{, charjunk}}}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
528 Optional keyword parameters \var{linejunk} and \var{charjunk} are
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
529 for filter functions (or \code{None}):
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
530
23300
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
531 \var{linejunk}: A function that accepts a single string
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
532 argument, and returns true if the string is junk. The default is
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
533 \code{None}, meaning that no line is considered junk.
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
534
23300
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
535 \var{charjunk}: A function that accepts a single character argument
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
536 (a string of length 1), and returns true if the character is junk.
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
537 The default is \code{None}, meaning that no character is
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
538 considered junk.
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
539 \end{classdesc}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
540
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
541 \class{Differ} objects are used (deltas generated) via a single
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
542 method:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
543
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
544 \begin{methoddesc}{compare}{a, b}
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
545 Compare two sequences of lines, and generate the delta (a sequence
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
546 of lines).
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
547
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
548 Each sequence must contain individual single-line strings ending
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
549 with newlines. Such sequences can be obtained from the
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
550 \method{readlines()} method of file-like objects. The delta generated
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
551 also consists of newline-terminated strings, ready to be printed as-is
21106
3827f136e0d6 writeline() --> writelines()
Fred Drake <fdrake@acm.org>
parents: 20677
diff changeset
552 via the \method{writelines()} method of a file-like object.
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
553 \end{methoddesc}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
554
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
555
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
556 \subsection{Differ Example \label{differ-examples}}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
557
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
558 This example compares two texts. First we set up the texts, sequences
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
559 of individual single-line strings ending with newlines (such sequences
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
560 can also be obtained from the \method{readlines()} method of file-like
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
561 objects):
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
562
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
563 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
564 >>> text1 = ''' 1. Beautiful is better than ugly.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
565 ... 2. Explicit is better than implicit.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
566 ... 3. Simple is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
567 ... 4. Complex is better than complicated.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
568 ... '''.splitlines(1)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
569 >>> len(text1)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
570 4
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
571 >>> text1[0][-1]
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
572 '\n'
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
573 >>> text2 = ''' 1. Beautiful is better than ugly.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
574 ... 3. Simple is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
575 ... 4. Complicated is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
576 ... 5. Flat is better than nested.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
577 ... '''.splitlines(1)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
578 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
579
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
580 Next we instantiate a Differ object:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
581
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
582 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
583 >>> d = Differ()
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
584 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
585
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
586 Note that when instantiating a \class{Differ} object we may pass
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
587 functions to filter out line and character ``junk.'' See the
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
588 \method{Differ()} constructor for details.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
589
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
590 Finally, we compare the two:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
591
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
592 \begin{verbatim}
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
593 >>> result = list(d.compare(text1, text2))
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
594 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
595
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
596 \code{result} is a list of strings, so let's pretty-print it:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
597
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
598 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
599 >>> from pprint import pprint
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
600 >>> pprint(result)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
601 [' 1. Beautiful is better than ugly.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
602 '- 2. Explicit is better than implicit.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
603 '- 3. Simple is better than complex.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
604 '+ 3. Simple is better than complex.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
605 '? ++ \n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
606 '- 4. Complex is better than complicated.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
607 '? ^ ---- ^ \n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
608 '+ 4. Complicated is better than complex.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
609 '? ++++ ^ ^ \n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
610 '+ 5. Flat is better than nested.\n']
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
611 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
612
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
613 As a single multi-line string it looks like this:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
614
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
615 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
616 >>> import sys
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
617 >>> sys.stdout.writelines(result)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
618 1. Beautiful is better than ugly.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
619 - 2. Explicit is better than implicit.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
620 - 3. Simple is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
621 + 3. Simple is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
622 ? ++
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
623 - 4. Complex is better than complicated.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
624 ? ^ ---- ^
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
625 + 4. Complicated is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
626 ? ++++ ^ ^
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
627 + 5. Flat is better than nested.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
628 \end{verbatim}