Skip to content

Log

Added in version 0.32.0

A Log widget displays lines of text which may be appended to in realtime.

Call Log.write_line to write a line at a time, or Log.write_lines to write multiple lines at once. Call Log.clear to clear the Log widget.

Tip

See also RichLog which can write more than just text, and supports a number of advanced features.

  • Focusable
  • Container

Example

The example below shows how to write text to a Log widget:

LogApp And when it has gone past, I will turn the inner eye to see its path. Where the fear has gone there will be nothing. Only I will remain. I must not fear. Fear is the mind-killer. Fear is the little-death that brings total obliteration. I will face my fear. I will permit it to pass over me and through me. And when it has gone past, I will turn the inner eye to see its path. Where the fear has gone there will be nothing. Only I will remain. I must not fear. Fear is the mind-killer. Fear is the little-death that brings total obliteration. I will face my fear. I will permit it to pass over me and through me. And when it has gone past, I will turn the inner eye to see its path. Where the fear has gone there will be nothing. Only I will remain.▄▄ I must not fear. Fear is the mind-killer. Fear is the little-death that brings total obliteration. I will face my fear. I will permit it to pass over me and through me. And when it has gone past, I will turn the inner eye to see its path. Where the fear has gone there will be nothing. Only I will remain.

from textual.app import App, ComposeResult
from textual.widgets import Log

TEXT = """I must not fear.
Fear is the mind-killer.
Fear is the little-death that brings total obliteration.
I will face my fear.
I will permit it to pass over me and through me.
And when it has gone past, I will turn the inner eye to see its path.
Where the fear has gone there will be nothing. Only I will remain."""


class LogApp(App):
    """An app with a simple log."""

    def compose(self) -> ComposeResult:
        yield Log()

    def on_ready(self) -> None:
        log = self.query_one(Log)
        log.write_line("Hello, World!")
        for _ in range(10):
            log.write_line(TEXT)


if __name__ == "__main__":
    app = LogApp()
    app.run()

Reactive Attributes

Name Type Default Description
max_lines int None Maximum number of lines in the log or None for no maximum.
auto_scroll bool False Scroll to end of log when new lines are added.

Messages

This widget posts no messages.

Bindings

This widget has no bindings.

Component Classes

This widget has no component classes.


textual.widgets.Log class

def __init__(
    self,
    highlight=False,
    max_lines=None,
    auto_scroll=True,
    name=None,
    id=None,
    classes=None,
    disabled=False,
):

Bases: ScrollView

A widget to log text.

Parameters
Name Type Description Default
highlight bool

Enable highlighting.

False
max_lines int | None

Maximum number of lines to display.

None
auto_scroll bool

Scroll to end on new lines.

True
name str | None

The name of the text log.

None
id str | None

The ID of the text log in the DOM.

None
classes str | None

The CSS classes of the text log.

None
disabled bool

Whether the text log is disabled or not.

False

auto_scroll class-attribute instance-attribute

auto_scroll: var[bool] = auto_scroll

Automatically scroll to new lines.

highlight instance-attribute

highlight = highlight

Enable highlighting.

highlighter instance-attribute

highlighter = ReprHighlighter()

The Rich Highlighter object to use, if highlight=True

line_count property

line_count: int

Number of lines of content.

lines property

lines: Sequence[str]

The raw lines in the TextLog.

Note that this attribute is read only. Changing the lines will not update the Log's contents.

max_lines class-attribute instance-attribute

max_lines: var[int | None] = max_lines

Maximum number of lines to show

clear method

def clear(self):

Clear the Log.

Returns
Type Description
Self

The Log instance.

notify_style_update method

def notify_style_update(self):

Called by Textual when styles update.

refresh_lines method

def refresh_lines(self, y_start, line_count=1):

Refresh one or more lines.

Parameters
Name Type Description Default
y_start int

First line to refresh.

required
line_count int

Total number of lines to refresh.

1

write method

def write(self, data, scroll_end=None):

Write to the log.

Parameters
Name Type Description Default
data str

Data to write.

required
scroll_end bool | None

Scroll to the end after writing, or None to use self.auto_scroll.

None
Returns
Type Description
Self

The Log instance.

write_line method

def write_line(self, line):

Write content on a new line.

Parameters
Name Type Description Default
line str

String to write to the log.

required
Returns
Type Description
Self

The Log instance.

write_lines method

def write_lines(self, lines, scroll_end=None):

Write an iterable of lines.

Parameters
Name Type Description Default
lines Iterable[str]

An iterable of strings to write.

required
scroll_end bool | None

Scroll to the end after writing, or None to use self.auto_scroll.

None
Returns
Type Description
Self

The Log instance.