difflib --- 計算差異的輔助工具?

源代碼: Lib/difflib.py

此模塊提供用于比較序列的類和函數(shù)。 例如，它可被用于比較文件，并可產(chǎn)生多種格式的不同文件差異信息，包括 HTML 和上下文以及統(tǒng)一的 diff 數(shù)據(jù)。 有關(guān)比較目錄和文件，另請參閱 filecmp 模塊。

class difflib.SequenceMatcher

這是一個靈活的類，可用于比較任何類型的序列對，只要序列元素為 hashable 對象。 其基本算法要早于由 Ratcliff 和 Obershelp 于 1980 年代末期發(fā)表并以“格式塔模式匹配”的夸張名稱命名的算法，并且更加有趣一些。 其思路是找到不包含“垃圾”元素的最長連續(xù)匹配子序列；所謂“垃圾”元素是指其在某種意義上沒有價值，例如空白行或空白符。 （處理垃圾元素是對 Ratcliff 和 Obershelp 算法的一個擴展。） 然后同樣的思路將遞歸地應用于匹配序列的左右序列片段。 這并不能產(chǎn)生最小編輯序列，但確實能產(chǎn)生在人們看來“正確”的匹配。

耗時: 基本 Ratcliff-Obershelp 算法在最壞情況下為立方時間而在一般情況下為平方時間。 SequenceMatcher 在最壞情況下為平方時間而在一般情況下的行為受到序列中有多少相同元素這一因素的微妙影響；在最佳情況下則為線性時間。

自動垃圾啟發(fā)式計算: SequenceMatcher 支持使用啟發(fā)式計算來自動將特定序列項視為垃圾。 這種啟發(fā)式計算會統(tǒng)計每個單獨項在序列中出現(xiàn)的次數(shù)。 如果某一項（在第一項之后）的重復次數(shù)超過序列長度的 1% 并且序列長度至少有 200 項，該項會被標記為“熱門”并被視為序列匹配中的垃圾。 這種啟發(fā)式計算可以通過在創(chuàng)建 SequenceMatcher 時將 autojunk 參數(shù)設為 False 來關(guān)閉。

3.2 新版功能: autojunk 形參。

class difflib.Differ?

這個類的作用是比較由文本行組成的序列，并產(chǎn)生可供人閱讀的差異或增量信息。 Differ 統(tǒng)一使用 SequenceMatcher 來完成行序列的比較以及相似（接近匹配）行內(nèi)部字符序列的比較。

Differ 增量的每一行均以雙字母代碼打頭：

雙字母代碼	含意
'- '	行為序列 1 所獨有
'+ '	行為序列 2 所獨有
'  '	行在兩序列中相同
'? '	行不存在于任一輸入序列

Lines beginning with '?' attempt to guide the eye to intraline differences, and were not present in either input sequence. These lines can be confusing if the sequences contain whitespace characters, such as spaces, tabs or line breaks.

class difflib.HtmlDiff?

這個類可用于創(chuàng)建 HTML 表格（或包含表格的完整 HTML 文件）以并排地逐行顯示文本比較，行間與行外的更改將突出顯示。 此表格可以基于完全或上下文差異模式來生成。

這個類的構(gòu)造函數(shù)：

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

初始化 HtmlDiff 的實例。

tabsize 是一個可選關(guān)鍵字參數(shù)，指定制表位的間隔，默認值為 8。

wrapcolumn 是一個可選關(guān)鍵字參數(shù)，指定行文本自動打斷并換行的列位置，默認值為 None 表示不自動換行。

linejunk 和 charjunk 均是可選關(guān)鍵字參數(shù)，會傳入 ndiff() (被 HtmlDiff 用來生成并排顯示的 HTML 差異)。 請參閱 ndiff() 文檔了解參數(shù)默認值及其說明。

下列是公開的方法

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

比較 fromlines 和 tolines (字符串列表) 并返回一個字符串，表示一個完整 HTML 文件，其中包含各行差異的表格，行間與行外的更改將突出顯示。

fromdesc 和 todesc 均是可選關(guān)鍵字參數(shù)，指定來源/目標文件的列標題字符串（默認均為空白字符串）。

context 和 numlines 均是可選關(guān)鍵字參數(shù)。 當只要顯示上下文差異時就將 context 設為 True，否則默認值 False 為顯示完整文件。 numlines 默認為 5。 當 context 為 True 時 numlines 將控制圍繞突出顯示差異部分的上下文行數(shù)。 當 context 為 False 時 numlines 將控制在使用 "next" 超鏈接時突出顯示差異部分之前所顯示的行數(shù)（設為零則會導致 "next" 超鏈接將下一個突出顯示差異部分放在瀏覽器頂端，不添加任何前導上下文）。

備注

fromdesc 和 todesc 會被當作未轉(zhuǎn)義的 HTML 來解讀，當接收不可信來源的輸入時應該適當?shù)剡M行轉(zhuǎn)義。

在 3.5 版更改: 增加了 charset 關(guān)鍵字參數(shù)。 HTML 文檔的默認字符集從 'ISO-8859-1' 更改為 'utf-8'。

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

比較 fromlines 和 tolines (字符串列表) 并返回一個字符串，表示一個包含各行差異的完整 HTML 表格，行間與行外的更改將突出顯示。

此方法的參數(shù)與 make_file() 方法的相同。

Tools/scripts/diff.py 是這個類的命令行前端，其中包含一個很好的使用示例。

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

比較 a 和 b (字符串列表)；返回上下文差異格式的增量信息 (一個產(chǎn)生增量行的 generator)。

所謂上下文差異是一種只顯示有更改的行再加幾個上下文行的緊湊形式。 更改被顯示為之前/之后的樣式。 上下文行數(shù)由 n 設定，默認為三行。

默認情況下，差異控制行（以 *** or --- 表示）是通過末尾換行符來創(chuàng)建的。 這樣做的好處是從 io.IOBase.readlines() 創(chuàng)建的輸入將得到適用于 io.IOBase.writelines() 的差異信息，因為輸入和輸出都帶有末尾換行符。

對于沒有末尾換行符的輸入，應將 lineterm 參數(shù)設為 ""，這樣輸出內(nèi)容將統(tǒng)一不帶換行符。

上下文差異格式通常帶有一個記錄文件名和修改時間的標頭。 這些信息的部分或全部可以使用字符串 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)?

返回由最佳“近似”匹配構(gòu)成的列表。 word 為一個指定目標近似匹配的序列（通常為字符串），possibilities 為一個由用于匹配 word 的序列構(gòu)成的列表（通常為字符串列表）。

可選參數(shù) n (默認為 3) 指定最多返回多少個近似匹配； n 必須大于 0.

可選參數(shù) cutoff (默認為 0.6) 是一個 [0, 1] 范圍內(nèi)的浮點數(shù)。 與 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 形式的增量信息 (一個產(chǎn)生增量行的 generator)。

可選關(guān)鍵字形參 linejunk 和 charjunk 均為過濾函數(shù) (或為 None)：

linejunk: 此函數(shù)接受單個字符串參數(shù)，如果其為垃圾字符串則返回真值，否則返回假值。 默認為 None。 此外還有一個模塊層級的函數(shù) IS_LINE_JUNK()，它會過濾掉沒有可見字符的行，除非該行添加了至多一個井號符 ('#') -- 但是下層的 SequenceMatcher 類會動態(tài)分析哪些行的重復頻繁到足以形成噪音，這通常會比使用此函數(shù)的效果更好。

charjunk: 此函數(shù)接受一個字符（長度為 1 的字符串)，如果其為垃圾字符則返回真值，否則返回假值。 默認為模塊層級的函數(shù) IS_CHARACTER_JUNK()，它會過濾掉空白字符（空格符或制表符；但包含換行符可不是個好主意?。?/p>

Tools/scripts/ndiff.py 是這個函數(shù)的命令行前端。

>>>

>>> 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)?

返回兩個序列中產(chǎn)生增量的那一個。

給出一個由 Differ.compare() 或 ndiff() 產(chǎn)生的 序列，提取出來自文件 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 (字符串列表)；返回統(tǒng)一差異格式的增量信息 (一個產(chǎn)生增量行的 generator)。

所以統(tǒng)一差異是一種只顯示有更改的行再加幾個上下文行的緊湊形式。 更改被顯示為內(nèi)聯(lián)的樣式（而不是分開的之前/之后文本塊）。 上下文行數(shù)由 n 設定，默認為三行。

默認情況下，差異控制行 (以 ---, +++ 或 @@ 表示) 是通過末尾換行符來創(chuàng)建的。 這樣做的好處是從 io.IOBase.readlines() 創(chuàng)建的輸入將得到適用于 io.IOBase.writelines() 的差異信息，因為輸入和輸出都帶有末尾換行符。

對于沒有末尾換行符的輸入，應將 lineterm 參數(shù)設為 ""，這樣輸出內(nèi)容將統(tǒng)一不帶換行符。

上下文差異格式通常帶有一個記錄文件名和修改時間的標頭。 這些信息的部分或全部可以使用字符串 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 (字節(jié)串對象列表)；產(chǎn)生以 dfunc 所返回格式表示的差異行列表（也是字節(jié)串）。 dfunc 必須是可調(diào)用對象，通常為 unified_diff() 或 context_diff()。

允許你比較編碼未知或不一致的數(shù)據(jù)。 除 n 之外的所有輸入都必須為字節(jié)串對象而非字符串。 作用方式為無損地將所有輸入 (除 n 之外) 轉(zhuǎn)換為字符串，并調(diào)用 dfunc(a, b, fromfile, tofile, fromfiledate, tofiledate, n, lineterm)。 dfunc 的輸出會被隨即轉(zhuǎn)換回字節(jié)串，這樣你所得到的增量行將具有與 a 和 b 相同的未知/不一致編碼。

3.5 新版功能.

difflib.IS_LINE_JUNK(line)?

對于可忽略的行返回 True。 如果 line 為空行或只包含單個 '#' 則 line 行就是可忽略的，否則就是不可忽略的。 此函數(shù)被用作較舊版本 ndiff() 中 linejunk 形參的默認值。

difflib.IS_CHARACTER_JUNK(ch)?

對于可忽略的字符返回 True。 字符 ch 如果為空格符或制表符則 ch 就是可忽略的，否則就是不可忽略的。 此函數(shù)被用作 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()