gh-154661: Reorganize difflib documentation by encukou · Pull Request #154662 · python/cpython

encukou · 2026-07-24T23:49:05Z

Put common information in an intro section at the beginning, rather than in a duplicate doc entry for SequenceMatcher
Merge the two doc entries for Differ
Document timing as a CPython implementation detail
Group examples together

Issue: Reorganize difflib documentation #154661

- Put common information in an intro section at the beginning, rather than in a duplicate doc entry for `SequenceMatcher` - Merge the two doc entries for `Differ` - Document timing as a CPython implementation detail - Group examples together

read-the-docs-community · 2026-07-24T23:53:00Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #33780055 | 📁 Comparing 300edbc against main (59e67c2)

🔍 Preview build

7 files changed · ± 7 modified

± Modified

hugovk

Thank you, much clearer 👍

hugovk · 2026-07-25T08:23:08Z

+   The basic Ratcliff-Obershelp algorithm is cubic time in the worst
+   case and quadratic time in the expected case.
+   :mod:`difflib`'s algorithm is quadratic time for the worst case and has
+   expected-case behavior dependent in a complicated way on how many elements


Suggested change

expected-case behavior dependent in a complicated way on how many elements

expected-case behavior dependent on a complicated way on how many elements

in is correct here -- the behaviour depends on how many elements the sequences have in common, but the relation isn't linear, or quadratic, or otherwise simple.

hugovk · 2026-07-25T08:25:11Z

+   because they synch up anywhere possible, sometimes at accidental matches
+   100 pages apart.
+   Restricting synch points to contiguous matches preserves some notion of


We use "sync" everywhere else, and avoids mispronunciation as "sinch" (which I have heard):

Suggested change

because they synch up anywhere possible, sometimes at accidental matches

100 pages apart.

Restricting synch points to contiguous matches preserves some notion of

because they sync up anywhere possible, sometimes at accidental matches

100 pages apart.

Restricting sync points to contiguous matches preserves some notion of

This PR just moves this text; I'd rather keep the original wording unchanged.
Merriam-Webster recognizes both sync & synch.

And acknowledges "less commonly synch" :) But fine to keep it as is in this PR.

There's no harm in keeping some of the page's old-timey charm :)

hugovk · 2026-07-25T08:26:32Z

+      be ignored.  Read the description of the
+      :meth:`~SequenceMatcher.find_longest_match` method's *isjunk*


Perhaps? (and may need an escape)

Suggested change

be ignored. Read the description of the

:meth:`~SequenceMatcher.find_longest_match` method's *isjunk*

be ignored. Read the description of

:meth:`~SequenceMatcher.find_longest_match`'s *isjunk*

Let's keep the original for now.

hugovk · 2026-07-25T08:30:42Z

And let's backport (if trivial).

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

encukou

Thanks for proofreading!

encukou · 2026-07-27T14:53:51Z

+   The basic Ratcliff-Obershelp algorithm is cubic time in the worst
+   case and quadratic time in the expected case.
+   :mod:`difflib`'s algorithm is quadratic time for the worst case and has
+   expected-case behavior dependent in a complicated way on how many elements


in is correct here -- the behaviour depends on how many elements the sequences have in common, but the relation isn't linear, or quadratic, or otherwise simple.

encukou · 2026-07-27T14:56:21Z

+   because they synch up anywhere possible, sometimes at accidental matches
+   100 pages apart.
+   Restricting synch points to contiguous matches preserves some notion of


This PR just moves this text; I'd rather keep the original wording unchanged.
Merriam-Webster recognizes both sync & synch.

encukou · 2026-07-27T14:57:04Z

+      be ignored.  Read the description of the
+      :meth:`~SequenceMatcher.find_longest_match` method's *isjunk*


Let's keep the original for now.

hugovk

Thanks!

hugovk · 2026-07-27T15:29:52Z

+   because they synch up anywhere possible, sometimes at accidental matches
+   100 pages apart.
+   Restricting synch points to contiguous matches preserves some notion of


And acknowledges "less commonly synch" :) But fine to keep it as is in this PR.

miss-islington-app · 2026-07-28T09:04:27Z

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

bedevere-app · 2026-07-28T09:04:42Z

GH-154805 is a backport of this pull request to the 3.15 branch.

bedevere-app · 2026-07-28T09:04:48Z

GH-154806 is a backport of this pull request to the 3.14 branch.

bedevere-app · 2026-07-28T09:04:53Z

GH-154807 is a backport of this pull request to the 3.13 branch.

Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Reorganize difflib documentation

4bcbafe

- Put common information in an intro section at the beginning, rather than in a duplicate doc entry for `SequenceMatcher` - Merge the two doc entries for `Differ` - Document timing as a CPython implementation detail - Group examples together

encukou added the docs Documentation in the Doc dir label Jul 24, 2026

github-project-automation Bot added this to Docs PRs Jul 24, 2026

github-project-automation Bot moved this to Todo in Docs PRs Jul 24, 2026

bedevere-app Bot added the skip news label Jul 24, 2026

bedevere-app Bot mentioned this pull request Jul 24, 2026

Reorganize difflib documentation #154661

Open

bedevere-app Bot added the awaiting core review label Jul 24, 2026

encukou mentioned this pull request Jul 24, 2026

gh-118150: warn in doc about results asymmetry for difflib junk #153892

Merged

hugovk reviewed Jul 25, 2026

View reviewed changes

hugovk added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jul 25, 2026

Apply suggestions from code review

300edbc

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

encukou commented Jul 27, 2026

View reviewed changes

hugovk approved these changes Jul 27, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Jul 27, 2026

encukou merged commit 1a40b7b into python:main Jul 28, 2026
33 checks passed

bedevere-app Bot removed the awaiting merge label Jul 28, 2026

github-project-automation Bot moved this from Todo to Done in Docs PRs Jul 28, 2026

encukou deleted the difflib-doc branch July 28, 2026 09:04

bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jul 28, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Jul 28, 2026

bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label Jul 28, 2026

hugovk added a commit that referenced this pull request Jul 28, 2026

[3.15] gh-154661: Reorganize difflib documentation (GH-154662) (#154805)

2e2dc91

Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

hugovk added a commit that referenced this pull request Jul 28, 2026

[3.14] gh-154661: Reorganize difflib documentation (GH-154662) (#154806)

c3b7eb0

Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

hugovk added a commit that referenced this pull request Jul 28, 2026

[3.13] gh-154661: Reorganize difflib documentation (GH-154662) (#154807)

2d0da0b

Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

	expected-case behavior dependent in a complicated way on how many elements
	expected-case behavior dependent on a complicated way on how many elements

		be ignored. Read the description of the
		:meth:`~SequenceMatcher.find_longest_match` method's isjunk

Uh oh!

Uh oh!

Conversation

encukou commented Jul 24, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hugovk commented Jul 25, 2026

Uh oh!

encukou left a comment

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!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app Bot commented Jul 28, 2026

Uh oh!

bedevere-app Bot commented Jul 28, 2026

Uh oh!

bedevere-app Bot commented Jul 28, 2026

Uh oh!

bedevere-app Bot commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

encukou commented Jul 24, 2026 •

edited by bedevere-app Bot

Loading

read-the-docs-community Bot commented Jul 24, 2026 •

edited

Loading