difflib – Средства для вычисления различий¶difflib – Helpers for computing deltas

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

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

class difflib.SequenceMatcher

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

Время выполнения: Базовый алгоритм Рэтклиффа-Обершелпа имеет кубическое время в худшем случае и квадратичное время в ожидаемом. 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 управляет количеством строк, показываемых перед подсветкой различий при использовании гиперссылок «далее» (установка в ноль приведёт к тому, что гиперссылки «далее» будут размещать следующую подсветку различий в верхней части браузера без предшествующего контекста).

Примечание

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

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. Если не указано, строки по умолчанию пусты.

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

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

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

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

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

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

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

Формат unified 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; возвращает последовательность строк дельты (тоже bytes) в формате, возвращаемом dfunc. dfunc должен быть вызываемым объектом, обычно unified_diff() или context_diff().

Позволяет сравнивать данные с неизвестной или несовместимой кодировкой. Все входные данные, кроме n, должны быть объектами bytes, а не str. Работает путём без потерь преобразования всех входных данных (кроме n) в str и вызова dfunc(a, b, fromfile, tofile, fromfiledate, tofiledate, n, lineterm). Затем вывод dfunc снова преобразуется в bytes, поэтому получаемые строки дельты имеют те же неизвестные или несовместимые кодировки, что и 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.

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

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

"""

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

"""ndiff [-q] file1 file2
    или
ndiff (-r1 | -r2) < ndiff_output > file1_or_file2

Выводит в stdout понятный человеку отчёт о различиях файлов. Отмечаются как меж-
строчные, так и внутристрочные различия. Во второй форме воссоздаёт file1
(-r1) или file2 (-r2) в stdout на основе отчёта ndiff со stdin.

В первой форме, если не указан -q ("quiet"), первые две строки
вывода – это

-: file1
+: file2

Каждая следующая строка начинается с двухбуквенного кода:

    "- "    строка, уникальная для file1
    "+ "    строка, уникальная для file2
    "  "    строка, общая для обоих файлов
    "? "    строка, отсутствующая в обоих входных файлах

Строки, начинающиеся с "? ", помогают глазу заметить внутристрочные
различия; в исходных файлах таких строк нет. Эти строки могут
сбивать с толку, если исходные файлы содержат символы табуляции.

Первый файл можно восстановить, оставив только строки, начинающиеся с
"  "  " или "- ", и удалив эти двухсимвольные префиксы; используйте ndiff с -r1.

Второй файл восстанавливается аналогично, но следует оставить только "  " и
""+ "; используйте ndiff с -r2; или, в Unix, второй файл можно
восстановить, пропустив вывод через

    sed -n '/^[+ ] /s/^..//p'
"""

__version__ = 1, 7, 0

import difflib, sys

def fail(msg):
    out = sys.stderr.write
    out(msg + "\n\n")
    out(__doc__)
    return 0

# открыть файл и вернуть файловый объект; ругать и вернуть 0, если не
# удалось открыть
def fopen(fname):
    try:
        return open(fname)
    except IOError as detail:
        return fail("couldn't open " + fname + ": " + str(detail))

# открыть два файла и выдать diff в stdout; вернуть false при проблеме
def fcompare(f1name, f2name):
    f1 = fopen(f1name)
    f2 = fopen(f2name)
    if not f1 or not f2:
        return 0

    a = f1.readlines(); f1.close()
    b = f2.readlines(); f2.close()
    for line in difflib.ndiff(a, b):
        print(line, end=' ')

    return 1

# разобрать args (обычно sys.argv[1:]) и сравнить;
# вернуть false при проблеме

def main(args):
    import getopt
    try:
        opts, args = getopt.getopt(args, "qr:")
    except getopt.error as detail:
        return fail(str(detail))
    noisy = 1
    qseen = rseen = 0
    for opt, val in opts:
        if opt == "-q":
            qseen = 1
            noisy = 0
        elif opt == "-r":
            rseen = 1
            whichfile = val
    if qseen and rseen:
        return fail("can't specify both -q and -r")
    if rseen:
        if args:
            return fail("no args allowed with -r option")
        if whichfile in ("1", "2"):
            restore(whichfile)
            return 1
        return fail("-r value must be 1 or 2")
    if len(args) != 2:
        return fail("need 2 filename args")
    f1name, f2name = args
    if noisy:
        print('-:', f1name)
        print('+:', f2name)
    return fcompare(f1name, f2name)

# прочитать вывод ndiff со stdin и вывести file1 (which=='1') или
# file2 (which=='2') в stdout

def restore(which):
    restored = difflib.restore(sys.stdin.readlines(), which)
    sys.stdout.writelines(restored)

if __name__ == '__main__':
    main(sys.argv[1:])