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

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

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

class difflib.SequenceMatcher

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

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

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

Изменено в версии 3.2: Добавлен параметр автозапуск.

class difflib.Differ¶

Это класс для сравнения последовательностей строк текста и создания удобочитаемых различий или дельт. Different использует 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 являются необязательными аргументами ключевых слов для указания строк заголовка столбца from/to файла (по умолчанию используется пустая строка).

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

Примечание

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

Изменено в версии 3.5: кодировка Добавлен аргумент, содержащий только ключевое слово. Кодировка 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 (списки строк); верните дельту (a generator, генерирующую дельта-строки) в формате контекстной разницы.

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

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

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

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

>>> import sys
>>> from difflib import *
>>> 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 (a 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)¶

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

Учитывая последовательность , полученную с помощью :meth:`Differ.compare` или :func:`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 (списки строк); верните дельту (a generator, генерирующую дельта-строки) в унифицированном формате diff.

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

По умолчанию управляющие строки diff (те, что содержат ---, +++, или @@) создаются с завершающей новой строкой. Это полезно для того, чтобы входные данные, созданные из io.IOBase.readlines(), приводили к различиям, которые подходят для использования с 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']
>>> 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 (списки объектов bytes), используя dfunc; получите последовательность дельта-строк (также байтов) в формате, возвращаемом dfunc. dfunc должен быть вызываемым, обычно либо unified_diff(), либо context_diff().

Позволяет сравнивать данные с неизвестной или несогласованной кодировкой. Все входные данные, кроме n, должны быть объектами bytes, а не 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.