diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index 5339186b72f6bc7..e86e72f7578dead 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -338,6 +338,26 @@ Diff generation + tree + emu +.. function:: mdiff(fromlines, tolines, context=None, linejunk=None, charjunk=IS_CHARACTER_JUNK) + + Return a generator yielding marked up *fromlines* and *tolines* side by side differences. + + Optional keyword parameters *context* is number of lines to display on each side the difference, if ``None``, all from/to text lines will be generated; *linejunk* and *charjunk* are filtering functions. + + from/to line tuple -- (line num, line text) + line num -- integer or None (to indicate a context separation) + line text -- original line text with following markers inserted: + + ``'\0+'`` -- marks start of added text + + ``'\0-'`` -- marks start of deleted text + + ``'\0^'`` -- marks start of changed text + + ``'\1'`` -- marks end of added/deleted/changed text + + boolean flag -- None indicates context separation, True indicates + either "from" or "to" line contains a change, otherwise False. .. function:: restore(sequence, which) diff --git a/Lib/difflib.py b/Lib/difflib.py index 95ba8fd782c6c3c..0d70861e4529c1c 100644 --- a/Lib/difflib.py +++ b/Lib/difflib.py @@ -10,6 +10,9 @@ Function ndiff(a, b): Return a delta: the difference between `a` and `b` (lists of strings). +Function mdiff(fromlines, tolines): + Return a generator yielding marked up from/to side by side differences. + Function restore(delta, which): Return one of the two sequences that generated an ndiff delta. @@ -26,7 +29,7 @@ For producing HTML side by side comparison with change highlights. """ -__all__ = ['get_close_matches', 'ndiff', 'restore', 'SequenceMatcher', +__all__ = ['get_close_matches', 'ndiff', 'mdiff', 'restore', 'SequenceMatcher', 'Differ','IS_CHARACTER_JUNK', 'IS_LINE_JUNK', 'context_diff', 'unified_diff', 'diff_bytes', 'HtmlDiff', 'Match'] @@ -1358,7 +1361,7 @@ def ndiff(a, b, linejunk=None, charjunk=IS_CHARACTER_JUNK): """ return Differ(linejunk, charjunk).compare(a, b) -def _mdiff(fromlines, tolines, context=None, linejunk=None, +def mdiff(fromlines, tolines, context=None, linejunk=None, charjunk=IS_CHARACTER_JUNK): r"""Returns generator yielding marked up from/to side by side differences. @@ -2025,7 +2028,7 @@ def make_table(self,fromlines,tolines,fromdesc='',todesc='',context=False, context_lines = numlines else: context_lines = None - diffs = _mdiff(fromlines,tolines,context_lines,linejunk=self._linejunk, + diffs = mdiff(fromlines,tolines,context_lines,linejunk=self._linejunk, charjunk=self._charjunk) # set up iterator to wrap lines that exceed desired width diff --git a/Lib/test/test_difflib.py b/Lib/test/test_difflib.py index 4f99b7c91c654e4..80f6711b6f4b673 100644 --- a/Lib/test/test_difflib.py +++ b/Lib/test/test_difflib.py @@ -114,7 +114,7 @@ def test_hint_indented_properly_with_tabs(self): def test_mdiff_catch_stop_iteration(self): # Issue #33224 self.assertEqual( - list(difflib._mdiff(["2"], ["3"], 1)), + list(difflib.mdiff(["2"], ["3"], 1)), [((1, '\x00-2\x01'), (1, '\x00+3\x01'), True)], ) diff --git a/Misc/NEWS.d/next/Library/2026-09-02-23-38-40.gh-issue-129922.Klr4dt.rst b/Misc/NEWS.d/next/Library/2026-09-02-23-38-40.gh-issue-129922.Klr4dt.rst new file mode 100644 index 000000000000000..bfc8e282ad0645b --- /dev/null +++ b/Misc/NEWS.d/next/Library/2026-09-02-23-38-40.gh-issue-129922.Klr4dt.rst @@ -0,0 +1 @@ +Promote ``difflib._mdiff()`` to a public function named :func:`difflib.mdiff`.