bpo-37004: Documented asymmetry of string arguments in difflib.SequenceMatcher for ratio method (GH-13482) (#15158)

miss-islington · sweeneyde · terryjreedy · commit 7dafbe81bd0a · 2019-08-07T11:39:47.000-04:00
https://bugs.python.org/issue37004 (cherry picked from commit e9cbcd0) Co-authored-by: sweeneyde <36520290+sweeneyde@users.noreply.github.com>
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
@@ -543,6 +543,16 @@ The :class:`SequenceMatcher` class has this constructor:
       to try :meth:`quick_ratio` or :meth:`real_quick_ratio` first to get an
       upper bound.
 
+      .. note::
+
+         Caution: The result of a :meth:`ratio` call may depend on the order of
+         the arguments. For instance::
+
+            >>> SequenceMatcher(None, 'tide', 'diet').ratio()
+            0.25
+            >>> SequenceMatcher(None, 'diet', 'tide').ratio()
+            0.5
+
 
    .. method:: quick_ratio()
 
diff --git a/Misc/NEWS.d/next/Documentation/2019-05-22-04-30-07.bpo-37004.BRgxrt.rst b/Misc/NEWS.d/next/Documentation/2019-05-22-04-30-07.bpo-37004.BRgxrt.rst
@@ -0,0 +1 @@
+In the documentation for difflib, a note was added explicitly warning that the results of SequenceMatcher's ratio method may depend on the order of the input strings.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+In the documentation for difflib, a note was added explicitly warning that the results of SequenceMatcher's ratio method may depend on the order of the input strings.`