gh-133722: Add Difflib theme to `_colorize` and 'color' option to `difflib.unified_diff` 10000 #133725

dougthor42 · 2025-05-09T03:31:17Z

Add a color arg (defaulting to False) to difflib.unified_diff. When True, ANSI color codes are injected to the diff lines so that the printed result looks like git diff --color:

>>> import difflib
>>> args = [['one', 'three'], ['two', 'three'], 'Original', 'Current']
>>> for line in difflib.unified_diff(*args, lineterm='', color=True):
...     print(line)
...     
--- Original
+++ Current
@@ -1,2 +1,2 @@
-one
+two
 three

Fixes #133722.

It's a bummer, I just missed the feature freeze window for 3.14 (it was yesterday! 😭), but c'est la vie!

Issue: Add a color: bool arg to difflib.unified_diff #133722

📚 Documentation preview 📚: https://cpython-previews--133725.org.readthedocs.build/

Fixes pythongh-133722.

tomasr8 · 2025-05-09T07:29:06Z

Thanks for the PR!

With the basic theming support in #133347 merged, perhaps we could define a separate difflib theme and use that here?

Doc/library/difflib.rst

hugovk · 2025-05-09T17:00:35Z

Thanks for the PR! I had a play with something similar but didn't get very far before the 3.14 freeze.

With the basic theming support in #133347 merged, perhaps we could define a separate difflib theme and use that here?

Yes, let's add theming support.

See this docstring for instructions.

For a couple of standalone examples of adding theme support to a module, see 230d658 and 5c5c3e1 from that PR.

dougthor42 · 2025-05-09T17:14:33Z

Ah, TIL! Thanks, I'll take a look at those docs and update accordingly. It'll be a few days a least before I can get to it, so for now I'll revert this back to draft.

hugovk · 2025-05-09T20:49:23Z

Absolutely no rush for this, we have 12 months until the 3.15 feature freeze. Don't hesitate if you have questions :)

dougthor42

Wow that was really easy! The examples helped a lot too, thanks! PTAL at your leisure.

Doc/library/difflib.rst

dougthor42 · 2025-05-11T04:41:32Z

Lib/_colorize.py

+    equal: str = ANSIColors.RESET  # context lines
+    insert: str = ANSIColors.GREEN
+    delete: str = ANSIColors.RED


I opted to use the difflib.context_diff internal terminology here. Should I use the more git-like terms context, added, and removed instead?

Hmm, maybe the Git-like terms if they're going to be more familiar with people and if the difflib ones are all internal.

Where does Git mention them?

Overall they are defined in the GNU unified diff detailed description.

The git diff man page mentions them in a variety of places (emphasis mine):

-U
--unified=

Generate diffs with lines of context instead of the usual three. Implies --patch.

Generating patch text with -p

Hunk headers mention the name of the function to which the hunk applies.

plain

Any line that is added in one location and was removed in another location will be colored with color.diff.newMoved.

Though sometimes it uses "deleted" instead of "removed":

--numstat

Similar to --stat, but shows number of added and deleted lines

I've gone ahead and switched to the GNU unified diff terms prior to the requested sorting. Also, to keep consistent with the other dataclass attributes (which are not currently sorted), the reset value was left at the end.

ZeroIntensity

Hm, I would expect to see this in the difflib CLI rather than a library function. But, as it turns out, difflib doesn't have a working CLI? That's different than what's documented.

I personally think it's worth adding one if we're going through the effort to add colorization.

hugovk

Let's also add a What's New entry, perhaps something similar to https://docs.python.org/3.14/whatsnew/3.14.html#whatsnew314-color-argparse

Doc/library/difflib.rst

hugovk · 2025-05-11T18:26:45Z

Lib/_colorize.py

+    equal: str = ANSIColors.RESET  # context lines
+    insert: str = ANSIColors.GREEN
+    delete: str = ANSIColors.RED


Hmm, maybe the Git-like terms if they're going to be more familiar with people and if the difflib ones are all internal.

Where does Git mention them?

Lib/_colorize.py

hugovk · 2025-05-11T18:27:20Z

Lib/_colorize.py

    syntax: Syntax = field(default_factory=Syntax)
    traceback: Traceback = field(default_factory=Traceback)
    unittest: Unittest = field(default_factory=Unittest)
+    difflib: Difflib = field(default_factory=Difflib)


And here:

Suggested change

syntax: Syntax = field(default_factory=Syntax)

traceback: Traceback = field(default_factory=Traceback)

unittest: Unittest = field(default_factory=Unittest)

difflib: Difflib = field(default_factory=Difflib)

difflib: Difflib = field(default_factory=Difflib)

syntax: Syntax = field(default_factory=Syntax)

traceback: Traceback = field(default_factory=Traceback)

unittest: Unittest = field(default_factory=Unittest)

I'm very slightly concerned about sorting when the dataclasses aren't kw_only.

Should I update the dataclass decorator to include kw_only=True and then sort? Or is that out of scope of this PR?

Let's ask @ambv about this.

Lib/_colorize.py

Lib/difflib.py

hugovk · 2025-05-11T18:30:47Z

Misc/NEWS.d/next/Library/2025-05-08-20-03-20.gh-issue-133722.1-B82a.rst

@@ -0,0 +1,2 @@
+Added a ``color`` option to :func:`difflib.unified_diff` that injects ANSI color


Suggested change

Added a ``color`` option to :func:`difflib.unified_diff` that injects ANSI color

Added a *color* option to :func:`difflib.unified_diff` that injects ANSI color

Still todo :)

dougthor42

What's New entry

Added, assuming a 3.15 release.

I would expect to see this in the difflib CLI rather than a library function.

My underlying use case and request is specific to the library function. That said, I agree that any CLI should also include coloring.

difflib doesn't have a working CLI? That's different than what's documented.

Hmm... I'm not able to find the difflib CLI docs? The closest thing I found was https://docs.python.org/3/library/difflib.html#difflib-interface but that just looks like an example of how to make a CLI for difflib. Was that what you were thinking of?

If I actually read the comment I would have seen that the docs were indeed linked... And yes, the linked item is just an example of how one might make a CLI for difflib.

I personally think it's worth adding one if we're going through the effort to add colorization.

I'd be happy to modify any existing CLI code to include colors. I can't say I'd have the time to add a CLI though.

Doc/library/difflib.rst

dougthor42 · 2025-05-14T03:08:27Z

Lib/_colorize.py

+    equal: str = ANSIColors.RESET  # context lines
+    insert: str = ANSIColors.GREEN
+    delete: str = ANSIColors.RED


Overall they are defined in the GNU unified diff detailed description.

The git diff man page mentions them in a variety of places (emphasis mine):

-U
--unified=

Generate diffs with lines of context instead of the usual three. Implies --patch.

Generating patch text with -p

Hunk headers mention the name of the function to which the hunk applies.

plain

Any line that is added in one location and was removed in another location will be colored with color.diff.newMoved.

Though sometimes it uses "deleted" instead of "removed":

--numstat

Similar to --stat, but shows number of added and deleted lines

I've gone ahead and switched to the GNU unified diff terms prior to the requested sorting. Also, to keep consistent with the other dataclass attributes (which are not currently sorted), the reset value was left at the end.

Lib/_colorize.py

dougthor42 · 2025-05-14T03:15:35Z

Lib/_colorize.py

    syntax: Syntax = field(default_factory=Syntax)
    traceback: Traceback = field(default_factory=Traceback)
    unittest: Unittest = field(default_factory=Unittest)
+    difflib: Difflib = field(default_factory=Difflib)


I'm very slightly concerned about sorting when the dataclasses aren't kw_only.

Should I update the dataclass decorator to include kw_only=True and then sort? Or is that out of scope of this PR?

dougthor42 · 2025-05-14T03:20:01Z

Misc/NEWS.d/next/Library/2025-05-08-20-03-20.gh-issue-133722.1-B82a.rst

@@ -0,0 +1,2 @@
+Added a ``color`` option to :func:`difflib.unified_diff` that injects ANSI color


Lib/_colorize.py

Lib/test/test_difflib.py

dougthor42 · 2025-05-14T03:53:37Z

Hmm... I'm not able to find the difflib CLI docs? The closest thing I found

@ZeroIntensity Doh! I just re-read your comment and realized you linked to it haha.

Anyway yeah that's just example code. To my knowledge there is no official CLI for difflib.

Doc/library/difflib.rst

Doc/whatsnew/3.15.rst

hugovk · 2025-05-15T14:51:54Z

Lib/_colorize.py

    syntax: Syntax = field(default_factory=Syntax)
    traceback: Traceback = field(default_factory=Traceback)
    unittest: Unittest = field(default_factory=Unittest)
+    difflib: Difflib = field(default_factory=Difflib)


Let's ask @ambv about this.

Lib/difflib.py

Lib/test/test_difflib.py

hugovk · 2025-05-19T17:02:14Z

Misc/NEWS.d/next/Library/2025-05-08-20-03-20.gh-issue-133722.1-B82a.rst

@@ -0,0 +1,2 @@
+Added a ``color`` option to :func:`difflib.unified_diff` that injects ANSI color


Still todo :)

Wulian233 · 2025-05-28T10:21:04Z

This PR needs to be updated to resolve the conflicts → #134581

dougthor42 added 4 commits May 8, 2025 19:51

Add test case

5c5b248

Add 'color' arg to difflib.unified_diff.

fdc0fa0

Fixes pythongh-133722.

Update docs and ACKs

fcdd7ab

blurb

0e9b070

bedevere-app bot mentioned this pull request May 9, 2025

Add a color: bool arg to difflib.unified_diff #133722

Open

fixup to follow convention

7c31749

dougthor42 marked this pull request as ready for review May 9, 2025 03:40

bedevere-app bot added the awaiting review label May 9, 2025

hugovk reviewed May 9, 2025

View reviewed changes

Doc/library/difflib.rst Outdated Show resolved Hide resolved

dougthor42 marked this pull request as draft May 9, 2025 17:14

bedevere-app bot removed the awaiting review label May 9, 2025

dougthor42 added 5 commits May 10, 2025 21:02

Add 'Difflib' theme

66475a2

fixup tests

dbf0547

Switch to using themes. So easy!

a72012e

use 'next' in versionchanged docs

2a3d818

turns out 'git diff' adds reset to the start and end of context lines

252982e

dougthor42 commented May 11, 2025

View reviewed changes

Doc/library/difflib.rst Outdated Show resolved Hide resolved

dougthor42 marked this pull request as ready for review May 11, 2025 04:38

bedevere-app bot added the awaiting review label May 11, 2025

dougthor42 changed the title ~~gh-133722: Add 'color' option to 'difflib.unified_diff'~~ gh-133722: Add Difflib theme to _colorize and 'color' option to difflib.unified_diff May 11, 2025

dougthor42 commented May 11, 2025

View reviewed changes

ZeroIntensity reviewed May 11, 2025

View reviewed changes

hugovk reviewed May 11, 2025

View reviewed changes

dougthor42 added 3 commits May 13, 2025 20:11

Use GNU unified diff terms

3422fa7

move class

bffdd71

kw-only the 'color' arg

3255866

dougthor42 added 3 commits May 13, 2025 20:19

Doc formatting updates

c48a6ac

Sort the things that are safe to sort without kw_only=True

8ca50fa

Update what's new

eb0e81e

dougthor42 commented May 14, 2025

View reviewed changes

dougthor42 added 2 commits May 13, 2025 20:57

Merge remote-tracking branch 'upstream/main' into difflib-color-gh133722

f7b34c3

fixup docs

fb092b0

hugovk reviewed May 19, 2025

View reviewed changes

dougthor42 added 3 commits May 19, 2025 21:04

fixup docs

734b0bc

Code review: docs, whatsnew, f-strings, news

8a10e40

force_colorized

57b80d1

		@@ -0,0 +1,2 @@
		Added a ``color`` option to :func:`difflib.unified_diff` that injects ANSI color

	Added a ``color`` option to :func:`difflib.unified_diff` that injects ANSI color
	Added a color option to :func:`difflib.unified_diff` that injects ANSI color

Uh oh!

gh-133722: Add Difflib theme to _colorize and 'color' option to difflib.unified_diff 10000 #133725

Are you sure you want to change the base?

gh-133722: Add Difflib theme to _colorize and 'color' option to difflib.unified_diff #133725

Conversation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gh-133722: Add Difflib theme to `_colorize` and 'color' option to `difflib.unified_diff` 10000 #133725

gh-133722: Add Difflib theme to `_colorize` and 'color' option to `difflib.unified_diff` #133725