gh-133722: Add Difflib theme to `_colorize` and 'color' option to `difflib.unified_diff`#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:

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

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/

Fixespythongh-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.

I like this suggestion.

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 · 2025-05-28T22:56:45Z

ACK @Wulian233. I was planning on waiting to resolve conflicts until after @ambv comments on #133725 (comment).

ambv · 2025-05-29T01:21:06Z

@dougthor42 I responded on that comment. It's a good suggestion to make the dataclasses kwonly.

hugovk

Thank you!

hugovk · 2025-06-09T13:13:43Z

Lib/difflib.py

+ Set *color* to ``True`` to enable output in color, similar to
+ :program:`git diff --color`. Even if enabled, it can be
+ :ref:`controlled using environment variables <using-on-controlling-color>`.


The CPython docstrings aren't rendered into docs, so let's use plain formatting like elsewhere. Perhaps:
Suggested change
Set*color*to``True``toenableoutputincolor, similarto
:program:`git diff --color`. Evenifenabled, itcanbe
:ref:`controlled using environment variables <using-on-controlling-color>`.
Set'color'toTruetoenableoutputincolor, similarto
'git diff --color'. Evenifenabled, itcanbe
controlledusingenvironmentvariablessuchas'NO_COLOR'.

Done. Also fixed the 3 spaces thing 🤦

Doc/whatsnew/3.15.rst

python-cla-bot · 2025-07-18T03:49:35Z

All commit authors signed the Contributor License Agreement.

hugovk · 2025-08-08T15:34:08Z

Thank you!

…to `difflib.unified_diff` (python#133725)

dougthor42 added 4 commits May 8, 2025 19:51

Add test case
5c5b248

Add 'color' arg to difflib.unified_diff.
fdc0fa0
Fixespythongh-133722.

Update docs and ACKs
fcdd7ab

blurb
0e9b070

bedevere-appbot mentioned this pull request May 9, 2025
Add a color: bool arg to difflib.unified_diff#133722
Closed

fixup to follow convention
7c31749

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

bedevere-appbot added the awaiting review label May 9, 2025

hugovk reviewed May 9, 2025
View reviewed changes

Doc/library/difflib.rst Outdated Show resolvedHide resolved

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

bedevere-appbot 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 resolvedHide resolved

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

bedevere-appbot 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_diffMay 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

dougthor42 added 2 commits May 28, 2025 21:56

kw_only
c235425

Merge branch 'main' into difflib-color-gh133722
387cfe6

hugovk approved these changes Jun 9, 2025
View reviewed changes

bedevere-appbot added awaiting merge and removed awaiting review labels Jun 9, 2025

Wulian233 reviewed Jun 9, 2025
View reviewed changes

Doc/whatsnew/3.15.rstShow resolvedHide resolved

documentation updates per code review
833d86a

Wulian233 approved these changes Jun 11, 2025
View reviewed changes

Merge branch 'main' into difflib-color-gh133722
25f9d80

hugovk merged commit 34d7351 into python:mainAug 8, 2025
49 checks passed

bedevere-appbot removed the awaiting merge label Aug 8, 2025

dougthor42 deleted the difflib-color-gh133722 branch August 10, 2025 21:59

Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025
pythongh-133722: Add Difflib theme to_colorizeand 'color' option …
2d1c812
…to `difflib.unified_diff` (python#133725)

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

		@@ -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

-Set*color*to``True``toenableoutputincolor, similarto
-:program:`git diff --color`. Evenifenabled, itcanbe
-:ref:`controlled using environment variables <using-on-controlling-color>`.
+Set'color'toTruetoenableoutputincolor, similarto
+'git diff --color'. Evenifenabled, itcanbe
+controlledusingenvironmentvariablessuchas'NO_COLOR'.

Uh oh!

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

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

Uh oh!

Conversation

dougthor42 commented May 9, 2025• edited by github-actions botLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tomasr8 commented May 9, 2025

Uh oh!

Uh oh!

hugovk commented May 9, 2025

Uh oh!

dougthor42 commented May 9, 2025

Uh oh!

hugovk commented May 9, 2025

Uh oh!

dougthor42 left a comment

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!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

hugovk left a comment

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!

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!

dougthor42 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

dougthor42 commented May 14, 2025

Uh oh!

Uh oh!

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

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

dougthor42 commented May 9, 2025•
edited by github-actions bot
Loading

dougthor42 left a comment •
edited
Loading

python-cla-botbot commented Jul 18, 2025•
edited
Loading