ScoringResult

class curses_fzf.ScoringResult(query: str, candidate: str)[source]

ScoringResult encapsules information and toolage to help with your own scoring functions.

The only important field is score, FuzzyFinder will take it into account when it decides which items to show and in which order. If it is 0 the element will not be displayed in FuzzyFinder.filtered list. Positive values will sort the items from high to low score.

The second field to notice is matches, which is a list of tuples containing the starting index of all matches inside the candidate string along with the matched substring. If set, this information will be used by FuzzyFinder to highlight the matched substrings in the FuzzyFinder.filtered list of query results.

The intended way to set those fields is add_match(). It adds the given score to ScoringResult.score and the given position and match as a tuple to ScoringResult.matches. However feel free to directly manipulate these fields as your scoring logic requires. Especially setting score to 0 is a common way to filter an item out of the results.

Parameters:
SEPARATORS: Set[str] = {'\t', ' ', '"', "'", '(', ')', ',', '-', '.', '/', ':', ';', '<', '>', '[', '\\', ']', '_', '`', '{', '|', '}'}

A set of characters that commonly indicate “word boundaries” in generic text and paths. Those are chosen similarly to fzf’s original heuristics.

add_match(position: int, match: str, score: int) → None[source]

Add position and match as a tuple to ScoringResult.matches. The given score is added to ScoringResult.score.

This is the intended way to add to the score and keep track of the matches, but feel free to directly manipulate these fields as your scoring logic requires. Especially setting score to 0 is a common way to filter an item out of the results.

Parameters:

  • position (int) – The starting index of the match in the original candidate string.

  • match (str) – The matched substring, starting at the given position.

  • score (int) – This value is added to ScoringResult.score.

candidate: str

The original candidate string parameter as given to the constructor. This is a single item’s display() representation from the FuzzyFinder.all_items list.

candidate_lower: str

The candidate string converted to lowercase.

candidate_words_with_index: List[Tuple[str, int]]

The candidate_lower string split on whitespaces. Each element is a tuple with the word and its starting index in the original candidate string.

check_query_empty() → bool[source]

Check if the query string is empty. If it is empty, the score is set to 100 to keep all items in the original order.

Returns:

True if the query string is empty,

False otherwise.

Return type:

bool

find_best_word_match(word: str) → Tuple[str, int, int, int] | None[source]

Find the best match for the given query word among the candidate_words_with_index. The best match is the one that is closest to a full word (highest percentage of the word matched). If multiple matches have the same percentage, the one with the match closer to the word’s beginning is preferred.

If a match is found, the index of the matched word in the candidate is added to ScoringResult._already_matched_words to prevent it from being matched again to another query word.

Parameters:

word (str) – The query word (an item from query_words_with_index) for which to find the best match among candidate_words_with_index.

Returns:

A tuple containing:

Returns None if no match was found at all.

Return type:

Optional[Tuple[str, int, int, int]]

greedy_match_positions() → List[int][source]

Find the positions of each single query characters in the candidate string using a greedy forward scan. This is a common first step in many fuzzy matching algorithms and can be used to quickly filter out candidates that don’t match at all or to get a baseline score for more complex scoring functions.

Returns:

A list of positions where the query characters match in

the candidate.

Return type:

List[int]

is_boundary(position: int) → bool[source]

Check if the given position in the candidate string is a boundary.

A boundary is defined as:

  • the beginning of the string

  • a position after a separator character (space, tab, slash, dash, dot, etc.)

  • a camelCase transition (lowercase followed by uppercase)

  • an alpha<->digit transition

Those criteria are chosen similarly to fzf’s original heuristics.

Parameters:

position (int) – The index in the candidate string to check.

Returns:

True if the position is a boundary, False otherwise.

Return type:

bool

matches: List[Tuple[int, str]]

A list of tuples representing each substring match of the query in the candidate string. The first tuple entry is the starting index of the match in the original candidate string. The second entry is the matched substring. The add_match() method is meant to add to matches, but feel free to directly manipulate this field as your scoring logic requires.

merge_positions_to_substrings(positions: List[int]) → List[Tuple[int, str]][source]

Convert matched character positions to (start, substring) tuples for add_match() or matches. Example: positions [3,4,5, 10,11] -> [(3, candidate[3:6]), (10, candidate[10:12])]

query: str

The original query string parameter as given to the constructor. This is the FuzzyFinder.query string entered by the user.

query_lower: str

The query string converted to lowercase.

query_words_with_index: List[Tuple[str, int]]

The query_lower string split on whitespaces. Each element is a tuple with the word and its starting index in the original query string.

score: int

The resulting fuzzy score. This is the field that FuzzyFinder will take into account when it decides which items to show. A score of 0 will filter the item out of the resulting FuzzyFinder.filtered list. Remaining items are sorted from high to low score. The add_match() method is meant to add to score, but feel free to directly manipulate this field as your scoring logic requires.