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.


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 = 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

Number of lines of content.

lines property

lines

The raw lines in the Log.

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 = max_lines

Maximum number of lines to show

clear

clear()

Clear the Log.

Returns:

Type Description
Self

The Log instance.

notify_style_update

notify_style_update()

Called by Textual when styles update.

refresh_lines

refresh_lines(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

write(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

write_line(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

write_lines(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.