API Reference

fuzzyfinder.fuzzyfinder(input, collection, accessor=None, sort_results=True, ignore_case=True, highlight=False)[source]

Filter a collection of objects by fuzzy matching against an input string.

Parameters:

  • input (str) – A partial string which is typically entered by a user.

  • collection (Iterable[Any]) – An iterable of objects which will be filtered based on the input. If the objects are not strings, an appropriate accessor keyword argument must be passed.

  • accessor (Callable[[Any], str] | None) – If the collection is not an iterable of strings, then use the accessor to fetch the string that will be used for fuzzy matching. Defaults to the identity function (simply returns the argument it received as input).

  • sort_results (bool) – The suggestions are sorted by considering the smallest contiguous match, followed by where the match is found in the full string. If two suggestions have the same rank, they are then sorted alpha-numerically. This parameter controls the last tie-breaker-alpha-numeric sorting. The sorting based on match length and position will be intact. Defaults to True.

  • ignore_case (bool) – If this parameter is set to False, the filtering is case-sensitive. Defaults to True.

  • highlight (bool | str | Tuple[str, str]) – Highlight the matching substrings when printed to the terminal, or elsewhere. If True, when printed to the terminal, the matching substrings will have the default highlight (green). If this parameter is a str, when printed to the terminal, the matching substrings will be highlighted in the corresponding color. Accepted values are: 'red', 'green', 'yellow', 'blue', 'magenta', and 'cyan'. If this parameter is a tuple, it must be a 2-tuple consisting of a prefix and a suffix string. The prefix and suffix are prepended and appended to contiguous substring chunks, and can range from anything like parentheses or ANSI escape codes to HTML tags with class or style attributes. Defaults to False.

Returns:

A generator object that produces a list of suggestions narrowed down from collection using the input.

Return type:

Iterator[Any]

Example

>>> suggestions = fuzzyfinder('abc', ['acb', 'defabca', 'abcd', 'aagbec', 'xyz', 'qux'])
>>> list(suggestions)
['abcd', 'defabca', 'aagbec']