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=INFO, verbosity=NORMAL)

A logger class that logs to the Textual console.

debug property

debug

Logs debug messages.

error property

error

Logs errors.

event property

event

Logs events.

info property

info

Logs information.

logging property

logging

Logs from stdlib logging module.

system property

system

Logs system information.

verbose property

verbose

A verbose logger.

warning property

warning

Logs warnings.

worker property

worker

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: Callable[
        FactoryParamSpec, Coroutine[None, None, ReturnType]
    ],
    *,
    name: str = "",
    group: str = "default",
    exit_on_error: bool = True,
    exclusive: bool = False,
    description: str | None = None,
    thread: bool = False
) -> Callable[FactoryParamSpec, "Worker[ReturnType]"]

work(
    method: Callable[FactoryParamSpec, ReturnType],
    *,
    name: str = "",
    group: str = "default",
    exit_on_error: bool = True,
    exclusive: bool = False,
    description: str | None = None,
    thread: bool = False
) -> Callable[FactoryParamSpec, "Worker[ReturnType]"]

work(
    *,
    name: str = "",
    group: str = "default",
    exit_on_error: bool = True,
    exclusive: bool = False,
    description: str | None = None,
    thread: bool = False
) -> Decorator[..., ReturnType]

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