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.

[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 […]