6.3. difflib – Вспомогательные средства для вычисления дельт¶difflib – Helpers for computing deltas

Этот модуль предоставляет классы и функции для сравнения последовательностей. Его можно использовать, например, для сравнения файлов, и он может выводить информацию о различиях в различных форматах, включая HTML, контекстные и объединённые диффы. Для сравнения каталогов и файлов смотрите также модуль filecmp.

class difflib.SequenceMatcher¶

Это гибкий класс для сравнения пар последовательностей любого типа, при условии, что элементы последовательностей являются хэшируемыми. Базовый алгоритм предшествует алгоритму, опубликованному в конце 1980-х годов Рэтклиффом и Обершелпом под громким названием «гештальт-сопоставление шаблонов», и немного сложнее его. Идея заключается в поиске самой длинной непрерывной совпадающей подпоследовательности, не содержащей «мусорных» элементов (алгоритм Рэтклиффа и Обершелпа не учитывает мусор). Затем эта же идея рекурсивно применяется к частям последовательностей слева и справа от совпадающей подпоследовательности. Это не даёт минимальных последовательностей редактирования, но обычно даёт совпадения, которые «выглядят правильно» для человека.

Время выполнения: Базовый алгоритм Рэтклиффа-Обершелпа имеет кубическую сложность в худшем случае и квадратичную в среднем. SequenceMatcher имеет квадратичную сложность в худшем случае, а поведение в среднем зависит сложным образом от того, сколько элементов у последовательностей общих; в лучшем случае сложность линейная.

Автоматическая эвристика мусора: SequenceMatcher поддерживает эвристику, которая автоматически помечает некоторые элементы последовательности как мусор. Эвристика подсчитывает, сколько раз каждый отдельный элемент встречается в последовательности. Если дубликаты элемента (после первого) составляют более 1% последовательности и длина последовательности не менее 200 элементов, этот элемент помечается как «популярный» и считается мусором для целей сопоставления последовательностей. Эту эвристику можно отключить, установив аргумент autojunk в значение False при создании SequenceMatcher.

Новое в версии 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)¶

Сравнивает fromlines и tolines (списки строк) и возвращает строку, содержащую полный HTML-файл с таблицей, отображающей построчные различия с подсветкой изменений между строками и внутри строк.

fromdesc и todesc – необязательные именованные аргументы для задания строк заголовков столбцов исходного и целевого файлов (оба по умолчанию равны пустой строке).

context и numlines – необязательные именованные аргументы. Установите context в значение True, чтобы показывать контекстные различия, иначе по умолчанию False, показывающее полные файлы. numlines по умолчанию равен 5. Когда context равно True, numlines управляет количеством строк контекста, окружающих подсветку различий. Когда context равно False, numlines управляет количеством строк, показываемых перед подсветкой различий при использовании гиперссылок «далее» (установка нуля приведёт к тому, что гиперссылка «далее» будет помещать следующую подсветку различий в верхнюю часть браузера без предшествующего контекста).

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 (списки строк); возвращает дельту (генератор, порождающий строки дельты) в формате контекстного diff.

Контекстные диффы – это компактный способ показать только изменённые строки плюс несколько строк контекста. Изменения отображаются в стиле «до/после». Количество строк контекста задаётся параметром n, по умолчанию – три.

По умолчанию управляющие строки diff (те, которые содержат *** или ---) создаются с завершающим символом новой строки. Это полезно, так как входные данные, созданные с помощью io.IOBase.readlines(), дают diff, подходящие для использования с io.IOBase.writelines(), поскольку и входные, и выходные данные имеют завершающие символы новой строки.

Для входных данных, не имеющих завершающего перевода строки, установите аргумент lineterm равным "", чтобы выходные данные были полностью без символов новой строки.

Формат контекстного diff обычно содержит заголовок с именами файлов и временем изменения. Любые или все из них могут быть заданы строками для fromfile, tofile, fromfiledate и tofiledate. Время изменения обычно указывается в формате ISO 8601. Если не указано, строки по умолчанию пусты.

>>> 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)  
*** 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('apple', keyword.kwlist)
[]
>>> get_close_matches('accept', keyword.kwlist)
['except']

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

Сравнивает a и b (списки строк); возвращает дельту в стиле Differ (генератор, порождающий строки дельты).

Необязательные именованные параметры linejunk и charjunk предназначены для функций фильтрации (или None):

linejunk: Функция, которая принимает один строковый аргумент и возвращает true, если строка является мусором, и false в противном случае. По умолчанию None. Также существует функция уровня модуля IS_LINE_JUNK(), которая отфильтровывает строки без видимых символов, за исключением не более одного символа решётки ('#') – однако базовый класс SequenceMatcher выполняет динамический анализ того, какие строки настолько часты, что составляют шум, и это обычно работает лучше, чем использование этой функции.

charjunk: Функция, которая принимает символ (строку длины 1) и возвращает истину, если символ является мусором, и ложь в противном случае. По умолчанию – функция уровня модуля IS_CHARACTER_JUNK(), которая отфильтровывает пробельные символы (пробел или табуляцию; примечание: не стоит включать сюда символ новой строки!).

Tools/scripts/ndiff.py – это интерфейс командной строки для этой функции.

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

difflib.restore(sequence, which)¶

Возвращает одну из двух последовательностей, породивших дельту.

Принимает sequence, созданный с помощью Differ.compare() или ndiff(), извлекает строки, относящиеся к файлу 1 или 2 (параметр which), удаляя префиксы строк.

Пример:

>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
...              'ore\ntree\nemu\n'.splitlines(1))
>>> diff = list(diff) # материализовать сгенерированную дельту в список
>>> 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 (списки строк); возвращает дельту (генератор, порождающий строки дельты) в формате unified diff.

Унифицированные различия – это компактный способ показа только изменённых строк плюс несколько строк контекста. Изменения отображаются встроенным стилем (вместо отдельных блоков «до» и «после»). Количество строк контекста задаётся параметром n, по умолчанию равным трём.

По умолчанию строки управления diff (те, что с ---, +++ или @@) создаются с завершающим переводом строки. Это полезно, потому что входные данные, полученные из io.IOBase.readlines(), дают diff, подходящий для использования с io.IOBase.writelines(), поскольку и входные, и выходные данные имеют завершающие переводы строк.

Для входных данных, не имеющих завершающего перевода строки, установите аргумент lineterm равным "", чтобы выходные данные были полностью без символов новой строки.

Формат контекстного diff обычно содержит заголовок с именами файлов и временем изменения. Любые или все из них могут быть заданы строками для fromfile, tofile, fromfiledate и tofiledate. Время изменения обычно указывается в формате ISO 8601. Если не указано, строки по умолчанию пусты.

>>> 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)   
--- before.py
+++ after.py
@@ -1,4 +1,4 @@
-bacon
-eggs
-ham
+python
+eggy
+hamster
 guido

Смотрите Интерфейс командной строки для difflib для более подробного примера.

difflib.IS_LINE_JUNK(line)¶

Возвращает True для строк, которые можно игнорировать. Строка line игнорируется, если line пуста или содержит только '#', иначе не игнорируется. В старых версиях используется как значение по умолчанию для параметра linejunk в ndiff().

difflib.IS_CHARACTER_JUNK(ch)¶

Возвращает True для игнорируемых символов. Символ ch игнорируется, если ch является пробелом или табуляцией, иначе не игнорируется. Используется как значение по умолчанию для параметра charjunk в ndiff().

>>> 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(1)
>>> 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(1)

>>> 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.

""" Интерфейс командной строки для difflib.py, выводящий разницу в четырёх форматах:

* ndiff:    выводит каждую строку и подсвечивает изменения между строками.
* context:  подсвечивает кластеры изменений в формате «до/после».
* unified:  подсвечивает кластеры изменений во встроенном формате.
* html:     генерирует построчное сравнение с подсветкой изменений.

"""

import sys, os, time, difflib, optparse

def main():
     # Настройка парсера аргументов
    usage = "usage: %prog [options] fromfile tofile"
    parser = optparse.OptionParser(usage)
    parser.add_option("-c", action="store_true", default=False,
                      help='Produce a context format diff (default)')
    parser.add_option("-u", action="store_true", default=False,
                      help='Produce a unified format diff')
    hlp = 'Produce HTML side by side diff (can use -c and -l in conjunction)'
    parser.add_option("-m", action="store_true", default=False, help=hlp)
    parser.add_option("-n", action="store_true", default=False,
                      help='Produce a ndiff format diff')
    parser.add_option("-l", "--lines", type="int", default=3,
                      help='Set number of context lines (default 3)')
    (options, args) = parser.parse_args()

    if len(args) == 0:
        parser.print_help()
        sys.exit(1)
    if len(args) != 2:
        parser.error("need to specify both a fromfile and tofile")

    n = options.lines
    fromfile, tofile = args # в соответствии со строкой использования

    # передаются в качестве аргументов функции diff
    fromdate = time.ctime(os.stat(fromfile).st_mtime)
    todate = time.ctime(os.stat(tofile).st_mtime)
    with open(fromfile) as fromf, open(tofile) as tof:
        fromlines, tolines = list(fromf), list(tof)

    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)

    # используется writelines, так как diff – генератор
    sys.stdout.writelines(diff)

if __name__ == '__main__':
    main()