Command

The Textual command palette.

See the guide on the Command Palette for full details.

Hits module-attribute

Hits: TypeAlias = AsyncIterator[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

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

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: ModalScreen[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

Name	Type	Description	Default
app	App	The app to test.	required

Returns

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

on_mount method

def on_mount(self, _):

Capture the calling screen.

on_unmount async

def on_unmount(self):

Shutdown providers when command palette is closed.

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 class-attribute instance-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.

score instance-attribute

score: float

The score of the command hit.

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

text class-attribute instance-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

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

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

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

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

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

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

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

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.

matcher method

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

Create a fuzzy matcher for the given user input.

Parameters

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

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

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

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 class-attribute instance-attribute

icon: var[str] = var(
    Emoji.replace(":magnifying_glass_tilted_right:")
)

The icon to display.