FuzzyFinder

class curses_fzf.FuzzyFinder(multi: bool = False, title: str = 'ITEMS', query: str = '', display: Callable[[Any], str] = lambda item: ..., preselect: Callable[[Any, ScoringResult], bool] = lambda item, result: ..., preview: Callable[[window, ColorTheme, Any, ScoringResult], str] | None = None, score: Callable[[str, str], ScoringResult] = scoring_fzf, color_theme: ColorTheme | None = None, autoreturn: int = 0, min_items: int = 0, max_items: int = sys.maxsize, page_size: int = 10, preview_window_percentage: int = 40)[source]

FuzzyFinder is the main entry point for the library. Use find() to run the fuzzyfinder on a list of items and return the selection. It allows the user to filter a list of items based on a query entered in UI or preseeded in constructor.

Parameters:

multi (bool) – multi selection mode determines whether to allow selection of multiple items or not. Default is False.
title (str) – The title to display in the upper left corner of the main FuzzyFinder window. Default is "ITEMS".
query (str) – The initial query to preseed the interface with. Default is "". See query for more details.
display (Callable[[Any], str]) – display() function is used to convert an item to a string for display and matching purposes. Default is lambda item: str(item). See display() for more details.
preselect (Callable[[Any, ScoringResult], bool]) – preselect() is a function to determine if an item should be preselected in multi selection mode based on the item and its scoring result. Default is a function that always returns False. See preselect() for more details.
preview (Optional[Callable[[curses.window, ColorTheme, Any, ScoringResult], str]]) – Show a preview window if preview() function is provided. Default is None. See preview() for more details.
score (Callable[[str, str], ScoringResult]) – The score() function is used to calculate the score of an item from all_items list based on the current query and the display() string of the item. Default is scoring_fzf(). See score() for more details.
color_theme (Optional[ColorTheme]) – The color_theme to use for the interface, if None was given the default ColorTheme will be used. Default is None.
autoreturn (int) – If autoreturn is a positive integer, the FuzzyFinder will automatically return the items in filtered list without user input if the number of items in the filtered list matches the given number. If multi is False, the actual value of autoreturn is ignored and the FuzzyFinder will automatically return if there is exactly one item in the filtered list. Default is 0.
min_items (int) – The minimum number of selected items to return in multi selection mode. Below this threshold, the FuzzyFinder will not accept the selection on ENTER. Default is 0.
max_items (int) – The maximum number of selected items to return in multi selection mode. Above this threshold, the FuzzyFinder will not accept the selection on ENTER. Default is sys.maxsize.
page_size (int) – Number of items to move in filtered list when pressing PAGE_UP/PAGE_DOWN. Default is 10.
preview_window_percentage (int) – preview_window_percentage defines the width of the preview window as a percentage of the total width. Default is 40.

all_items: List[Any]: The original list of all items given by the user in find() method. This list will be filtered by query into filtered list.

autoreturn: int: If autoreturn is a positive integer, the FuzzyFinder will automatically return the items in filtered list without user input if the number of items in the filtered list matches the given number. If multi is False, the actual value of autoreturn is ignored and the FuzzyFinder will automatically return if there is exactly one item in the filtered list. Default is 0.

calculate_filtered() → None[source]

Calculate the filtered list of items from the all_items list based on the current query and score function.

This function will be called in each iteration of the main loop of FuzzyFinder before rendering the items.

color_theme: ColorTheme: The color_theme to use for the interface. If None was given in the constructor, the default ColorTheme will be used.

property cursor_items: int: The index of the cursor inside the filtered list of items. Use kb_move_items_cursor_absolute and kb_move_items_cursor_relative to update the cursor position.

property cursor_query: int: The index of the cursor inside the query string. Use kb_move_query_cursor_absolute and kb_move_query_cursor_relative to update the cursor position.

display: Callable[[Any], str]

display() function is used to convert an item to a string for display and matching purposes. Default is lambda item: str(item).

Parameters:: item (Any) – The item to convert to a string.
Returns:: The single-line string representation of the item.
Return type:: str

filtered: List[Tuple[Any, ScoringResult]]: The list of items filtered by the current query, each paired with its ScoringResult. This list is updated by calculate_filtered(), which is called in each iteration of the main loop before rendering the items.

find(items: List[Any], title: str | None = None, query: str | None = None) → List[Any][source]

Run the FuzzyFinder on the given list of items and return the selected item(s).

Parameters:

items (List[Any]) – The list of items to filter and select from. This list will be stored in all_items and filtered based on the query into filtered list.
title (Optional[str]) – The title to display in the upper left corner of the main FuzzyFinder window. Default is None, in which case the title given on constructor will be reused.
query (Optional[str]) – The initial query to preseed the interface with. Default is None, in which case the query given on constructor will be reused. See query for more details.

Returns:

The list of selected items.

Return type:

List[Any]

kb_abort_selection() → None[source]: keymap function: Abort the FuzzyFinder and raise the CursesFzfAborted exception.

kb_accept_selection() → None[source]: keymap function: Accept the current selection and return it. This will set return_selection_now to True.

kb_add_to_query(text: str, index: int = -1) → None[source]

keymap function: Add the given text to the query before the given index. Adjust the cursor_query cursor and reset the cursor_items cursor if necessary.

May raise CursesFzfIndexOutOfBounds if the given index is out of bounds.

Parameters:

text (str) – The text to add to the query string.
index (int) – The index before which to add the text in the query string. The default is -1, which means to add the text at the end of the query string. The index may also be negative, in which case it will be counted from the end of the string (e.g. -1 means before the last character, -2 means before the second last character, etc.).

kb_add_to_query_cursor(text: str) → None[source]

keymap function: Add the given text to the query at the current cursor_query cursor position. Adjust the cursor_query cursor and reset the cursor_items cursor if necessary.

Parameters:: text (str) – The text to add to the query string.

kb_deselect_all() → None[source]: keymap function: Deselect all items from the current filtered list (only in multi mode).

kb_move_items_cursor_absolute(position: int) → None[source]

keymap function: Move the cursor_items cursor to the absolute position inside the filtered list while keeping it within bounds of the list.

Parameters:: position (int) – The absolute index inside the filtered list to move the cursor to.

kb_move_items_cursor_relative(offset: int) → None[source]

keymap function: Move the cursor_items cursor by offset while keeping it within bounds of the filtered list.

Parameters:: offset (int) – The relative offset to move the cursor by inside the filtered list. Negative values will move the cursor up, positive values will move it down.

kb_move_query_cursor_absolute(position: int) → None[source]

keymap function: Move the cursor_query cursor to the absolute position inside the query string while keeping it within bounds of the string.

Parameters:: position (int) – The absolute index inside the query string to move the cursor to.

kb_move_query_cursor_relative(offset: int) → None[source]

keymap function: Move the cursor_query cursor by offset while keeping it within bounds of the query string.

Parameters:: offset (int) – The relative offset to move the cursor by inside the query string. Negative values will move the cursor left, positive values will move it right.

kb_remove_from_query(index: int = -1, length: int = 1) → None[source]

keymap function: Remove length characters from the query at position index and return the cursor_items cursor to index 0. The cursor_query cursor will be adjusted if it is after the remove index.

Parameters:

index (int) – The index at which to remove characters from the query string. The default is -1, which means to remove the character before the end of the query string. The index may also be negative, in which case it will be counted from the end of the string (e.g. -1 means the last character, -2 means the second last character, etc.).
length (int) – The number of characters to remove from the query string starting from the given index. The default is 1. The length may be higher than the actual length of the query, but not negative.

kb_remove_from_query_cursor(before: bool = True) → None[source]

keymap function: Remove one character from the query before cursor_query cursor position and return the cursor_items cursor to index 0. The cursor_query cursor will be adjusted.

Parameters:: before (bool) – Whether to remove the character before the query cursor (like BACKSPACE) or the character at the query cursor (like DEL). Default is True.

kb_reset_query() → None[source]: keymap function: Clear the query string and return the cursor_query and cursor_items cursor to index 0.

kb_select_all() → None[source]: keymap function: Select all items from the current filtered list (only in multi mode).

kb_show_help() → None[source]: keymap function: Show the help screen, using F1 key.

kb_toggle_preview() → None[source]: keymap function: Toggle the visibility of the show_preview() window. This will toggle the show_preview boolean.

kb_toggle_selection() → None[source]: keymap function: Toggle the selection state of the current item (only in multi mode). This will add/remove the item to/from selected list.

keymap

Dictionary mapping keys (e.g. curses.KEY_UP) to their corresponding keybinding functions (e.g. lambda: self.kb_move_items_cursor_relative(-1)). If the target function takes no arguments, it can be directly assigned like curses.KEY_F1: self.kb_show_help.

All the functions starting with kb_ are keybinding functions that are used in the keymap and can also be reassigned or called directly.

max_items: int: The maximum number of selected items to return in multi selection mode. Above this threshold, the FuzzyFinder will not accept the selection on ENTER. Default is sys.maxsize.

min_items: int: The minimum number of selected items to return in multi selection mode. Below this threshold, the FuzzyFinder will not accept the selection on ENTER. Default is 0.

multi: bool: multi selection mode determines whether to allow selection of multiple items or not. Default is False.

page_size: int: Number of items to move in filtered list when pressing PAGE_UP/PAGE_DOWN. Default is 10.

preselect: Callable[[Any, ScoringResult], bool]

preselect() is a function to determine if an item should be preselected in multi selection mode based on the item and its scoring result. Default is a function that always returns False.

Parameters:

item (Any) – The item from filtered list to determine the preselection for.
scoring_result (ScoringResult) – The ScoringResult of the item based on the current query.

Returns:

Whether the item should be preselected or not.

Return type:

bool

preview: Callable[[window, ColorTheme, Any, ScoringResult], str] | None

If a preview() function is provided, a preview window will be shown for the currently highlighted item in the filtered list. preview_window_percentage defines the width of the preview window as a percentage of the total width. The preview window can be toggled with Ctrl+P.

The preview() function can be used in two ways:

If the function returns a non-empty string, it will be rendered line by line inside the preview window, honoring the available space. In this case the curses.window parameter can be ignored.
If the function returns an empty string, FuzzyFinder will assume that the user is handling the rendering of the preview window using the provided curses.window parameter. In this case the user needs to take care of window boundaries.

Parameters:

preview_window (curses.window) – The curses window to render the preview in.
color_theme (ColorTheme) – The color_theme of FuzzyFinder.
item (Any) – The item from filtered list to generate the preview for.
score_result (ScoringResult) – The ScoringResult of the item based on the current query.

Returns:

The text to render in the preview window, if it is non-empty.

Return type:

str

preview_window_percentage: int: preview_window_percentage defines the width of the preview window as a percentage of the total width. The default value is 40. The preview window will be placed on the right side of the screen if a preview() function is provided.

property query: str: The query entered by the user or preseeded on initialization. Setting this property will also reset the cursor_items cursor and move the cursor_query cursor to the end of the query.

return_selection_now: bool: Whether the FuzzyFinder should end the main loop and return the selected items. This will be set to True by kb_accept_selection() on ENTER.

score: Callable[[str, str], ScoringResult]

The score() function is used to calculate the score of an item from all_items list based on the current query and the display() string of the item. The score is used to sort the items in the filtered list and to determine which items match the query.

Default is scoring_fzf().

Parameters:

query (str) – The current query. This is the string that the user has entered to filter the items.
candidate (str) – The string representation of the item as returned by display(). This is the string that is used for matching and display purposes.

Returns:

The ScoringResult of the item.

Return type:

ScoringResult

selected: List[Any]: The list of currently selected items in multi selection mode. In single selection mode this list will be bypassed and the currently highlighted item in filtered list will be returned on ENTER.

show_preview: bool: Show or hide the preview window. This can be toggled with Ctrl+P if a preview() function is provided. It will be set by kb_toggle_preview().

stdscr: window | None: The main curses window, will be set automatically in FuzzyFinder’s main loop.

title: str: The title to display in the upper left corner of the main FuzzyFinder window. Default is "ITEMS".