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.

textual.command

Hits module-attribute ¶

ProviderSource module-attribute ¶

Command ¶

prompt ¶

hit ¶

id ¶

disabled ¶

hit instance-attribute ¶

CommandInput ¶

value ¶

placeholder ¶

highlighter ¶

password ¶

restrict ¶

type ¶

max_length ¶

suggester ¶

validators ¶

validate_on ¶

valid_empty ¶

name ¶

id ¶

classes ¶

disabled ¶

tooltip ¶

CommandList ¶

CommandPalette ¶

providers ¶

placeholder ¶

BINDINGS class-attribute ¶

COMPONENT_CLASSES class-attribute ¶

run_on_select class-attribute ¶

Closed dataclass ¶

option_selected instance-attribute ¶

Opened dataclass ¶

OptionHighlighted dataclass ¶

highlighted_event instance-attribute ¶

is_open staticmethod ¶

app ¶

DiscoveryHit dataclass ¶

command instance-attribute ¶

display instance-attribute ¶

help class-attribute instance-attribute ¶

prompt property ¶

score property ¶

text class-attribute instance-attribute ¶

Hit dataclass ¶

command instance-attribute ¶

help class-attribute instance-attribute ¶

match_display instance-attribute ¶

prompt property ¶

score instance-attribute ¶

text class-attribute instance-attribute ¶

Matcher ¶

query ¶

match_style ¶

case_sensitive ¶

case_sensitive property ¶

match_style property ¶

query property ¶

query_pattern property ¶

highlight ¶

candidate ¶

match ¶

candidate ¶

Provider ¶

screen ¶

app property ¶

focused property ¶

match_style property ¶

screen property ¶

discover async ¶

matcher ¶

user_input ¶

case_sensitive ¶

search abstractmethod async ¶

query ¶

shutdown async ¶

startup async ¶

Hits `module-attribute` ¶

ProviderSource `module-attribute` ¶

`prompt` ¶

`hit` ¶

`id` ¶

`disabled` ¶

hit `instance-attribute` ¶

`value` ¶

`placeholder` ¶

`highlighter` ¶

`password` ¶

`restrict` ¶

`type` ¶

`max_length` ¶

`suggester` ¶

`validators` ¶

`validate_on` ¶

`valid_empty` ¶

`name` ¶

`id` ¶

`classes` ¶

`disabled` ¶

`tooltip` ¶

`providers` ¶

`placeholder` ¶

BINDINGS `class-attribute` ¶

COMPONENT_CLASSES `class-attribute` ¶

run_on_select `class-attribute` ¶

Closed `dataclass` ¶

option_selected `instance-attribute` ¶

Opened `dataclass` ¶

OptionHighlighted `dataclass` ¶

highlighted_event `instance-attribute` ¶

is_open `staticmethod` ¶

`app` ¶

DiscoveryHit `dataclass` ¶

command `instance-attribute` ¶

display `instance-attribute` ¶

help `class-attribute` `instance-attribute` ¶

prompt `property` ¶

score `property` ¶

text `class-attribute` `instance-attribute` ¶

Hit `dataclass` ¶

command `instance-attribute` ¶

help `class-attribute` `instance-attribute` ¶

match_display `instance-attribute` ¶

prompt `property` ¶

score `instance-attribute` ¶

text `class-attribute` `instance-attribute` ¶

`query` ¶

`match_style` ¶

`case_sensitive` ¶

case_sensitive `property` ¶

match_style `property` ¶

query `property` ¶

query_pattern `property` ¶

`candidate` ¶

`candidate` ¶

`screen` ¶

app `property` ¶

focused `property` ¶

match_style `property` ¶

screen `property` ¶

discover `async` ¶

`user_input` ¶

`case_sensitive` ¶

search `abstractmethod` `async` ¶

`query` ¶

shutdown `async` ¶

startup `async` ¶

icon `class-attribute` `instance-attribute` ¶

callback `instance-attribute` ¶

help_text `class-attribute` `instance-attribute` ¶

name `instance-attribute` ¶

discover `async` ¶