Skip to content

Suggester

The Suggester class is used by the Input widget.

SuggestFromList class

def __init__(self, suggestions, *, case_sensitive=True):

Bases: Suggester

Give completion suggestions based on a fixed list of options.

Example
countries = ["England", "Scotland", "Portugal", "Spain", "France"]

class MyApp(App[None]):
    def compose(self) -> ComposeResult:
        yield Input(suggester=SuggestFromList(countries, case_sensitive=False))

If the user types P inside the input widget, a completion suggestion for "Portugal" appears.

Parameters
Parameter Default Description
suggestions
Iterable[str]
required

Valid suggestions sorted by decreasing priority.

case_sensitive
bool
True

Whether suggestions are computed in a case sensitive manner or not. The values provided in the argument suggestions represent the canonical representation of the completions and they will be suggested with that same casing.

get_suggestion async

def get_suggestion(self, value):

Gets a completion from the given possibilities.

Parameters
Parameter Default Description
value
str
required

The current value.

Returns
Type Description
str | None

A valid completion suggestion or None.

Suggester class

def __init__(self, *, use_cache=True, case_sensitive=False):

Bases: ABC

Defines how widgets generate completion suggestions.

To define a custom suggester, subclass Suggester and implement the async method get_suggestion. See SuggestFromList for an example.

Parameters
Parameter Default Description
use_cache
bool
True

Whether to cache suggestion results.

case_sensitive
bool
False

Whether suggestions are case sensitive or not. If they are not, incoming values are casefolded before generating the suggestion.

cache instance-attribute

cache: LRUCache[str, str | None] | None = (
    LRUCache(1024) if use_cache else None
)

Suggestion cache, if used.

get_suggestion abstractmethod async

def get_suggestion(self, value):

Try to get a completion suggestion for the given input value.

Custom suggesters should implement this method.

Note

The value argument will be casefolded if self.case_sensitive is False.

Note

If your implementation is not deterministic, you may need to disable caching.

Parameters
Parameter Default Description
value
str
required

The current value of the requester widget.

Returns
Type Description
str | None

A valid suggestion or None.

SuggestionReady class

Bases: Message

Sent when a completion suggestion is ready.

suggestion instance-attribute

suggestion: str

The string suggestion.

value instance-attribute

value: str

The value to which the suggestion is for.