From 7dafbe81bd0afb8bd67bc3a4c851a6c728fd87fe Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Wed, 7 Aug 2019 08:39:47 -0700
Subject: [PATCH] bpo-37004: Documented asymmetry of string arguments in
 difflib.SequenceMatcher for ratio method (GH-13482) (#15158)

https://bugs.python.org/issue37004
(cherry picked from commit e9cbcd0018abd2a5f2348c45d5c9c4265c4f42dc)

Co-authored-by: sweeneyde <36520290+sweeneyde@users.noreply.github.com>
---
 Doc/library/difflib.rst                                | 10 ++++++++++
 .../2019-05-22-04-30-07.bpo-37004.BRgxrt.rst           |  1 +
 2 files changed, 11 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Documentation/2019-05-22-04-30-07.bpo-37004.BRgxrt.rst

diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
index f044cb2d6e0..e245ab81cfb 100644
--- 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
new file mode 100644
index 00000000000..dfc8b7ed74c
--- /dev/null
+++ 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.
\ No newline at end of file