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

[Lenormju]

• Issue: Difflib creates unreasonably large diffs #118150

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33647276 | 📁 Comparing 0793740 against main (cffcee4)

  🔍 Preview build  

16 files changed · ± 16 modified

± Modified

• c-api/frame.html
• c-api/veryhigh.html
• library/allos.html
• library/calendar.html
• library/concurrent.interpreters.html
• library/ctypes.html
• library/difflib.html
• library/filecmp.html
• library/functions.html
• library/inspect.html
• and 6 more...

[encukou]

This sounds ungrammatical.
Do we need to note that output can be very large?

Suggested change

	diff than simply reversing the output, sometimes very large.
	diff than reversing the output.

[Lenormju]

I think yes, because it is the original issue, and the most unexpected behavior. #118150 describes a pathological case where, depending on the inputs' order, the diff can be 1186x bigger. I call that surprising, and very large. In this case, it was because most lines got autojunked.

I will fix the grammar right now, sorry for that.

[Lenormju]

I reworded the two junk-related paragraphs.
About the size:

But it can also cause pathological cases where too many items considered junk cause an unexpectedly large (but correct) diff result.

[encukou]

But, is it the only case that can produce unexpectedly large result?
Your wording tends to imply that avoiding junk will result in “good” and small results.

[Lenormju]

To my understanding, if "junk" did not exist, diffs would be more "minimal", but less pleasing to humans. Junk is an heuristic by Tim to produce better looking diffs for humans (and also being more efficient at doing so).
So I think my implication is true.
But is it the only case ? I ran some experiments, and there is a bias (not a general rule): setting junk tends to produce bigger diffs. But it definitely enables the pathological ones (when the algo has nothing to grasp on, as nearly every item is considered junk).
Setting autojunk=False and isjunk=None, to disable all junk behavior, will cause diffs to be closer to the lower bound possible of the Ratcliff–Obershelp algorithm, but the results would not be as nice to humans (cf the private volatile example here : #80136 (comment)). "good" is subjective. It depends on what you want. Quoting my current wording:

[junk] can produce better results for humans [...] But it can also cause pathological cases [...] unexpectedly large (but correct) diff result

So yes:

avoiding junk will result in “good” and small results

... just not for humans, and less efficiently.

[encukou]

What do you think about making this an introduction to the difflib module, rather than docs for the SequenceMatcher class (which is documented properly below)?

Something like this, plus dedenting it:

All functionality in this module uses the algorithm implemented in
:class:`SequenceMatcher`, a flexible class for comparing pairs
of sequences of any type, so long […]

[Lenormju]

I agree, because in the end everything relies on it. But can we do that in another PR, iteratively ?