difflib — Помощники для вычисления дельт¶

Исходный код: Lib/difflib.py.

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

class difflib.SequenceMatcher

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

Тайминг: Основной алгоритм Ratcliff-Obershelp имеет кубическое время в худшем случае и квадратичное время в ожидаемом случае. 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, *, charset='utf-8')¶

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

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

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

Примечание

fromdesc и todesc интерпретируются как HTML без символов и должны быть правильно экранированы при получении входных данных из ненадежных источников.

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

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

По умолчанию управляющие строки diff (те, что имеют *** или ---) создаются с пропущенной новой строкой. Это полезно для того, чтобы входы, созданные с помощью 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)¶

Возвращает список лучших «достаточно хороших» совпадений. слово - это последовательность, для которой нужны близкие совпадения (обычно строка), а возможности - это список последовательностей, с которыми можно сопоставить слово (обычно список строк).

Необязательный аргумент n (по умолчанию 3) - это максимальное количество близких совпадений, которое нужно вернуть; n должно быть больше, чем 0.

Необязательный аргумент cutoff (по умолчанию 0.6) представляет собой плавающее число в диапазоне [0, 1]. Возможности, которые по крайней мере не похожи на слово, игнорируются.

Лучшие (не более 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: Функция, принимающая один строковый аргумент и возвращающая 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(), извлеките строки, происходящие из файла 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, порождающую строки дельты) в унифицированном формате diff.

Унифицированные диффы - это компактный способ показать только те строки, которые изменились, плюс несколько строк контекста. Изменения отображаются в стиле inline (вместо отдельных блоков before/after). Количество контекстных строк задается параметром 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')¶

Сравните a и b (списки байтовых объектов) с помощью dfunc; выдайте последовательность дельта-строк (также байтов) в формате, возвращаемом dfunc. 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 пуста или содержит один '#', в противном случае она не является игнорируемой. Используется по умолчанию для параметра 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(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()