diff options
Diffstat (limited to 'Doc/library/difflib.rst')
| -rw-r--r-- | Doc/library/difflib.rst | 65 |
1 files changed, 31 insertions, 34 deletions
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index 66f64e5..db4bd3a 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -1,4 +1,3 @@ - :mod:`difflib` --- Helpers for computing deltas =============================================== @@ -8,7 +7,10 @@ .. sectionauthor:: Tim Peters <tim_one@users.sourceforge.net> .. Markup by Fred L. Drake, Jr. <fdrake@acm.org> +.. testsetup:: + import sys + from difflib import * This module provides classes and functions for comparing sequences. It can be used for example, for comparing files, and can produce difference @@ -144,12 +146,10 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module. expressed in the format returned by :func:`time.ctime`. If not specified, the strings default to blanks. - :: - >>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n'] >>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n'] >>> for line in context_diff(s1, s2, fromfile='before.py', tofile='after.py'): - ... sys.stdout.write(line) + ... sys.stdout.write(line) # doctest: +NORMALIZE_WHITESPACE *** before.py --- after.py *************** @@ -180,7 +180,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module. Possibilities that don't score at least that similar to *word* are ignored. The best (no more than *n*) matches among the possibilities are returned in a - list, sorted by similarity score, most similar first. :: + list, sorted by similarity score, most similar first. >>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy']) ['apple', 'ape'] @@ -215,7 +215,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module. function :func:`IS_CHARACTER_JUNK`, which filters out whitespace characters (a blank or tab; note: bad idea to include newline in this!). - :file:`Tools/scripts/ndiff.py` is a command-line front-end to this function. :: + :file:`Tools/scripts/ndiff.py` is a command-line front-end to this function. >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1), ... 'ore\ntree\nemu\n'.splitlines(1)) @@ -239,7 +239,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module. lines originating from file 1 or 2 (parameter *which*), stripping off line prefixes. - Example:: + Example: >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1), ... 'ore\ntree\nemu\n'.splitlines(1)) @@ -279,12 +279,11 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module. expressed in the format returned by :func:`time.ctime`. If not specified, the strings default to blanks. - :: >>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n'] >>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n'] >>> for line in unified_diff(s1, s2, fromfile='before.py', tofile='after.py'): - ... sys.stdout.write(line) + ... sys.stdout.write(line) # doctest: +NORMALIZE_WHITESPACE --- before.py +++ after.py @@ -1,4 +1,4 @@ @@ -379,11 +378,11 @@ use :meth:`set_seq2` to set the commonly used sequence once and call conditions, the additional conditions ``k >= k'``, ``i <= i'``, and if ``i == i'``, ``j <= j'`` are also met. In other words, of all maximal matching blocks, return one that starts earliest in *a*, and of all those maximal matching blocks - that start earliest in *a*, return the one that starts earliest in *b*. :: + that start earliest in *a*, return the one that starts earliest in *b*. >>> s = SequenceMatcher(None, " abcd", "abcd abcd") >>> s.find_longest_match(0, 5, 0, 9) - (0, 4, 5) + Match(a=0, b=4, size=5) If *isjunk* was provided, first the longest matching block is determined as above, but with the additional restriction that no junk element appears in the @@ -394,11 +393,11 @@ use :meth:`set_seq2` to set the commonly used sequence once and call Here's the same example as before, but considering blanks to be junk. That prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the second sequence directly. Instead only the ``'abcd'`` can match, and matches the - leftmost ``'abcd'`` in the second sequence:: + leftmost ``'abcd'`` in the second sequence: >>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd") >>> s.find_longest_match(0, 5, 0, 9) - (1, 0, 4) + Match(a=1, b=0, size=4) If no blocks match, this returns ``(alo, blo, 0)``. @@ -420,11 +419,11 @@ use :meth:`set_seq2` to set the commonly used sequence once and call .. XXX Explain why a dummy is used! - :: + .. doctest:: >>> s = SequenceMatcher(None, "abxcd", "abcd") >>> s.get_matching_blocks() - [(0, 0, 2), (3, 2, 2), (5, 4, 0)] + [Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)] .. method:: SequenceMatcher.get_opcodes() @@ -453,7 +452,7 @@ use :meth:`set_seq2` to set the commonly used sequence once and call | | are equal). | +---------------+---------------------------------------------+ - For example:: + For example: >>> a = "qabxcd" >>> b = "abycdf" @@ -509,7 +508,7 @@ use :meth:`set_seq2` to set the commonly used sequence once and call The three methods that return the ratio of matching to total characters can give different results due to differing levels of approximation, although :meth:`quick_ratio` and :meth:`real_quick_ratio` are always at least as large as -:meth:`ratio`:: +:meth:`ratio`: >>> s = SequenceMatcher(None, "abcd", "bcde") >>> s.ratio() @@ -525,7 +524,7 @@ different results due to differing levels of approximation, although SequenceMatcher Examples ------------------------ -This example compares two strings, considering blanks to be "junk:" :: +This example compares two strings, considering blanks to be "junk:" >>> s = SequenceMatcher(lambda x: x == " ", ... "private Thread currentThread;", @@ -533,19 +532,18 @@ This example compares two strings, considering blanks to be "junk:" :: :meth:`ratio` returns a float in [0, 1], measuring the similarity of the sequences. As a rule of thumb, a :meth:`ratio` value over 0.6 means the -sequences are close matches:: +sequences are close matches: >>> print(round(s.ratio(), 3)) 0.866 If you're only interested in where the sequences match, -:meth:`get_matching_blocks` is handy:: +:meth:`get_matching_blocks` is handy: >>> for block in s.get_matching_blocks(): ... print("a[%d] and b[%d] match for %d elements" % block) a[0] and b[0] match for 8 elements - a[8] and b[17] match for 6 elements - a[14] and b[23] match for 15 elements + a[8] and b[17] match for 21 elements a[29] and b[38] match for 0 elements Note that the last tuple returned by :meth:`get_matching_blocks` is always a @@ -553,14 +551,13 @@ dummy, ``(len(a), len(b), 0)``, and this is the only case in which the last tuple element (number of elements matched) is ``0``. If you want to know how to change the first sequence into the second, use -:meth:`get_opcodes`:: +:meth:`get_opcodes`: >>> for opcode in s.get_opcodes(): ... print("%6s a[%d:%d] b[%d:%d]" % opcode) equal a[0:8] b[0:8] insert a[8:8] b[8:17] - equal a[8:14] b[17:23] - equal a[14:29] b[23:38] + equal a[8:29] b[17:38] See also the function :func:`get_close_matches` in this module, which shows how simple code building on :class:`SequenceMatcher` can be used to do useful work. @@ -613,7 +610,7 @@ Differ Example This example compares two texts. First we set up the texts, sequences of individual single-line strings ending with newlines (such sequences can also be -obtained from the :meth:`readlines` method of file-like objects):: +obtained from the :meth:`readlines` method of file-like objects): >>> text1 = ''' 1. Beautiful is better than ugly. ... 2. Explicit is better than implicit. @@ -630,7 +627,7 @@ obtained from the :meth:`readlines` method of file-like objects):: ... 5. Flat is better than nested. ... '''.splitlines(1) -Next we instantiate a Differ object:: +Next we instantiate a Differ object: >>> d = Differ() @@ -638,11 +635,11 @@ Note that when instantiating a :class:`Differ` object we may pass functions to filter out line and character "junk." See the :meth:`Differ` constructor for details. -Finally, we compare the two:: +Finally, we compare the two: >>> result = list(d.compare(text1, text2)) -``result`` is a list of strings, so let's pretty-print it:: +``result`` is a list of strings, so let's pretty-print it: >>> from pprint import pprint >>> pprint(result) @@ -650,14 +647,14 @@ Finally, we compare the two:: '- 2. Explicit is better than implicit.\n', '- 3. Simple is better than complex.\n', '+ 3. Simple is better than complex.\n', - '? ++ \n', + '? ++\n', '- 4. Complex is better than complicated.\n', - '? ^ ---- ^ \n', + '? ^ ---- ^\n', '+ 4. Complicated is better than complex.\n', - '? ++++ ^ ^ \n', + '? ++++ ^ ^\n', '+ 5. Flat is better than nested.\n'] -As a single multi-line string it looks like this:: +As a single multi-line string it looks like this: >>> import sys >>> sys.stdout.writelines(result) @@ -682,7 +679,7 @@ This example shows how to use difflib to create a ``diff``-like utility. It is also contained in the Python source distribution, as :file:`Tools/scripts/diff.py`. -:: +.. testcode:: """ Command line interface to difflib.py providing diffs in four formats: |