Command

The Textual command palette.

See the guide on the Command Palette for full details.

Hits module-attribute

Hits: TypeAlias = AsyncIterator['DiscoveryHit | Hit']

Return type for the command provider's search method.

Command class

def __init__(self, prompt, command, id=None, disabled=False):

Bases: Option

Class that holds a command in the CommandList.

Parameters

Parameter	Default	Description
prompt RenderableType	required	The prompt for the option.
command DiscoveryHit | Hit	required	The details of the command associated with the option.
id str | None	None	The optional ID for the option.
disabled bool	False	The initial enabled/disabled state. Enabled by default.

command instance-attribute

command = command

The details of the command associated with the option.

CommandInput class

Bases: Input

The command palette input control.

CommandList class

Bases: OptionList

The command palette command list.

CommandPalette class

def __init__(self):

Bases: _SystemModalScreen[CallbackType]

The Textual command palette.

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
    Binding(
        "ctrl+end, shift+end",
        "command_list('last')",
        show=False,
    ),
    Binding(
        "ctrl+home, shift+home",
        "command_list('first')",
        show=False,
    ),
    Binding("down", "cursor_down", show=False),
    Binding("escape", "escape", "Exit the command palette"),
    Binding(
        "pagedown", "command_list('page_down')", show=False
    ),
    Binding(
        "pageup", "command_list('page_up')", show=False
    ),
    Binding("up", "command_list('cursor_up')", show=False),
]

Key(s)	Description
ctrl+end, shift+end	Jump to the last available commands.
ctrl+home, shift+home	Jump to the first available commands.
down	Navigate down through the available commands.
escape	Exit the command palette.
pagedown	Navigate down a page through the available commands.
pageup	Navigate up a page through the available commands.
up	Navigate up through the available commands.

COMPONENT_CLASSES class-attribute

COMPONENT_CLASSES: set[str] = {
    "command-palette--help-text",
    "command-palette--highlight",
}

Class	Description
command-palette--help-text	Targets the help text of a matched command.
command-palette--highlight	Targets the highlights of a matched command.

run_on_select class-attribute

run_on_select: bool = True

A flag to say if a command should be run when selected by the user.

If True then when a user hits Enter on a command match in the result list, or if they click on one with the mouse, the command will be selected and run. If set to False the input will be filled with the command and then Enter should be pressed on the keyboard or the 'go' button should be pressed.

is_open staticmethod

def is_open(app):

Is the command palette current open?

Parameters

Parameter	Default	Description
app App	required	The app to test.

Returns

Type	Description
bool	True if the command palette is currently open, False if not.

DiscoveryHit class

Holds the details of a single command search hit.

command instance-attribute

command: IgnoreReturnCallbackType

The function to call when the command is chosen.

display instance-attribute

display: RenderableType

A string or Rich renderable representation of the hit.

help instance-attribute class-attribute

help: str | None = None

Optional help text for the command.

prompt property

prompt: RenderableType

The prompt to use when displaying the discovery hit in the command palette.

text instance-attribute class-attribute

text: str | None = None

The command text associated with the hit, as plain text.

If display is not simple text, this attribute should be provided by the Provider object.

Hit class

Holds the details of a single command search hit.

command instance-attribute

command: IgnoreReturnCallbackType

The function to call when the command is chosen.

help instance-attribute class-attribute

help: str | None = None

Optional help text for the command.

match_display instance-attribute

match_display: RenderableType

A string or Rich renderable representation of the hit.

prompt property

prompt: RenderableType

The prompt to use when displaying the hit in the command palette.

score instance-attribute

score: float

The score of the command hit.

The value should be between 0 (no match) and 1 (complete match).

text instance-attribute class-attribute

text: str | None = None

The command text associated with the hit, as plain text.

If match_display is not simple text, this attribute should be provided by the Provider object.

Matcher class

def __init__(
    self, query, *, match_style=None, case_sensitive=False
):

A fuzzy matcher.

Parameters

Parameter	Default	Description
query str	required	A query as typed in by the user.
match_style Style | None	None	The style to use to highlight matched portions of a string.
case_sensitive bool	False	Should matching be case sensitive?

case_sensitive property

case_sensitive: bool

Is this matcher case sensitive?

match_style property

match_style: Style

The style that will be used to highlight hits in the matched text.

query property

query: str

The query string to look for.

query_pattern property

query_pattern: str

The regular expression pattern built from the query.

highlight method

def highlight(self, candidate):

Highlight the candidate with the fuzzy match.

Parameters

Parameter	Default	Description
candidate str	required	The candidate string to match against the query.

Returns

Type	Description
Text	A [rich.text.Text][Text] object with highlighted matches.

match method

def match(self, candidate):

Match the candidate against the query.

Parameters

Parameter	Default	Description
candidate str	required	Candidate string to match against the query.

Returns

Type	Description
float	Strength of the match from 0 to 1.

Provider class

def __init__(self, screen, match_style=None):

Bases: ABC

Base class for command palette command providers.

To create new command provider, inherit from this class and implement search.

Parameters

Parameter	Default	Description
screen Screen[Any]	required	A reference to the active screen.

app property

app: App[object]

A reference to the application.

focused property

focused: Widget | None

The currently-focused widget in the currently-active screen in the application.

If no widget has focus this will be None.

match_style property

match_style: Style | None

The preferred style to use when highlighting matching portions of the match_display.

screen property

screen: Screen[object]

The currently-active screen in the application.

discover async

def discover(self):

A default collection of hits for the provider.

Yields:

Type	Description
Hits	Instances of DiscoveryHit.

Note

This is different from search in that it should yield DiscoveryHits that should be shown by default (before user input).

It is permitted to not implement this method.

matcher method

def matcher(self, user_input, case_sensitive=False):

Create a fuzzy matcher for the given user input.

Parameters

Parameter	Default	Description
user_input str	required	The text that the user has input.
case_sensitive bool	False	Should matching be case sensitive?

Returns

Type	Description
Matcher	A fuzzy matcher object for matching against candidate hits.

search async abstractmethod

def search(self, query):

A request to search for commands relevant to the given query.

Parameters

Parameter	Default	Description
query str	required	The user input to be matched.

Yields:

Type	Description
Hits	Instances of Hit.

shutdown async

def shutdown(self):

Called when the Provider is shutdown.

Use this method to perform an cleanup, if required.

startup async

def startup(self):

Called after the Provider is initialized, but before any calls to search.

SearchIcon class

Bases: Static

Widget for displaying a search icon before the command input.

icon instance-attribute class-attribute

icon: var[str] = var('🔎')

The icon to display.