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
Name Type Description Default
suggestions Iterable[str]

Valid suggestions sorted by decreasing priority.

required
case_sensitive bool

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.

True

get_suggestion async

def get_suggestion(self, value):

Gets a completion from the given possibilities.

Parameters
Name Type Description Default
value str

The current value.

required
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
Name Type Description Default
use_cache bool

Whether to cache suggestion results.

True
case_sensitive bool

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

False

cache instance-attribute

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

Suggestion cache, if used.

get_suggestion async abstractmethod

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
Name Type Description Default
value str

The current value of the requester widget.

required
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.