cpython-lru_cache-weakref: Doc/library/difflib.rst annotate

annotate Doc/library/difflib.rst @ 80661:94de77bd0b4b 2.7

Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.

author	Andrew Svetlov <andrew.svetlov@gmail.com>
date	Thu, 29 Nov 2012 19:51:28 +0200
parents	a36666c52115
children	fa7cfbec0d32

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 :mod:`difflib` --- Helpers for computing deltas
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 ===============================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. module:: difflib
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 :synopsis: Helpers for computing differences between objects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 .. moduleauthor:: Tim Peters <tim_one@users.sourceforge.net>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 .. sectionauthor:: Tim Peters <tim_one@users.sourceforge.net>
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43753 diff changeset	8 .. Markup by Fred L. Drake, Jr. <fdrake@acm.org>
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	10 .. testsetup::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	12 import sys
31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	13 from difflib import *
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 .. versionadded:: 2.1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
43598 96af41e50e56 Added a cross-ref to each other. Mark Summerfield <list@qtrac.plus.com> parents: 42604 diff changeset	17 This module provides classes and functions for comparing sequences. It
96af41e50e56 Added a cross-ref to each other. Mark Summerfield <list@qtrac.plus.com> parents: 42604 diff changeset	18 can be used for example, for comparing files, and can produce difference
96af41e50e56 Added a cross-ref to each other. Mark Summerfield <list@qtrac.plus.com> parents: 42604 diff changeset	19 information in various formats, including HTML and context and unified
96af41e50e56 Added a cross-ref to each other. Mark Summerfield <list@qtrac.plus.com> parents: 42604 diff changeset	20 diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 .. class:: SequenceMatcher
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 This is a flexible class for comparing pairs of sequences of any type, so long
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43629 diff changeset	25 as the sequence elements are :term:`hashable`. The basic algorithm predates, and is a
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 little fancier than, an algorithm published in the late 1980's by Ratcliff and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 Obershelp under the hyperbolic name "gestalt pattern matching." The idea is to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 find the longest contiguous matching subsequence that contains no "junk"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 elements (the Ratcliff and Obershelp algorithm doesn't address junk). The same
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 idea is then applied recursively to the pieces of the sequences to the left and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 to the right of the matching subsequence. This does not yield minimal edit
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 sequences, but does tend to yield matches that "look right" to people.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 Timing: The basic Ratcliff-Obershelp algorithm is cubic time in the worst
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 case and quadratic time in the expected case. :class:`SequenceMatcher` is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 quadratic time for the worst case and has expected-case behavior dependent in a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 complicated way on how many elements the sequences have in common; best case
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 time is linear.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39
66156 1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	40 Automatic junk heuristic: :class:`SequenceMatcher` supports a heuristic that
1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	41 automatically treats certain sequence items as junk. The heuristic counts how many
1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	42 times each individual item appears in the sequence. If an item's duplicates (after
1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	43 the first one) account for more than 1% of the sequence and the sequence is at least
1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	44 200 items long, this item is marked as "popular" and is treated as junk for
1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	45 the purpose of sequence matching. This heuristic can be turned off by setting
1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	46 the ``autojunk`` argument to ``False`` when creating the :class:`SequenceMatcher`.
1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	47
66174 f6e813b48af3 #2986 Correct and duplicate version-added message Terry Reedy <tjreedy@udel.edu> parents: 66156 diff changeset	48 .. versionadded:: 2.7.1
66156 1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	49 The autojunk parameter.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 .. class:: Differ
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 This is a class for comparing sequences of lines of text, and producing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 human-readable differences or deltas. Differ uses :class:`SequenceMatcher`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 both to compare sequences of lines, and to compare sequences of characters
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 within similar (near-matching) lines.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 Each line of a :class:`Differ` delta begins with a two-letter code:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 +----------+-------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 \| Code \| Meaning \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 +==========+===========================================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 \| ``'- '`` \| line unique to sequence 1 \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 +----------+-------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 \| ``'+ '`` \| line unique to sequence 2 \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 +----------+-------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 \| ``' '`` \| line common to both sequences \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 +----------+-------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 \| ``'? '`` \| line not present in either input sequence \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 +----------+-------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 Lines beginning with '``?``' attempt to guide the eye to intraline differences,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 and were not present in either input sequence. These lines can be confusing if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 the sequences contain tab characters.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 .. class:: HtmlDiff
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 This class can be used to create an HTML table (or a complete HTML file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 containing the table) showing a side by side, line by line comparison of text
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 with inter-line and intra-line change highlights. The table can be generated in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 either full or contextual difference mode.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 The constructor for this class is:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86
77102 a36666c52115 #14804: Remove [] around optional arguments with default values Hynek Schlawack <hs@ox.cx> parents: 68256 diff changeset	87 .. function:: __init__(tabsize=8, wrapcolumn=None, linejunk=None, charjunk=IS_CHARACTER_JUNK)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 Initializes instance of :class:`HtmlDiff`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 tabsize is an optional keyword argument to specify tab stop spacing and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 defaults to ``8``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 wrapcolumn is an optional keyword to specify column number where lines are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 broken and wrapped, defaults to ``None`` where lines are not wrapped.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 linejunk and charjunk are optional keyword arguments passed into ``ndiff()``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 (used by :class:`HtmlDiff` to generate the side by side HTML differences). See
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 ``ndiff()`` documentation for argument default values and descriptions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 The following methods are public:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 .. function:: make_file(fromlines, tolines [, fromdesc][, todesc][, context][, numlines])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 Compares fromlines and tolines (lists of strings) and returns a string which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 is a complete HTML file containing a table showing line by line differences with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 inter-line and intra-line changes highlighted.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 fromdesc and todesc are optional keyword arguments to specify from/to file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 column header strings (both default to an empty string).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 context and numlines are both optional keyword arguments. Set context to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 ``True`` when contextual differences are to be shown, else the default is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 ``False`` to show the full files. numlines defaults to ``5``. When context
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 is ``True`` numlines controls the number of context lines which surround the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 difference highlights. When context is ``False`` numlines controls the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 number of lines which are shown before a difference highlight when using the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119 "next" hyperlinks (setting to zero would cause the "next" hyperlinks to place
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 the next difference highlight at the top of the browser without any leading
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 context).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 .. function:: make_table(fromlines, tolines [, fromdesc][, todesc][, context][, numlines])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 Compares fromlines and tolines (lists of strings) and returns a string which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 is a complete HTML table showing line by line differences with inter-line and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 intra-line changes highlighted.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 The arguments for this method are the same as those for the :meth:`make_file`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 method.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 :file:`Tools/scripts/diff.py` is a command-line front-end to this class and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 contains a good example of its use.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 .. versionadded:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 .. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140
43629 4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43598 diff changeset	141 Compare a and b (lists of strings); return a delta (a :term:`generator`
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43598 diff changeset	142 generating the delta lines) in context diff format.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 Context diffs are a compact way of showing just the lines that have changed plus
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 a few lines of context. The changes are shown in a before/after style. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 number of context lines is set by n which defaults to three.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 By default, the diff control lines (those with ``***`` or ``---``) are created
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 with a trailing newline. This is helpful so that inputs created from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 :func:`file.readlines` result in diffs that are suitable for use with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 :func:`file.writelines` since both the inputs and outputs have trailing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 newlines.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 For inputs that do not have trailing newlines, set the lineterm argument to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 ``""`` so that the output will be uniformly newline free.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 The context diff format normally has a header for filenames and modification
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 times. Any or all of these may be specified using strings for fromfile,
60552 713f1f6bf339 Issue #7585: use tab between components in unified and context diff headers. R. David Murray <rdmurray@bitdance.com> parents: 53552 diff changeset	159 tofile, fromfiledate, and tofiledate. The modification times are normally
713f1f6bf339 Issue #7585: use tab between components in unified and context diff headers. R. David Murray <rdmurray@bitdance.com> parents: 53552 diff changeset	160 expressed in the ISO 8601 format. If not specified, the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 strings default to blanks.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162
45454 d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	163 >>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	164 >>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	165 >>> for line in context_diff(s1, s2, fromfile='before.py', tofile='after.py'):
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	166 ... sys.stdout.write(line) # doctest: +NORMALIZE_WHITESPACE
45454 d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	167 *** before.py
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	168 --- after.py
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	169 ***************
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	170 * 1,4 **
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	171 ! bacon
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	172 ! eggs
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	173 ! ham
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	174 guido
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	175 --- 1,4 ----
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	176 ! python
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	177 ! eggy
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	178 ! hamster
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	179 guido
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	180
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	181 See :ref:`difflib-interface` for a more detailed example.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 .. function:: get_close_matches(word, possibilities[, n][, cutoff])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 Return a list of the best "good enough" matches. word is a sequence for which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 close matches are desired (typically a string), and possibilities is a list of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 sequences against which to match word (typically a list of strings).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 Optional argument n (default ``3``) is the maximum number of close matches to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 return; n must be greater than ``0``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 Optional argument cutoff (default ``0.6``) is a float in the range [0, 1].
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 Possibilities that don't score at least that similar to word are ignored.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 The best (no more than n) matches among the possibilities are returned in a
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	199 list, sorted by similarity score, most similar first.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 >>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 ['apple', 'ape']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 >>> import keyword
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 >>> get_close_matches('wheel', keyword.kwlist)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 ['while']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 >>> get_close_matches('apple', keyword.kwlist)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 []
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 >>> get_close_matches('accept', keyword.kwlist)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 ['except']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 .. function:: ndiff(a, b[, linejunk][, charjunk])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213
43629 4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43598 diff changeset	214 Compare a and b (lists of strings); return a :class:`Differ`\ -style
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43598 diff changeset	215 delta (a :term:`generator` generating the delta lines).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 Optional keyword parameters linejunk and charjunk are for filter functions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 (or ``None``):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 linejunk: A function that accepts a single string argument, and returns true
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 if the string is junk, or false if not. The default is (``None``), starting with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 Python 2.3. Before then, the default was the module-level function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 :func:`IS_LINE_JUNK`, which filters out lines without visible characters, except
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 for at most one pound character (``'#'``). As of Python 2.3, the underlying
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 :class:`SequenceMatcher` class does a dynamic analysis of which lines are so
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 frequent as to constitute noise, and this usually works better than the pre-2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 default.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 charjunk: A function that accepts a character (a string of length 1), and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 returns if the character is junk, or false if not. The default is module-level
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 function :func:`IS_CHARACTER_JUNK`, which filters out whitespace characters (a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 blank or tab; note: bad idea to include newline in this!).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	234 :file:`Tools/scripts/ndiff.py` is a command-line front-end to this function.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 ... 'ore\ntree\nemu\n'.splitlines(1))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 >>> print ''.join(diff),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 - one
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 ? ^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 + ore
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 ? ^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 - two
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 - three
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 ? -
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 + tree
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 + emu
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 .. function:: restore(sequence, which)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252 Return one of the two sequences that generated a delta.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 Given a sequence produced by :meth:`Differ.compare` or :func:`ndiff`, extract
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 lines originating from file 1 or 2 (parameter which), stripping off line
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 prefixes.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	258 Example:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 ... 'ore\ntree\nemu\n'.splitlines(1))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 >>> diff = list(diff) # materialize the generated delta into a list
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 >>> print ''.join(restore(diff, 1)),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 one
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 two
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 three
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 >>> print ''.join(restore(diff, 2)),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 ore
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 tree
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 emu
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 .. function:: unified_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274
43629 4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43598 diff changeset	275 Compare a and b (lists of strings); return a delta (a :term:`generator`
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43598 diff changeset	276 generating the delta lines) in unified diff format.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 Unified diffs are a compact way of showing just the lines that have changed plus
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 a few lines of context. The changes are shown in a inline style (instead of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 separate before/after blocks). The number of context lines is set by n which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 defaults to three.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 By default, the diff control lines (those with ``---``, ``+++``, or ``@@``) are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 created with a trailing newline. This is helpful so that inputs created from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 :func:`file.readlines` result in diffs that are suitable for use with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 :func:`file.writelines` since both the inputs and outputs have trailing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 newlines.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 For inputs that do not have trailing newlines, set the lineterm argument to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 ``""`` so that the output will be uniformly newline free.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 The context diff format normally has a header for filenames and modification
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 times. Any or all of these may be specified using strings for fromfile,
60552 713f1f6bf339 Issue #7585: use tab between components in unified and context diff headers. R. David Murray <rdmurray@bitdance.com> parents: 53552 diff changeset	294 tofile, fromfiledate, and tofiledate. The modification times are normally
713f1f6bf339 Issue #7585: use tab between components in unified and context diff headers. R. David Murray <rdmurray@bitdance.com> parents: 53552 diff changeset	295 expressed in the ISO 8601 format. If not specified, the
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 strings default to blanks.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297
45454 d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	298 >>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	299 >>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	300 >>> for line in unified_diff(s1, s2, fromfile='before.py', tofile='after.py'):
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	301 ... sys.stdout.write(line) # doctest: +NORMALIZE_WHITESPACE
45454 d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	302 --- before.py
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	303 +++ after.py
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	304 @@ -1,4 +1,4 @@
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	305 -bacon
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	306 -eggs
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	307 -ham
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	308 +python
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	309 +eggy
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	310 +hamster
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	311 guido
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	312
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	313 See :ref:`difflib-interface` for a more detailed example.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 .. function:: IS_LINE_JUNK(line)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 Return true for ignorable lines. The line line is ignorable if line is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 blank or contains a single ``'#'``, otherwise it is not ignorable. Used as a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 default for parameter linejunk in :func:`ndiff` before Python 2.3.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 .. function:: IS_CHARACTER_JUNK(ch)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 Return true for ignorable characters. The character ch is ignorable if ch
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 is a space or tab, otherwise it is not ignorable. Used as a default for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 parameter charjunk in :func:`ndiff`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 `Pattern Matching: The Gestalt Approach <http://www.ddj.com/184407970?pgno=5>`_
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 Discussion of a similar algorithm by John W. Ratcliff and D. E. Metzener. This
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 was published in `Dr. Dobb's Journal <http://www.ddj.com/>`_ in July, 1988.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 .. _sequence-matcher:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 SequenceMatcher Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 The :class:`SequenceMatcher` class has this constructor:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
77102 a36666c52115 #14804: Remove [] around optional arguments with default values Hynek Schlawack <hs@ox.cx> parents: 68256 diff changeset	347 .. class:: SequenceMatcher(isjunk=None, a='', b='', autojunk=True)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 Optional argument isjunk must be ``None`` (the default) or a one-argument
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 function that takes a sequence element and returns true if and only if the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 element is "junk" and should be ignored. Passing ``None`` for isjunk is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 equivalent to passing ``lambda x: 0``; in other words, no elements are ignored.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 For example, pass::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 lambda x: x in " \t"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 if you're comparing lines as sequences of characters, and don't want to synch up
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 on blanks or hard tabs.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 The optional arguments a and b are sequences to be compared; both default to
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43629 diff changeset	361 empty strings. The elements of both sequences must be :term:`hashable`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
66156 1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	363 The optional argument autojunk can be used to disable the automatic junk
1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	364 heuristic.
1a65290e6d03 #2986 Add autojunk parameter to SequenceMatcher to optionally disable 'popular == junk' heuristic. Terry Reedy <tjreedy@udel.edu> parents: 60552 diff changeset	365
66174 f6e813b48af3 #2986 Correct and duplicate version-added message Terry Reedy <tjreedy@udel.edu> parents: 66156 diff changeset	366 .. versionadded:: 2.7.1
f6e813b48af3 #2986 Correct and duplicate version-added message Terry Reedy <tjreedy@udel.edu> parents: 66156 diff changeset	367 The autojunk parameter.
f6e813b48af3 #2986 Correct and duplicate version-added message Terry Reedy <tjreedy@udel.edu> parents: 66156 diff changeset	368
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	369 :class:`SequenceMatcher` objects have the following methods:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	371 .. method:: set_seqs(a, b)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	373 Set the two sequences to be compared.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	375 :class:`SequenceMatcher` computes and caches detailed information about the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	376 second sequence, so if you want to compare one sequence against many
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	377 sequences, use :meth:`set_seq2` to set the commonly used sequence once and
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	378 call :meth:`set_seq1` repeatedly, once for each of the other sequences.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	381 .. method:: set_seq1(a)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	383 Set the first sequence to be compared. The second sequence to be compared
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	384 is not changed.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	387 .. method:: set_seq2(b)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	389 Set the second sequence to be compared. The first sequence to be compared
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	390 is not changed.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	393 .. method:: find_longest_match(alo, ahi, blo, bhi)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	395 Find longest matching block in ``a[alo:ahi]`` and ``b[blo:bhi]``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	397 If isjunk was omitted or ``None``, :meth:`find_longest_match` returns
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	398 ``(i, j, k)`` such that ``a[i:i+k]`` is equal to ``b[j:j+k]``, where ``alo
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	399 <= i <= i+k <= ahi`` and ``blo <= j <= j+k <= bhi``. For all ``(i', j',
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	400 k')`` meeting those conditions, the additional conditions ``k >= k'``, ``i
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	401 <= i'``, and if ``i == i'``, ``j <= j'`` are also met. In other words, of
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	402 all maximal matching blocks, return one that starts earliest in a, and
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	403 of all those maximal matching blocks that start earliest in a, return
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	404 the one that starts earliest in b.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	406 >>> s = SequenceMatcher(None, " abcd", "abcd abcd")
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	407 >>> s.find_longest_match(0, 5, 0, 9)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	408 Match(a=0, b=4, size=5)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	410 If isjunk was provided, first the longest matching block is determined
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	411 as above, but with the additional restriction that no junk element appears
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	412 in the block. Then that block is extended as far as possible by matching
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	413 (only) junk elements on both sides. So the resulting block never matches
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	414 on junk except as identical junk happens to be adjacent to an interesting
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	415 match.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	417 Here's the same example as before, but considering blanks to be junk. That
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	418 prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	419 second sequence directly. Instead only the ``'abcd'`` can match, and
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	420 matches the leftmost ``'abcd'`` in the second sequence:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	422 >>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	423 >>> s.find_longest_match(0, 5, 0, 9)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	424 Match(a=1, b=0, size=4)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	426 If no blocks match, this returns ``(alo, blo, 0)``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	428 .. versionchanged:: 2.6
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	429 This method returns a :term:`named tuple` ``Match(a, b, size)``.
44638 62f6d780a11d Documentation for r5990[3567]. Georg Brandl <georg@python.org> parents: 44383 diff changeset	430
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	432 .. method:: get_matching_blocks()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	434 Return list of triples describing matching subsequences. Each triple is of
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	435 the form ``(i, j, n)``, and means that ``a[i:i+n] == b[j:j+n]``. The
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	436 triples are monotonically increasing in i and j.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	438 The last triple is a dummy, and has the value ``(len(a), len(b), 0)``. It
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	439 is the only triple with ``n == 0``. If ``(i, j, n)`` and ``(i', j', n')``
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	440 are adjacent triples in the list, and the second is not the last triple in
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	441 the list, then ``i+n != i'`` or ``j+n != j'``; in other words, adjacent
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	442 triples always describe non-adjacent equal blocks.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	444 .. XXX Explain why a dummy is used!
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 46555 diff changeset	446 .. versionchanged:: 2.5
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	447 The guarantee that adjacent triples always describe non-adjacent blocks
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	448 was implemented.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	450 .. doctest::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	452 >>> s = SequenceMatcher(None, "abxcd", "abcd")
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	453 >>> s.get_matching_blocks()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	454 [Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	457 .. method:: get_opcodes()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	459 Return list of 5-tuples describing how to turn a into b. Each tuple is
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	460 of the form ``(tag, i1, i2, j1, j2)``. The first tuple has ``i1 == j1 ==
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	461 0``, and remaining tuples have i1 equal to the i2 from the preceding
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	462 tuple, and, likewise, j1 equal to the previous j2.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	464 The tag values are strings, with these meanings:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	466 +---------------+---------------------------------------------+
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	467 \| Value \| Meaning \|
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	468 +===============+=============================================+
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	469 \| ``'replace'`` \| ``a[i1:i2]`` should be replaced by \|
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	470 \| \| ``b[j1:j2]``. \|
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	471 +---------------+---------------------------------------------+
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	472 \| ``'delete'`` \| ``a[i1:i2]`` should be deleted. Note that \|
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	473 \| \| ``j1 == j2`` in this case. \|
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	474 +---------------+---------------------------------------------+
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	475 \| ``'insert'`` \| ``b[j1:j2]`` should be inserted at \|
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	476 \| \| ``a[i1:i1]``. Note that ``i1 == i2`` in \|
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	477 \| \| this case. \|
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	478 +---------------+---------------------------------------------+
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	479 \| ``'equal'`` \| ``a[i1:i2] == b[j1:j2]`` (the sub-sequences \|
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	480 \| \| are equal). \|
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	481 +---------------+---------------------------------------------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	483 For example:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	485 >>> a = "qabxcd"
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	486 >>> b = "abycdf"
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	487 >>> s = SequenceMatcher(None, a, b)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	488 >>> for tag, i1, i2, j1, j2 in s.get_opcodes():
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	489 ... print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	490 ... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	491 delete a[0:1] (q) b[0:0] ()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	492 equal a[1:3] (ab) b[0:2] (ab)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	493 replace a[3:4] (x) b[2:3] (y)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	494 equal a[4:6] (cd) b[3:5] (cd)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	495 insert a[6:6] () b[5:6] (f)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	498 .. method:: get_grouped_opcodes([n])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	500 Return a :term:`generator` of groups with up to n lines of context.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	502 Starting with the groups returned by :meth:`get_opcodes`, this method
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	503 splits out smaller change clusters and eliminates intervening ranges which
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	504 have no changes.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	506 The groups are returned in the same format as :meth:`get_opcodes`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	508 .. versionadded:: 2.3
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	511 .. method:: ratio()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	513 Return a measure of the sequences' similarity as a float in the range [0,
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	514 1].
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	516 Where T is the total number of elements in both sequences, and M is the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	517 number of matches, this is 2.0\*M / T. Note that this is ``1.0`` if the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	518 sequences are identical, and ``0.0`` if they have nothing in common.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	520 This is expensive to compute if :meth:`get_matching_blocks` or
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	521 :meth:`get_opcodes` hasn't already been called, in which case you may want
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	522 to try :meth:`quick_ratio` or :meth:`real_quick_ratio` first to get an
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	523 upper bound.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	526 .. method:: quick_ratio()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	528 Return an upper bound on :meth:`ratio` relatively quickly.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	531 .. method:: real_quick_ratio()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	533 Return an upper bound on :meth:`ratio` very quickly.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 The three methods that return the ratio of matching to total characters can give
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 different results due to differing levels of approximation, although
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 :meth:`quick_ratio` and :meth:`real_quick_ratio` are always at least as large as
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	539 :meth:`ratio`:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541 >>> s = SequenceMatcher(None, "abcd", "bcde")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 >>> s.ratio()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 0.75
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 >>> s.quick_ratio()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 0.75
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 >>> s.real_quick_ratio()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 1.0
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 .. _sequencematcher-examples:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552 SequenceMatcher Examples
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	555 This example compares two strings, considering blanks to be "junk:"
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557 >>> s = SequenceMatcher(lambda x: x == " ",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558 ... "private Thread currentThread;",
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559 ... "private volatile Thread currentThread;")
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561 :meth:`ratio` returns a float in [0, 1], measuring the similarity of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562 sequences. As a rule of thumb, a :meth:`ratio` value over 0.6 means the
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	563 sequences are close matches:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 >>> print round(s.ratio(), 3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566 0.866
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 If you're only interested in where the sequences match,
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	569 :meth:`get_matching_blocks` is handy:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571 >>> for block in s.get_matching_blocks():
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 ... print "a[%d] and b[%d] match for %d elements" % block
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 a[0] and b[0] match for 8 elements
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	574 a[8] and b[17] match for 21 elements
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 a[29] and b[38] match for 0 elements
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 Note that the last tuple returned by :meth:`get_matching_blocks` is always a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 dummy, ``(len(a), len(b), 0)``, and this is the only case in which the last
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579 tuple element (number of elements matched) is ``0``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 If you want to know how to change the first sequence into the second, use
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	582 :meth:`get_opcodes`:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584 >>> for opcode in s.get_opcodes():
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 ... print "%6s a[%d:%d] b[%d:%d]" % opcode
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 equal a[0:8] b[0:8]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 insert a[8:8] b[8:17]
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	588 equal a[8:29] b[17:38]
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589
56810 68f7288d155c Merged revisions 71094,71102-71103,71106,71486,71962,72053,72221,72418-72419 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	590 .. seealso::
68f7288d155c Merged revisions 71094,71102-71103,71106,71486,71962,72053,72221,72418-72419 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	591
68f7288d155c Merged revisions 71094,71102-71103,71106,71486,71962,72053,72221,72418-72419 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	592 * The :func:`get_close_matches` function in this module which shows how
68f7288d155c Merged revisions 71094,71102-71103,71106,71486,71962,72053,72221,72418-72419 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	593 simple code building on :class:`SequenceMatcher` can be used to do useful
68f7288d155c Merged revisions 71094,71102-71103,71106,71486,71962,72053,72221,72418-72419 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	594 work.
68f7288d155c Merged revisions 71094,71102-71103,71106,71486,71962,72053,72221,72418-72419 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	595
68f7288d155c Merged revisions 71094,71102-71103,71106,71486,71962,72053,72221,72418-72419 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	596 * `Simple version control recipe
68f7288d155c Merged revisions 71094,71102-71103,71106,71486,71962,72053,72221,72418-72419 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	597 <http://code.activestate.com/recipes/576729/>`_ for a small application
68f7288d155c Merged revisions 71094,71102-71103,71106,71486,71962,72053,72221,72418-72419 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	598 built with :class:`SequenceMatcher`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601 .. _differ-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	602
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603 Differ Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604 --------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	605
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	606 Note that :class:`Differ`\ -generated deltas make no claim to be minimal
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607 diffs. To the contrary, minimal diffs are often counter-intuitive, because they
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608 synch up anywhere possible, sometimes accidental matches 100 pages apart.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609 Restricting synch points to contiguous matches preserves some notion of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610 locality, at the occasional cost of producing a longer diff.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612 The :class:`Differ` class has this constructor:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615 .. class:: Differ([linejunk[, charjunk]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	616
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617 Optional keyword parameters linejunk and charjunk are for filter functions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618 (or ``None``):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620 linejunk: A function that accepts a single string argument, and returns true
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621 if the string is junk. The default is ``None``, meaning that no line is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622 considered junk.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	624 charjunk: A function that accepts a single character argument (a string of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625 length 1), and returns true if the character is junk. The default is ``None``,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626 meaning that no character is considered junk.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	628 :class:`Differ` objects are used (deltas generated) via a single method:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	631 .. method:: Differ.compare(a, b)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	633 Compare two sequences of lines, and generate the delta (a sequence of lines).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	635 Each sequence must contain individual single-line strings ending with newlines.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	636 Such sequences can be obtained from the :meth:`readlines` method of file-like
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	637 objects. The delta generated also consists of newline-terminated strings, ready
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 46014 diff changeset	638 to be printed as-is via the :meth:`writelines` method of a file-like object.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	641 .. _differ-examples:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 Differ Example
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644 --------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646 This example compares two texts. First we set up the texts, sequences of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647 individual single-line strings ending with newlines (such sequences can also be
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	648 obtained from the :meth:`readlines` method of file-like objects):
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 >>> text1 = ''' 1. Beautiful is better than ugly.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651 ... 2. Explicit is better than implicit.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652 ... 3. Simple is better than complex.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 ... 4. Complex is better than complicated.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654 ... '''.splitlines(1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 >>> len(text1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656 4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 >>> text1[0][-1]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658 '\n'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659 >>> text2 = ''' 1. Beautiful is better than ugly.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660 ... 3. Simple is better than complex.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661 ... 4. Complicated is better than complex.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662 ... 5. Flat is better than nested.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 ... '''.splitlines(1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	665 Next we instantiate a Differ object:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667 >>> d = Differ()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 Note that when instantiating a :class:`Differ` object we may pass functions to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670 filter out line and character "junk." See the :meth:`Differ` constructor for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 details.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	673 Finally, we compare the two:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 >>> result = list(d.compare(text1, text2))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	677 ``result`` is a list of strings, so let's pretty-print it:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 >>> from pprint import pprint
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 >>> pprint(result)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681 [' 1. Beautiful is better than ugly.\n',
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	682 '- 2. Explicit is better than implicit.\n',
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	683 '- 3. Simple is better than complex.\n',
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684 '+ 3. Simple is better than complex.\n',
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	685 '? ++\n',
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686 '- 4. Complex is better than complicated.\n',
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	687 '? ^ ---- ^\n',
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688 '+ 4. Complicated is better than complex.\n',
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	689 '? ++++ ^ ^\n',
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690 '+ 5. Flat is better than nested.\n']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	692 As a single multi-line string it looks like this:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694 >>> import sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695 >>> sys.stdout.writelines(result)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696 1. Beautiful is better than ugly.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697 - 2. Explicit is better than implicit.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698 - 3. Simple is better than complex.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699 + 3. Simple is better than complex.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700 ? ++
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701 - 4. Complex is better than complicated.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 ? ^ ---- ^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703 + 4. Complicated is better than complex.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 ? ++++ ^ ^
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 + 5. Flat is better than nested.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706
45454 d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	707
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	708 .. _difflib-interface:
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	709
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	710 A command-line interface to difflib
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	711 -----------------------------------
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	712
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	713 This example shows how to use difflib to create a ``diff``-like utility.
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	714 It is also contained in the Python source distribution, as
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	715 :file:`Tools/scripts/diff.py`.
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	716
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45454 diff changeset	717 .. testcode::
45454 d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	718
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	719 """ Command line interface to difflib.py providing diffs in four formats:
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	720
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	721 * ndiff: lists every line and highlights interline changes.
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	722 * context: highlights clusters of changes in a before/after format.
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	723 * unified: highlights clusters of changes in an inline format.
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	724 * html: generates side by side comparison with change highlights.
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	725
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	726 """
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	727
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	728 import sys, os, time, difflib, optparse
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	729
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	730 def main():
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	731 # Configure the option parser
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	732 usage = "usage: %prog [options] fromfile tofile"
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	733 parser = optparse.OptionParser(usage)
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	734 parser.add_option("-c", action="store_true", default=False,
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	735 help='Produce a context format diff (default)')
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	736 parser.add_option("-u", action="store_true", default=False,
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	737 help='Produce a unified format diff')
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	738 hlp = 'Produce HTML side by side diff (can use -c and -l in conjunction)'
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	739 parser.add_option("-m", action="store_true", default=False, help=hlp)
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	740 parser.add_option("-n", action="store_true", default=False,
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	741 help='Produce a ndiff format diff')
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	742 parser.add_option("-l", "--lines", type="int", default=3,
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	743 help='Set number of context lines (default 3)')
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	744 (options, args) = parser.parse_args()
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	745
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	746 if len(args) == 0:
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	747 parser.print_help()
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	748 sys.exit(1)
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	749 if len(args) != 2:
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	750 parser.error("need to specify both a fromfile and tofile")
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	751
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	752 n = options.lines
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	753 fromfile, tofile = args # as specified in the usage string
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	754
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	755 # we're passing these as arguments to the diff function
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	756 fromdate = time.ctime(os.stat(fromfile).st_mtime)
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	757 todate = time.ctime(os.stat(tofile).st_mtime)
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	758 fromlines = open(fromfile, 'U').readlines()
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	759 tolines = open(tofile, 'U').readlines()
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	760
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	761 if options.u:
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	762 diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile,
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	763 fromdate, todate, n=n)
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	764 elif options.n:
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	765 diff = difflib.ndiff(fromlines, tolines)
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	766 elif options.m:
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	767 diff = difflib.HtmlDiff().make_file(fromlines, tolines, fromfile,
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	768 tofile, context=options.c,
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	769 numlines=n)
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	770 else:
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	771 diff = difflib.context_diff(fromlines, tolines, fromfile, tofile,
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	772 fromdate, todate, n=n)
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	773
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	774 # we're using writelines because diff is a generator
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	775 sys.stdout.writelines(diff)
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	776
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	777 if __name__ == '__main__':
d7e232e9f1a1 More difflib examples. Written for GHOP by Josip Dzolonga. Georg Brandl <georg@python.org> parents: 44638 diff changeset	778 main()

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/difflib.rst @ 80661:94de77bd0b4b 2.7