gh-88315: Add key argument to difflib.get_close_matches()

Doc/library/difflib.rst

@@ -316,11 +316,19 @@ Diff generation
    Setting the optional *autojunk* argument to ``False`` will turn
    :ref:`automatic junk heuristic <difflib-junk>` off.
 
+   Optional arg *key* (default ``None``) specifies a function of one argument that
+   is used to extract a comparison key from each element in *possibilities*
+   (for example, ``key=str.lower``). If the value is ``None``, the elements are
+   compared with *word* directly.
+
    The best (no more than *n*) matches among the possibilities are returned in a
    list, sorted by similarity score, most similar first.
 
       >>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
       ['apple', 'ape']
+      >>> get_close_matches("appel", [("aple", 9), ("peach", 8), ("puppy", 7)],
+      ...                   key=lambda x: x[0])
+      [('aple', 9)]
       >>> import keyword
       >>> get_close_matches('wheel', keyword.kwlist)
       ['while']

Lib/difflib.py

@@ -1,7 +1,7 @@
 """
 Module difflib -- helpers for computing deltas between objects.
 
-Function get_close_matches(word, possibilities, n=3, cutoff=0.6):
+Function get_close_matches(word, possibilities, n=3, cutoff=0.6, key=None):
     Use SequenceMatcher to return list of the best "good enough" matches.
 
 Function context_diff(a, b):
@@ -664,7 +664,8 @@ def real_quick_ratio(self):
     __class_getitem__ = classmethod(GenericAlias)
 
 
-def get_close_matches(word, possibilities, n=3, cutoff=0.6, *, autojunk=True):
+def get_close_matches(word, possibilities, n=3, cutoff=0.6, key=None, *,
+                      autojunk=True):
     """Use SequenceMatcher to return list of the best "good enough" matches.
 
     word is a sequence for which close matches are desired (typically a
@@ -679,11 +680,18 @@ def get_close_matches(word, possibilities, n=3, cutoff=0.6, *, autojunk=True):
     Optional arg cutoff (default 0.6) is a float in [0, 1].  Possibilities
     that don't score at least that similar to word are ignored.
 
+    Optional arg key specifies a function of one argument that is used to
+    extract a comparison key from each element in iterable (for example,
+    key=str.lower). The default value is None (compare the elements directly).
+
     The best (no more than n) matches among the possibilities are returned
     in a list, sorted by similarity score, most similar first.
 
     >>> get_close_matches("appel", ["ape", "apple", "peach", "puppy"])
     ['apple', 'ape']
+    >>> get_close_matches("appel", [("aple", 9), ("peach", 8), ("puppy", 7)],
+    ...                   key=lambda x: x[0])
+    [('aple', 9)]
     >>> import keyword as _keyword
     >>> get_close_matches("wheel", _keyword.kwlist)
     ['while']
@@ -701,7 +709,7 @@ def get_close_matches(word, possibilities, n=3, cutoff=0.6, *, autojunk=True):
     s = SequenceMatcher(autojunk=autojunk)
     s.set_seq2(word)
     for x in possibilities:
-        s.set_seq1(x)
+        s.set_seq1(key(x) if key is not None else x)
         if s.real_quick_ratio() < cutoff or s.quick_ratio() < cutoff:
             continue
 

Misc/NEWS.d/next/Library/2021-05-16-16-46-01.bpo-44149.2MUHbG.rst

@@ -0,0 +1 @@
+Add a ``key`` argument to :func:`difflib.get_close_matches`.