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

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

Documentation build overview

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

🔍 Preview build

7 files changed · ± 7 modified

± Modified

Thank you, much clearer 👍

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.

I agree with Petr.

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

A tossup.

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.

And let's backport (if trivial).

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

Thanks for proofreading!

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.

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

Let's keep the original for now.

Thanks!

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

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

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

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

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>

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

Closed

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 only security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 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 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 only 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>

dg-pb mentioned this pull request Oct 24, 2026

gh-145209: Composability of difflib #145210

Open

+                 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

+                 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

	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

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

Repository navigation

gh-154661: Reorganize difflib documentation - #154662

gh-154661: Reorganize difflib documentation#154662encukou merged 2 commits intopython:mainpython/cpython:mainfrom encukou:difflib-docencukou/cpython:difflib-docCopy head branch name to clipboard

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!

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

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gh-154661: Reorganize difflib documentation#154662
encukou merged 2 commits into
python:mainfrom
encukou:difflib-doc

encukou commented Jul 24, 2026 •
edited by bedevere-app Bot
Loading

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