6.3. difflib —计算增量的帮助者¶

源代码： Lib/difflib.py

此模块提供了用于比较序列的类和函数。它可以用于例如比较文件，并且可以产生各种格式的差异信息，包括HTML和上下文以及统一差异。用于比较目录和文件，另请参阅 filecmp 模块。

class difflib.SequenceMatcher¶

这是用于比较任何类型的序列对的灵活类，只要序列元素是 hashable。基本算法比20世纪80年代由Ratcliff和Obershelp在双曲线名称“格式模式匹配”下公布的算法早，并且是一个有点幸运的。这个想法是找到不包含“垃圾”元素的最长的连续匹配子序列；这些“垃圾”元素在某种意义上是不感兴趣的元素，例如空白行或空格。 （处理垃圾是Ratcliff和Obershelp算法的扩展。）然后，将相同的想法递归地应用于匹配子序列左侧和右侧的序列片段。这不产生最小的编辑序列，但往往产生“看起来正确”的人的匹配。

定时： 基本Ratcliff-Obershelp算法是最坏情况下的三次时间和预期情况下的二次时间。 SequenceMatcher 是最坏情况的二次时间，并且预期情况行为以复杂的方式依赖于序列具有多少元素；最佳情况下时间是线性的。

自动垃圾启发式： SequenceMatcher 支持将某些序列项自动处理为垃圾的启发式算法。启发式计算每个单个项目在序列中出现的次数。如果项目的重复项（在第一个项目之后）占序列的1%以上且序列长度至少为200个项目，则该项目被标记为“流行”，并被视为垃圾以用于序列匹配。在创建 SequenceMatcher 时，可以通过将 autojunk 参数设置为 False 来关闭此启发式。

3.2 新版功能: autojunk 参数。

class difflib.Differ¶

这是一个类，用于比较文本行的序列，并产生人类可读的差异或增量。 Differ使用 SequenceMatcher 来比较线的序列，并且比较类似（近匹配）线内的字符序列。

Differ 增量的每一行以双字母代码开头：

码	含义
'- '	行对序列1唯一
'+ '	行对序列2唯一
'  '	两个序列共有的
'? '	线不存在于任一输入序列中

以“ ? ”开头的行试图引导眼睛到内向差异，并且不存在于任一输入序列中。如果序列包含选项卡字符，这些行可能会混淆。

class difflib.HtmlDiff¶

此类可用于创建一个并排显示的HTML表（或包含表的完整HTML文件），逐行比较文本与行间变化和行内变化亮点。该表可以在完全或上下文差分模式下生成。

这个类的构造函数是：

__init__(tabsize=8, wrapcolumn=None, linejunk=None, charjunk=IS_CHARACTER_JUNK)¶

初始化 HtmlDiff 的实例。

tabsize 是一个可选的关键字参数，用于指定制表符间距，默认为 8。

wrapcolumn 是一个可选的关键字，用于指定行号被折断和换行的列号，缺省为 None，其中行不被换行。

linejunk 和 charjunk 是传递到 ndiff() 的可选关键字参数（由 HtmlDiff 用于生成并行HTML差异）。有关参数默认值和描述，请参阅 ndiff() 文档。

以下方法是公共的：

make_file(fromlines, tolines, fromdesc='', todesc='', context=False, numlines=5, *, charset='utf-8')¶

比较 fromlines 和 tolines （字符串列表），并返回一个字符串，它是一个完整的HTML文件，包含一个表格，显示行间差异，突出显示行间和行内更改。

fromdesc 和 todesc 是可选的关键字参数，用于指定从/到文件列标题字符串（默认为空字符串）。

context 和 numlines 都是可选的关键字参数。当要显示上下文差异时，将 context 设置为 True，否则默认值为 False 以显示完整文件。 numlines 默认为 5。当 context 为 True 时，numlines 控制包围差异亮点的上下文线的数量。当 context 是 False 时，numlines 控制在使用“下一个”超链接时显示在差异突出显示之前的行数（设置为零会导致“下一个”超链接将下一个差异突出显示放在浏览器的顶部，而没有任何前导上下文）。

在 3.5 版更改: 添加了仅 charset 关键字参数。 HTML文档的默认字符集从 'ISO-8859-1' 更改为 'utf-8'。

make_table(fromlines, tolines, fromdesc='', todesc='', context=False, numlines=5)¶

比较 fromlines 和 tolines （字符串列表），并返回一个字符串，它是一个完整的HTML表格，显示逐行间差异，突出显示行间和行内更改。

此方法的参数与 make_file() 方法的参数相同。

Tools/scripts/diff.py 是此类的命令行前端，并包含其使用的一个很好的例子。

difflib.context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')¶

比较 a 和 b （字符串列表）；在上下文差异格式中返回增量（生成增量线的 generator）。

上下文差异是一种紧凑的方式，只显示已更改的行和上下文的几行。更改以前/后样式显示。上下文线的数量由 n 设置，默认为三。

默认情况下，差异控制线（具有 *** 或 --- 的线）使用拖尾换行符创建。这是有帮助的，使得从 io.IOBase.readlines() 创建的输入导致适合与 io.IOBase.writelines() 一起使用的差异，因为输入和输出都具有尾随换行。

对于没有尾随换行符的输入，将 lineterm 参数设置为 ""，以便输出将一致地换行。

上下文差异格式通常具有文件名和修改时间的头。可以使用 fromfile，tofile，fromfiledate 和 tofiledate 的字符串来指定这些中的任何一个或全部。修改时间通常以ISO 8601格式表示。如果未指定，则字符串默认为空格。

>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> sys.stdout.writelines(context_diff(s1, s2, fromfile='before.py', tofile='after.py'))
*** before.py
--- after.py
***************
*** 1,4 ****
! bacon
! eggs
! ham
  guido
--- 1,4 ----
! python
! eggy
! hamster
  guido

有关更详细的示例，请参阅 到difflib的命令行界面。

difflib.get_close_matches(word, possibilities, n=3, cutoff=0.6)¶

返回最好的“足够好”匹配的列表。 word 是需要紧密匹配的序列（通常是字符串），possibilities 是与 word 匹配的序列列表（通常是字符串列表）。

可选参数 n （默认 3）是要返回的最大匹配数； n 必须大于 0。

可选参数 cutoff （默认 0.6）是范围[0，1]中的浮点。忽略至少与 word 类似的得分的可能性。

在列表中返回可能性中最好的（不超过 n）匹配，按照相似性分数排序，最相似。

>>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
['apple', 'ape']
>>> import keyword
>>> get_close_matches('wheel', keyword.kwlist)
['while']
>>> get_close_matches('pineapple', keyword.kwlist)
[]
>>> get_close_matches('accept', keyword.kwlist)
['except']

difflib.ndiff(a, b, linejunk=None, charjunk=IS_CHARACTER_JUNK)¶

比较 a 和 b （字符串列表）；返回 Differ 样式增量（生成增量线的 generator）。

可选的关键字参数 linejunk 和 charjunk 是过滤功能（或 None）：

linejunk：接受单个字符串参数的函数，如果字符串是junk则返回true，否则返回false。默认值为 None。还有一个模块级函数 IS_LINE_JUNK()，它过滤掉没有可见字符的行，但最多只有一个字符（'#'） - 然而，基础 SequenceMatcher 类动态分析哪些行频繁构成噪声，这通常比使用此功能更好。

charjunk：接受字符（长度为1的字符串）的函数，如果字符是垃圾则返回，否则返回false。默认是模块级函数 IS_CHARACTER_JUNK()，它过滤掉空格字符（一个空白或制表符；包含换行符是个不错的主意！）。

Tools/scripts/ndiff.py 是此函数的命令行前端。

>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(keepends=True),
...              'ore\ntree\nemu\n'.splitlines(keepends=True))
>>> print(''.join(diff), end="")
- one
?  ^
+ ore
?  ^
- two
- three
?  -
+ tree
+ emu

difflib.restore(sequence, which)¶

返回生成增量的两个序列之一。

给定由 Differ.compare() 或 ndiff() 产生的 sequence，提取源自文件1或2（参数 which）的行，剥离行前缀。

例：

>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(keepends=True),
...              'ore\ntree\nemu\n'.splitlines(keepends=True))
>>> diff = list(diff) # materialize the generated delta into a list
>>> print(''.join(restore(diff, 1)), end="")
one
two
three
>>> print(''.join(restore(diff, 2)), end="")
ore
tree
emu

difflib.unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')¶

比较 a 和 b （字符串列表）；以统一差异格式返回增量（生成增量线的 generator）。

统一差异是一种紧凑的方式，只显示已更改的行，以及几行上下文。更改以内联样式显示（而不是单独的前/后块）。上下文线的数量由 n 设置，默认为三。

默认情况下，差异控制线（具有 ---，+++ 或 @@ 的线）使用拖尾换行符创建。这是有帮助的，使得从 io.IOBase.readlines() 创建的输入导致适合与 io.IOBase.writelines() 一起使用的差异，因为输入和输出都具有尾随换行。

对于没有尾随换行符的输入，将 lineterm 参数设置为 ""，以便输出将一致地换行。

上下文差异格式通常具有文件名和修改时间的头。可以使用 fromfile，tofile，fromfiledate 和 tofiledate 的字符串来指定这些中的任何一个或全部。修改时间通常以ISO 8601格式表示。如果未指定，则字符串默认为空格。

>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> sys.stdout.writelines(unified_diff(s1, s2, fromfile='before.py', tofile='after.py'))
--- before.py
+++ after.py
@@ -1,4 +1,4 @@
-bacon
-eggs
-ham
+python
+eggy
+hamster
 guido

有关更详细的示例，请参阅 到difflib的命令行界面。

difflib.diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\n')¶

使用 dfunc 比较 a 和 b （字节对象列表）；以 dfunc 返回的格式产生一系列delta线（也是字节）。 dfunc 必须是可调用的，通常是 unified_diff() 或 context_diff()。

允许您比较具有未知或不一致编码的数据。除 n 之外的所有输入必须是字节对象，而不是str。通过无损地将所有输入（除 n）转换为str，并调用 dfunc(a, b, fromfile, tofile, fromfiledate, tofiledate, n, lineterm) 来工作。 dfunc 的输出然后被转换回字节，因此您接收的三角线具有与 a 和 b 相同的未知/不一致的编码。

3.5 新版功能.

difflib.IS_LINE_JUNK(line)¶

对于可忽略的行返回true。如果 line 为空或包含单个 '#'，则线 line 可忽略，否则不可忽略。在旧版本中用作 ndiff() 中参数 linejunk 的默认值。

difflib.IS_CHARACTER_JUNK(ch)¶

对可忽略的字符返回true。如果 ch 是空格或制表符，则字符 ch 可忽略，否则不可忽略。用作 ndiff() 中参数 charjunk 的默认值。

>>> s = SequenceMatcher(None, "abcd", "bcde")
>>> s.ratio()
0.75
>>> s.quick_ratio()
0.75
>>> s.real_quick_ratio()
1.0

>>> s = SequenceMatcher(lambda x: x == " ",
...                     "private Thread currentThread;",
...                     "private volatile Thread currentThread;")

>>> print(round(s.ratio(), 3))
0.866

>>> 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 21 elements
a[29] and b[38] match for 0 elements

>>> 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:29] b[17:38]

>>> text1 = '''  1. Beautiful is better than ugly.
...   2. Explicit is better than implicit.
...   3. Simple is better than complex.
...   4. Complex is better than complicated.
... '''.splitlines(keepends=True)
>>> len(text1)
4
>>> text1[0][-1]
'\n'
>>> text2 = '''  1. Beautiful is better than ugly.
...   3.   Simple is better than complex.
...   4. Complicated is better than complex.
...   5. Flat is better than nested.
... '''.splitlines(keepends=True)

>>> d = Differ()

>>> result = list(d.compare(text1, text2))

>>> from pprint import pprint
>>> pprint(result)
['    1. Beautiful is better than ugly.\n',
 '-   2. Explicit is better than implicit.\n',
 '-   3. Simple is better than complex.\n',
 '+   3.   Simple is better than complex.\n',
 '?     ++\n',
 '-   4. Complex is better than complicated.\n',
 '?            ^                     ---- ^\n',
 '+   4. Complicated is better than complex.\n',
 '?           ++++ ^                      ^\n',
 '+   5. Flat is better than nested.\n']

>>> import sys
>>> sys.stdout.writelines(result)
    1. Beautiful is better than ugly.
-   2. Explicit is better than implicit.
-   3. Simple is better than complex.
+   3.   Simple is better than complex.
?     ++
-   4. Complex is better than complicated.
?            ^                     ---- ^
+   4. Complicated is better than complex.
?           ++++ ^                      ^
+   5. Flat is better than nested.

#!/usr/bin/env python3
""" Command line interface to difflib.py providing diffs in four formats:

* ndiff:    lists every line and highlights interline changes.
* context:  highlights clusters of changes in a before/after format.
* unified:  highlights clusters of changes in an inline format.
* html:     generates side by side comparison with change highlights.

"""

import sys, os, difflib, argparse
from datetime import datetime, timezone

def file_mtime(path):
    t = datetime.fromtimestamp(os.stat(path).st_mtime,
                               timezone.utc)
    return t.astimezone().isoformat()

def main():

    parser = argparse.ArgumentParser()
    parser.add_argument('-c', action='store_true', default=False,
                        help='Produce a context format diff (default)')
    parser.add_argument('-u', action='store_true', default=False,
                        help='Produce a unified format diff')
    parser.add_argument('-m', action='store_true', default=False,
                        help='Produce HTML side by side diff '
                             '(can use -c and -l in conjunction)')
    parser.add_argument('-n', action='store_true', default=False,
                        help='Produce a ndiff format diff')
    parser.add_argument('-l', '--lines', type=int, default=3,
                        help='Set number of context lines (default 3)')
    parser.add_argument('fromfile')
    parser.add_argument('tofile')
    options = parser.parse_args()

    n = options.lines
    fromfile = options.fromfile
    tofile = options.tofile

    fromdate = file_mtime(fromfile)
    todate = file_mtime(tofile)
    with open(fromfile) as ff:
        fromlines = ff.readlines()
    with open(tofile) as tf:
        tolines = tf.readlines()

    if options.u:
        diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile, fromdate, todate, n=n)
    elif options.n:
        diff = difflib.ndiff(fromlines, tolines)
    elif options.m:
        diff = difflib.HtmlDiff().make_file(fromlines,tolines,fromfile,tofile,context=options.c,numlines=n)
    else:
        diff = difflib.context_diff(fromlines, tolines, fromfile, tofile, fromdate, todate, n=n)

    sys.stdout.writelines(diff)

if __name__ == '__main__':
    main()