Skip to content

textual

The root Textual module.

Exposes some commonly used symbols.

log module-attribute

log = Logger(None)

Global logger that logs to the currently active app.

Example
from textual import log
log(locals())

Logger

Logger(
    log_callable,
    group=LogGroup.INFO,
    verbosity=LogVerbosity.NORMAL,
)

A logger class that logs to the Textual console.

debug property

debug: Logger

Logs debug messages.

error property

error: Logger

Logs errors.

event property

event: Logger

Logs events.

info property

info: Logger

Logs information.

logging property

logging: Logger

Logs from stdlib logging module.

system property

system: Logger

Logs system information.

verbose property

verbose: Logger

A verbose logger.

warning property

warning: Logger

Logs warnings.

worker property

worker: Logger

Logs worker information.

verbosity

verbosity(verbose)

Get a new logger with selective verbosity.

Parameters:

Name Type Description Default
verbose bool

True to use HIGH verbosity, otherwise NORMAL.

required

Returns:

Type Description
Logger

New logger.

LoggerError

Bases: Exception

Raised when the logger failed.

on

on(message_type, selector=None, **kwargs)

Decorator to declare that the method is a message handler.

The decorator accepts an optional CSS selector that will be matched against a widget exposed by a control property on the message.

Example
# Handle the press of buttons with ID "#quit".
@on(Button.Pressed, "#quit")
def quit_button(self) -> None:
    self.app.quit()

Keyword arguments can be used to match additional selectors for attributes listed in ALLOW_SELECTOR_MATCH.

Example
# Handle the activation of the tab "#home" within the `TabbedContent` "#tabs".
@on(TabbedContent.TabActivated, "#tabs", pane="#home")
def switch_to_home(self) -> None:
    self.log("Switching back to the home tab.")
    ...

Parameters:

Name Type Description Default
message_type type[Message]

The message type (i.e. the class).

required
selector str | None

An optional selector. If supplied, the handler will only be called if selector matches the widget from the control attribute of the message.

None
**kwargs str

Additional selectors for other attributes of the message.

{}

work

work(
    method=None,
    *,
    name="",
    group="default",
    exit_on_error=True,
    exclusive=False,
    description=None,
    thread=False
)

A decorator used to create workers.

Parameters:

Name Type Description Default
method Callable[FactoryParamSpec, ReturnType] | Callable[FactoryParamSpec, Coroutine[None, None, ReturnType]] | None

A function or coroutine.

None
name str

A short string to identify the worker (in logs and debugging).

''
group str

A short string to identify a group of workers.

'default'
exit_on_error bool

Exit the app if the worker raises an error. Set to False to suppress exceptions.

True
exclusive bool

Cancel all workers in the same group.

False
description str | None

Readable description of the worker for debugging purposes. By default, it uses a string representation of the decorated method and its arguments.

None
thread bool

Mark the method as a thread worker.

False