Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libdifflib.tex @ 38811:4558916b841f legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
SequenceMatcher.get_matching_blocks(): This now guarantees that adjacent triples in the result list describe non-adjacent matching blocks. That's _nice_ to have, and Guido said he wanted it. Not a bugfix candidate: Guido or not ;-), this changes visible endcase semantics (note that some tests had to change), and nothing about this was documented before. Since it was working as designed, and behavior was consistent with the docs, it wasn't "a bug".
author Tim Peters <tim.peters@gmail.com>
date Wed, 14 Jun 2006 04:09:25 +0000
parents 67f2190e1f6d
children 00c02c4488ce
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.}
31275
8c13ab69ba4f - update Tim's email address
Fred Drake <fdrake@acm.org>
parents: 29404
diff changeset
6 \moduleauthor{Tim Peters}{tim_one@users.sourceforge.net}
8c13ab69ba4f - update Tim's email address
Fred Drake <fdrake@acm.org>
parents: 29404
diff changeset
7 \sectionauthor{Tim Peters}{tim_one@users.sourceforge.net}
16682
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
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
55 \begin{classdesc*}{HtmlDiff}
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
56
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
57 This class can be used to create an HTML table (or a complete HTML file
33448
5570fae1f01c Typo fix: 'comparisions' is not a word
Andrew M. Kuchling <amk@amk.ca>
parents: 33319
diff changeset
58 containing the table) showing a side by side, line by line comparison
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
59 of text with inter-line and intra-line change highlights. The table can
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
60 be generated in either full or contextual difference mode.
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
61
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
62 The constructor for this class is:
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
63
33754
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
64 \begin{funcdesc}{__init__}{\optional{tabsize}\optional{,
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
65 wrapcolumn}\optional{, linejunk}\optional{, charjunk}}
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
66
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
67 Initializes instance of \class{HtmlDiff}.
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
68
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
69 \var{tabsize} is an optional keyword argument to specify tab stop spacing
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
70 and defaults to \code{8}.
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
71
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
72 \var{wrapcolumn} is an optional keyword to specify column number where
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
73 lines are broken and wrapped, defaults to \code{None} where lines are not
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
74 wrapped.
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
75
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
76 \var{linejunk} and \var{charjunk} are optional keyword arguments passed
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
77 into \code{ndiff()} (used by \class{HtmlDiff} to generate the
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
78 side by side HTML differences). See \code{ndiff()} documentation for
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
79 argument default values and descriptions.
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
80
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
81 \end{funcdesc}
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
82
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
83 The following methods are public:
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
84
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
85 \begin{funcdesc}{make_file}{fromlines, tolines
33754
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
86 \optional{, fromdesc}\optional{, todesc}\optional{, context}\optional{,
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
87 numlines}}
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
88 Compares \var{fromlines} and \var{tolines} (lists of strings) and returns
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
89 a string which is a complete HTML file containing a table showing line by
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
90 line differences with inter-line and intra-line changes highlighted.
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
91
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
92 \var{fromdesc} and \var{todesc} are optional keyword arguments to specify
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
93 from/to file column header strings (both default to an empty string).
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
94
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
95 \var{context} and \var{numlines} are both optional keyword arguments.
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
96 Set \var{context} to \code{True} when contextual differences are to be
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
97 shown, else the default is \code{False} to show the full files.
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
98 \var{numlines} defaults to \code{5}. When \var{context} is \code{True}
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
99 \var{numlines} controls the number of context lines which surround the
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
100 difference highlights. When \var{context} is \code{False} \var{numlines}
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
101 controls the number of lines which are shown before a difference
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
102 highlight when using the "next" hyperlinks (setting to zero would cause
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
103 the "next" hyperlinks to place the next difference highlight at the top of
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
104 the browser without any leading context).
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
105 \end{funcdesc}
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
106
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
107 \begin{funcdesc}{make_table}{fromlines, tolines
33754
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
108 \optional{, fromdesc}\optional{, todesc}\optional{, context}\optional{,
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
109 numlines}}
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
110 Compares \var{fromlines} and \var{tolines} (lists of strings) and returns
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
111 a string which is a complete HTML table showing line by line differences
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
112 with inter-line and intra-line changes highlighted.
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
113
33754
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
114 The arguments for this method are the same as those for the
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
115 \method{make_file()} method.
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
116 \end{funcdesc}
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
117
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
118 \file{Tools/scripts/diff.py} is a command-line front-end to this class
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
119 and contains a good example of its use.
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
120
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
121 \versionadded{2.4}
33319
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
122 \end{classdesc*}
6d3bdd19beeb Patch #914575: difflib side by side diff support, diff.py s/b/s HTML option.
Martin v. Löwis <martin@v.loewis.de>
parents: 31410
diff changeset
123
33754
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
124 \begin{funcdesc}{context_diff}{a, b\optional{, fromfile}\optional{,
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
125 tofile}\optional{, fromfiledate}\optional{, tofiledate}\optional{,
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
126 n}\optional{, lineterm}}
29398
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
127 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
128 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
129 format.
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
130
29398
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
131 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
132 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
133 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
134 which defaults to three.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
135
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
136 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
137 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
138 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
139 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
140 trailing newlines.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
141
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
142 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
143 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
144
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
145 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
146 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
147 \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
148 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
149 \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
150
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
151 \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
152 function.
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
153
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
154 \versionadded{2.3}
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
155 \end{funcdesc}
29398
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
156
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
157 \begin{funcdesc}{get_close_matches}{word, possibilities\optional{,
33754
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
158 n}\optional{, cutoff}}
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
159 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
160 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
161 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
162 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
163
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164 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
165 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
166
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167 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
168 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
169 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
170
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171 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
172 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
173
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 >>> 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
176 ['apple', 'ape']
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
177 >>> import keyword
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
178 >>> 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
179 ['while']
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180 >>> 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
181 []
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
182 >>> 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
183 ['except']
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
184 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
185 \end{funcdesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
186
33754
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
187 \begin{funcdesc}{ndiff}{a, b\optional{, linejunk}\optional{, charjunk}}
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
188 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
189 \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
190
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
191 Optional keyword parameters \var{linejunk} and \var{charjunk} are
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
192 for filter functions (or \code{None}):
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
193
23300
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
194 \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
195 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
196 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
197 the default was the module-level function
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
198 \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
199 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
200 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
201 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
202 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
203 default.
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
204
23300
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
205 \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
206 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
207 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
208 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
209 idea to include newline in this!).
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
210
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
211 \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
212 function.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
213
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
214 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
215 >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
26556
242ad5c592cc Remove extra ")" in example.
Fred Drake <fdrake@acm.org>
parents: 23300
diff changeset
216 ... 'ore\ntree\nemu\n'.splitlines(1))
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
217 >>> print ''.join(diff),
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
218 - one
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
219 ? ^
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
220 + ore
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
221 ? ^
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
222 - two
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
223 - three
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
224 ? -
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
225 + tree
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
226 + emu
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
227 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
228 \end{funcdesc}
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
229
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
230 \begin{funcdesc}{restore}{sequence, which}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
231 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
232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
233 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
234 \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
235 (parameter \var{which}), stripping off line prefixes.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
236
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
237 Example:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
238
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
239 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
240 >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
241 ... '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
242 >>> 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
243 >>> print ''.join(restore(diff, 1)),
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
244 one
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
245 two
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
246 three
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
247 >>> print ''.join(restore(diff, 2)),
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
248 ore
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
249 tree
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
250 emu
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
251 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
252
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
253 \end{funcdesc}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
254
33754
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
255 \begin{funcdesc}{unified_diff}{a, b\optional{, fromfile}\optional{,
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
256 tofile}\optional{, fromfiledate}\optional{, tofiledate}\optional{,
10b25414628c SF bug 1046690: difflib.HtmlDiff doc errors.
Tim Peters <tim.peters@gmail.com>
parents: 33462
diff changeset
257 n}\optional{, lineterm}}
29398
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
258 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
259 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
260 format.
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
261
29398
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
262 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
263 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
264 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
265 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
266
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
267 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
268 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
269 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
270 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
271 the inputs and outputs have trailing newlines.
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
272
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
273 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
274 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
275
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
276 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
277 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
278 \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
279 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
280 \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
281
e6b0a406dc31 Document context_diff() and unified_diff()
Raymond Hettinger <python@rcn.com>
parents: 26556
diff changeset
282 \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
283 function.
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
284
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
285 \versionadded{2.3}
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
286 \end{funcdesc}
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
287
20677
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
288 \begin{funcdesc}{IS_LINE_JUNK}{line}
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
289 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
290 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
291 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
292 \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
293 \end{funcdesc}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
294
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
295
20677
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
296 \begin{funcdesc}{IS_CHARACTER_JUNK}{ch}
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
297 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
298 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
299 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
300 \function{ndiff()}.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
301 \end{funcdesc}
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
302
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
303
17382
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
304 \begin{seealso}
31410
6e3758ed1ef4 add direct link to the article in DDJ
Fred Drake <fdrake@acm.org>
parents: 31275
diff changeset
305 \seetitle[http://www.ddj.com/documents/s=1103/ddj8807c/]
6e3758ed1ef4 add direct link to the article in DDJ
Fred Drake <fdrake@acm.org>
parents: 31275
diff changeset
306 {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
307 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
308 This was published in
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
309 \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
310 July, 1988.}
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
311 \end{seealso}
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
312
d368552c2b72 Add reference to the DDJ article discussing a similar algorithm.
Fred Drake <fdrake@acm.org>
parents: 16758
diff changeset
313
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
314 \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
315
17780
a1575dbf7d81 Replace "\begin{classdesc}{SomeClass}{\unspecified}" with
Fred Drake <fdrake@acm.org>
parents: 17388
diff changeset
316 The \class{SequenceMatcher} class has this constructor:
a1575dbf7d81 Replace "\begin{classdesc}{SomeClass}{\unspecified}" with
Fred Drake <fdrake@acm.org>
parents: 17388
diff changeset
317
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
318 \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
319 a\optional{, b}}}}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
320 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
321 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
322 true if and only if the element is ``junk'' and should be ignored.
33909
2fa872784eb6 SF bug #1060825: Error in difflib docs
Raymond Hettinger <python@rcn.com>
parents: 33754
diff changeset
323 Passing \code{None} for \var{isjunk} is equivalent to passing
20677
f614825d326a Enforce a bit of markup consistency.
Fred Drake <fdrake@acm.org>
parents: 20038
diff changeset
324 \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
325 example, pass:
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
326
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
327 \begin{verbatim}
16758
8996288a8873 Fix extra backslash in example.
Fred Drake <fdrake@acm.org>
parents: 16703
diff changeset
328 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
329 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
330
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
331 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
332 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
333
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
334 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
335 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
336 sequences must be hashable.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
337 \end{classdesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
338
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
339
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
340 \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
341
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
342 \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
343 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
344 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
345
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
346 \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
347 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
348 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
349 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
350 of the other sequences.
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 \begin{methoddesc}{set_seq1}{a}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
353 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
354 compared is not changed.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
355 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
356
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
357 \begin{methoddesc}{set_seq2}{b}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
358 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
359 compared is not changed.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
360 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
361
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
362 \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
363 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
364 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
365
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
366 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
367 \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
368 \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
369 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
370 \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
371 \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
372 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
373 conditions, the additional conditions
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
374 \code{\var{k} >= \var{k'}},
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
375 \code{\var{i} <= \var{i'}},
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
376 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
377 are also met.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
378 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
379 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
380 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
381 in \var{b}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
382
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
383 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
384 >>> 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
385 >>> 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
386 (0, 4, 5)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
387 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
388
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
389 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
390 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
391 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
392 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
393 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
394 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
395
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
396 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
397 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
398 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
399 \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
400 the second sequence:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
401
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
402 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
403 >>> 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
404 >>> 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
405 (1, 0, 4)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
406 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
407
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
408 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
409 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
410
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
411 \begin{methoddesc}{get_matching_blocks}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
412 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
413 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
414 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
415 \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
416 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
417
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
418 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
419 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
420 % 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
421
38811
4558916b841f SequenceMatcher.get_matching_blocks(): This now guarantees that
Tim Peters <tim.peters@gmail.com>
parents: 34296
diff changeset
422 If
4558916b841f SequenceMatcher.get_matching_blocks(): This now guarantees that
Tim Peters <tim.peters@gmail.com>
parents: 34296
diff changeset
423 \code{(\var{i}, \var{j}, \var{n})} and
4558916b841f SequenceMatcher.get_matching_blocks(): This now guarantees that
Tim Peters <tim.peters@gmail.com>
parents: 34296
diff changeset
424 \code{(\var{i'}, \var{j'}, \var{n'})} are adjacent triples in the list,
4558916b841f SequenceMatcher.get_matching_blocks(): This now guarantees that
Tim Peters <tim.peters@gmail.com>
parents: 34296
diff changeset
425 and the second is not the last triple in the list, then
4558916b841f SequenceMatcher.get_matching_blocks(): This now guarantees that
Tim Peters <tim.peters@gmail.com>
parents: 34296
diff changeset
426 \code{\var{i}+\var{n} != \var{i'}} or
4558916b841f SequenceMatcher.get_matching_blocks(): This now guarantees that
Tim Peters <tim.peters@gmail.com>
parents: 34296
diff changeset
427 \code{\var{j}+\var{n} != \var{j'}}; in other words, adjacent triples
4558916b841f SequenceMatcher.get_matching_blocks(): This now guarantees that
Tim Peters <tim.peters@gmail.com>
parents: 34296
diff changeset
428 always describe non-adjacent equal blocks.
4558916b841f SequenceMatcher.get_matching_blocks(): This now guarantees that
Tim Peters <tim.peters@gmail.com>
parents: 34296
diff changeset
429 \versionchanged[The guarantee that adjacent triples always describe
4558916b841f SequenceMatcher.get_matching_blocks(): This now guarantees that
Tim Peters <tim.peters@gmail.com>
parents: 34296
diff changeset
430 non-adjacent blocks was implemented]{2.5}
4558916b841f SequenceMatcher.get_matching_blocks(): This now guarantees that
Tim Peters <tim.peters@gmail.com>
parents: 34296
diff changeset
431
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
432 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
433 >>> s = SequenceMatcher(None, "abxcd", "abcd")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
434 >>> s.get_matching_blocks()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
435 [(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
436 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
437 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
438
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
439 \begin{methoddesc}{get_opcodes}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
440 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
441 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
442 \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
443 \var{j1} == 0}, and remaining tuples have \var{i1} equal to the
34296
67f2190e1f6d SF Patch #1093896: miscellaneous doc typos
Raymond Hettinger <python@rcn.com>
parents: 33909
diff changeset
444 \var{i2} from the preceding tuple, and, likewise, \var{j1} equal to
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
445 the previous \var{j2}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
446
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
447 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
448
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
449 \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
450 \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
451 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
452 \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
453 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
454 this case.}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
455 \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
456 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
457 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
458 case.}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
459 \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
460 \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
461 equal).}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
462 \end{tableii}
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 For example:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
465
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
466 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
467 >>> a = "qabxcd"
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
468 >>> b = "abycdf"
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
469 >>> s = SequenceMatcher(None, a, b)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
470 >>> 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
471 ... 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
472 ... (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
473 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
474 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
475 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
476 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
477 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
478 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
479 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
480
29404
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
481 \begin{methoddesc}{get_grouped_opcodes}{\optional{n}}
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
482 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
483
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
484 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
485 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
486 intervening ranges which have no changes.
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
487
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
488 The groups are returned in the same format as \method{get_opcodes()}.
33462
5876636ca8c6 HtmlDiff corrections from Dan Gass, + trimmed trailing whitespace.
Tim Peters <tim.peters@gmail.com>
parents: 33448
diff changeset
489 \versionadded{2.3}
29404
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
490 \end{methoddesc}
8c5a6853a02a Add docs for get_grouped_opcodes().
Raymond Hettinger <python@rcn.com>
parents: 29398
diff changeset
491
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
492 \begin{methoddesc}{ratio}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
493 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
494 range [0, 1].
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
495
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
496 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
497 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
498 \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
499 have nothing in common.
16682
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
500
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
501 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
502 \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
503 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
504 \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
505 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
506
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
507 \begin{methoddesc}{quick_ratio}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
508 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
509
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
510 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
511 \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
512 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
513
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
514 \begin{methoddesc}{real_quick_ratio}{}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
515 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
516
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
517 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
518 \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
519 \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
520 \end{methoddesc}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
521
16703
8172906c6dc8 Improve accuracy. In the .tex file, note the new "% BUG:" comments: an
Tim Peters <tim.peters@gmail.com>
parents: 16682
diff changeset
522 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
523 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
524 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
525 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
526
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
527 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
528 >>> s = SequenceMatcher(None, "abcd", "bcde")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
529 >>> s.ratio()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
530 0.75
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
531 >>> s.quick_ratio()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
532 0.75
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
533 >>> s.real_quick_ratio()
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
534 1.0
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
535 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
536
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
537
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
538 \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
539
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
540
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
541 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
542
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
543 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
544 >>> s = SequenceMatcher(lambda x: x == " ",
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
545 ... "private Thread currentThread;",
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
546 ... "private volatile Thread currentThread;")
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
547 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
548
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
549 \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
550 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
551 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
552
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
553 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
554 >>> print round(s.ratio(), 3)
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
555 0.866
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
556 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
557
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
558 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
559 \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
560
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
561 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
562 >>> 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
563 ... 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
564 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
565 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
566 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
567 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
568 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
569
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
570 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
571 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
572 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
573 matched) is \code{0}.
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
574
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
575 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
576 use \method{get_opcodes()}:
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
577
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
578 \begin{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
579 >>> 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
580 ... 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
581 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
582 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
583 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
584 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
585 \end{verbatim}
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
586
3cb00cbe7455 Documentation for the difflib module, converted from the module docstrings.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
587 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
588 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
589 used to do useful work.
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
590
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 \subsection{Differ Objects \label{differ-objects}}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
593
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
594 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
595 \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
596 counter-intuitive, because they synch up anywhere possible, sometimes
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
597 accidental matches 100 pages apart. Restricting synch points to
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
598 contiguous matches preserves some notion of locality, at the
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
599 occasional cost of producing a longer diff.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
600
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
601 The \class{Differ} class has this constructor:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
602
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
603 \begin{classdesc}{Differ}{\optional{linejunk\optional{, charjunk}}}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
604 Optional keyword parameters \var{linejunk} and \var{charjunk} are
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
605 for filter functions (or \code{None}):
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
606
23300
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
607 \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
608 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
609 \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
610
23300
b5f6e9f6e7f4 Mostly in SequenceMatcher.{__chain_b, find_longest_match}:
Tim Peters <tim.peters@gmail.com>
parents: 21106
diff changeset
611 \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
612 (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
613 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
614 considered junk.
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
615 \end{classdesc}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
616
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
617 \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
618 method:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
619
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
620 \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
621 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
622 of lines).
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
623
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
624 Each sequence must contain individual single-line strings ending
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
625 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
626 \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
627 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
628 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
629 \end{methoddesc}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
630
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
631
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
632 \subsection{Differ Example \label{differ-examples}}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
633
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
634 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
635 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
636 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
637 objects):
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
638
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
639 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
640 >>> text1 = ''' 1. Beautiful is better than ugly.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
641 ... 2. Explicit is better than implicit.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
642 ... 3. Simple is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
643 ... 4. Complex is better than complicated.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
644 ... '''.splitlines(1)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
645 >>> len(text1)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
646 4
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
647 >>> text1[0][-1]
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
648 '\n'
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
649 >>> text2 = ''' 1. Beautiful is better than ugly.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
650 ... 3. Simple is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
651 ... 4. Complicated is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
652 ... 5. Flat is better than nested.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
653 ... '''.splitlines(1)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
654 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
655
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
656 Next we instantiate a Differ object:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
657
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
658 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
659 >>> d = Differ()
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
660 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
661
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
662 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
663 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
664 \method{Differ()} constructor for details.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
665
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
666 Finally, we compare the two:
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
667
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
668 \begin{verbatim}
20038
8a6f2ee6eaba Make difflib.ndiff() and difflib.Differ.compare() generators. This
Tim Peters <tim.peters@gmail.com>
parents: 19232
diff changeset
669 >>> result = list(d.compare(text1, text2))
19232
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
670 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
671
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
672 \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
673
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
674 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
675 >>> from pprint import pprint
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
676 >>> pprint(result)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
677 [' 1. Beautiful is better than ugly.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
678 '- 2. Explicit is better than implicit.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
679 '- 3. Simple is better than complex.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
680 '+ 3. Simple is better than complex.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
681 '? ++ \n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
682 '- 4. Complex is better than complicated.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
683 '? ^ ---- ^ \n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
684 '+ 4. Complicated is better than complex.\n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
685 '? ++++ ^ ^ \n',
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
686 '+ 5. Flat is better than nested.\n']
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
687 \end{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
688
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
689 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
690
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
691 \begin{verbatim}
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
692 >>> import sys
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
693 >>> sys.stdout.writelines(result)
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
694 1. Beautiful is better than ugly.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
695 - 2. Explicit is better than implicit.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
696 - 3. Simple is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
697 + 3. Simple is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
698 ? ++
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
699 - 4. Complex is better than complicated.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
700 ? ^ ---- ^
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
701 + 4. Complicated is better than complex.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
702 ? ++++ ^ ^
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
703 + 5. Flat is better than nested.
65885ea76c37 David Goodger <dgoodger@atsautomation.com>:
Fred Drake <fdrake@acm.org>
parents: 17785
diff changeset
704 \end{verbatim}