textual.command

This module contains classes for working with Textual's command palette.

See the guide on the Command Palette for full details.

Hits module-attribute

Hits = AsyncIterator['DiscoveryHit | Hit']

Return type for the command provider's search method.

ProviderSource module-attribute

ProviderSource = "Iterable[type[Provider] | Callable[[], type[Provider]]]"

The type used to declare the providers for a CommandPalette.

Command

Command(prompt, hit, id=None, disabled=False)

Bases: Option

Class that holds a hit in the CommandList.

Parameters:

Name	Type	Description	Default
prompt	VisualType	The prompt for the option.	required
hit	DiscoveryHit | Hit	The details of the hit 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

hit instance-attribute

hit = hit

The details of the hit associated with the option.

CommandInput

CommandInput(
    value=None,
    placeholder="",
    highlighter=None,
    password=False,
    *,
    restrict=None,
    type="text",
    max_length=0,
    suggester=None,
    validators=None,
    validate_on=None,
    valid_empty=False,
    name=None,
    id=None,
    classes=None,
    disabled=False,
    tooltip=None
)

Bases: Input

The command palette input control.

Parameters:

Name	Type	Description	Default
value	str | None	An optional default value for the input.	None
placeholder	str	Optional placeholder text for the input.	''
highlighter	Highlighter | None	An optional highlighter for the input.	None
password	bool	Flag to say if the field should obfuscate its content.	False
restrict	str | None	A regex to restrict character inputs.	None
type	InputType	The type of the input.	'text'
max_length	int	The maximum length of the input, or 0 for no maximum length.	0
suggester	Suggester | None	Suggester associated with this input instance.	None
validators	Validator | Iterable[Validator] | None	An iterable of validators that the Input value will be checked against.	None
validate_on	Iterable[InputValidationOn] | None	Zero or more of the values "blur", "changed", and "submitted", which determine when to do input validation. The default is to do validation for all messages.	None
valid_empty	bool	Empty values are valid.	False
name	str | None	Optional name for the input widget.	None
id	str | None	Optional ID for the widget.	None
classes	str | None	Optional initial classes for the widget.	None
disabled	bool	Whether the input is disabled or not.	False
tooltip	RenderableType | None	Optional tooltip.	None

CommandList

CommandList(
    *content,
    name=None,
    id=None,
    classes=None,
    disabled=False,
    wrap=True,
    tooltip=None,
)

Bases: OptionList

The command palette command list.

CommandPalette

CommandPalette(
    providers=None,
    *,
    placeholder="Search for commands…",
    name=None,
    id=None,
    classes=None
)

Bases: SystemModalScreen[None]

The Textual command palette.

Parameters:

Name	Type	Description	Default
providers	ProviderSource | None	An optional list of providers to use. If None, the providers supplied in the App or Screen will be used.	None
placeholder	str	The placeholder text for the command palette.	'Search for commands…'

BINDINGS class-attribute

BINDINGS = [
    Binding(
        "ctrl+end, shift+end",
        "command_list('last')",
        "Go to bottom",
        show=False,
    ),
    Binding(
        "ctrl+home, shift+home",
        "command_list('first')",
        "Go to top",
        show=False,
    ),
    Binding(
        "down", "cursor_down", "Next command", show=False
    ),
    Binding("escape", "escape", "Exit the command palette"),
    Binding(
        "pagedown",
        "command_list('page_down')",
        "Next page",
        show=False,
    ),
    Binding(
        "pageup",
        "command_list('page_up')",
        "Previous page",
        show=False,
    ),
    Binding(
        "up",
        "command_list('cursor_up')",
        "Previous command",
        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 = {
    "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 = 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.

Closed dataclass

Closed(option_selected)

Bases: Message

Posted to App when the command palette is closed.

option_selected instance-attribute

option_selected

True if an option was selected, False if the palette was closed without selecting an option.

Opened dataclass

Opened()

Bases: Message

Posted to App when the command palette is opened.

OptionHighlighted dataclass

OptionHighlighted(highlighted_event)

Bases: Message

Posted to App when an option is highlighted in the command palette.

highlighted_event instance-attribute

highlighted_event

The option highlighted event from the OptionList within the command palette.

is_open staticmethod

is_open(app)

Is a command palette current open?

Parameters:

Name	Type	Description	Default
app	App[object]	The app to test.	required

Returns:

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

DiscoveryHit dataclass

DiscoveryHit(display, command, text=None, help=None)

Holds the details of a single command search hit.

command instance-attribute

command

The function to call when the command is chosen.

display instance-attribute

display

A string or Rich renderable representation of the hit.

help class-attribute instance-attribute

help = None

Optional help text for the command.

prompt property

prompt

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

score property

score

A discovery hit always has a score of 0.

The order in which discovery hits are displayed is determined by the order in which they are yielded by the Provider. It's up to the developer to yield DiscoveryHits in the .

text class-attribute instance-attribute

text = 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 dataclass

Hit(score, match_display, command, text=None, help=None)

Holds the details of a single command search hit.

command instance-attribute

command

The function to call when the command is chosen.

help class-attribute instance-attribute

help = None

Optional help text for the command.

match_display instance-attribute

match_display

A string or Rich renderable representation of the hit.

prompt property

prompt

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

score instance-attribute

score

The score of the command hit.

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

text class-attribute instance-attribute

text = 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

Matcher(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

Is this matcher case sensitive?

match_style property

match_style

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

query property

query

The query string to look for.

query_pattern property

query_pattern

The regular expression pattern built from the query.

highlight

highlight(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

match(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

Provider(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

A reference to the application.

focused property

focused

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

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

screen property

screen

The currently-active screen in the application.

discover async

discover()

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

matcher(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 abstractmethod async

search(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

shutdown()

Called when the Provider is shutdown.

Use this method to perform an cleanup, if required.

startup async

startup()

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

SearchIcon

SearchIcon(
    content="",
    *,
    expand=False,
    shrink=False,
    markup=True,
    name=None,
    id=None,
    classes=None,
    disabled=False
)

Bases: Static

Widget for displaying a search icon before the command input.

icon class-attribute instance-attribute

icon = var('🔎')

The icon to display.

SimpleCommand

Bases: NamedTuple

A simple command.

callback instance-attribute

callback

The callback to invoke when the command is selected.

help_text class-attribute instance-attribute

help_text = None

The description of the command.

name instance-attribute

name

The name of the command.

SimpleProvider

SimpleProvider(screen, commands)

Bases: Provider

A simple provider which the caller can pass commands to.

discover async

discover()

Handle a request for the discovery commands for this provider.

Yields:

Type	Description
Hits	Commands that can be discovered.