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