Rich log (#3046)

* log

* tests

* snapshot tests

* change to richlog

* keep raw lines

* disable highlighting by default

* simplify

* superfluous test

* optimization

* update cell length

* add refresh

* write method

* version bump

* doc fix link

* makes lines private

* docstring

* relax dev dependancy

* remove superfluous code [skip ci]

* added FAQ [skipci]

* fix code in faq [skipci]

* fix typo

* max lines fix

Author: willmcgugan

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.32.0] - 2023-08-03
+
+### Added
+
+- Added widgets.Log
+- Added Widget.is_vertical_scroll_end, Widget.is_horizontal_scroll_end, Widget.is_vertical_scrollbar_grabbed, Widget.is_horizontal_scrollbar_grabbed
+
+### Changed
+
+- Breaking change: Renamed TextLog to RichLog
+
 ## [0.31.0] - 2023-08-01
 
 ### Added

FAQ.md

@@ -7,8 +7,9 @@
 - [How can I select and copy text in a Textual app?](#how-can-i-select-and-copy-text-in-a-textual-app)
 - [How can I set a translucent app background?](#how-can-i-set-a-translucent-app-background)
 - [How do I center a widget in a screen?](#how-do-i-center-a-widget-in-a-screen)
-- [How do I fixed WorkerDeclarationError?](#how-do-i-fixed-workerdeclarationerror)
+- [How do I fix WorkerDeclarationError?](#how-do-i-fix-workerdeclarationerror)
 - [How do I pass arguments to an app?](#how-do-i-pass-arguments-to-an-app)
+- [No widget called TextLog](#no-widget-called-textlog)
 - [Why do some key combinations never make it to my app?](#why-do-some-key-combinations-never-make-it-to-my-app)
 - [Why doesn't Textual look good on macOS?](#why-doesn't-textual-look-good-on-macos)
 - [Why doesn't Textual support ANSI themes?](#why-doesn't-textual-support-ansi-themes)
@@ -145,8 +146,8 @@ if __name__ == "__main__":
     ButtonApp().run()
 ```
 
-<a name="how-do-i-fixed-workerdeclarationerror"></a>
-## How do I fixed WorkerDeclarationError?
+<a name="how-do-i-fix-workerdeclarationerror"></a>
+## How do I fix WorkerDeclarationError?
 
 Textual version 0.31.0 requires that you set `thread=True` on the `@work` decorator if you want to run a threaded worker.
 
@@ -158,15 +159,15 @@ def run_in_background():
     ...
 ```
 
-If you *don't* want a worker, you should make your work function `async`:
+If you *don't* want a threaded worker, you should make your work function `async`:
 
 ```python
-@work():
+@work()
 async def run_in_background():
     ...
 ```
 
-This change was made because it was easy to accidentally created a threaded worker, which may produce unexpected results.
+This change was made because it was too easy to accidentally create a threaded worker, which may produce unexpected results.
 
 <a name="how-do-i-pass-arguments-to-an-app"></a>
 ## How do I pass arguments to an app?
@@ -195,13 +196,26 @@ Then the app can be run, passing in various arguments; for example:
 # Running with default arguments.
 Greetings().run()
 
-# Running with a keyword arguyment.
+# Running with a keyword argument.
 Greetings(to_greet="davep").run()
 
 # Running with both positional arguments.
 Greetings("Well hello", "there").run()
 ```
 
+<a name="no-widget-called-textlog"></a>
+## No widget called TextLog
+
+The `TextLog` widget was renamed to `RichLog` in Textual 0.32.0.
+You will need to replace all references to `TextLog` in your code, with `RichLog`.
+Most IDEs will have a search and replace function which will help you do this.
+
+Here's how you should import RichLog:
+
+```python
+from textual.widgets import RichLog
+```
+
 <a name="why-do-some-key-combinations-never-make-it-to-my-app"></a>
 ## Why do some key combinations never make it to my app?
 

docs/examples/guide/input/key01.py

@@ -1,16 +1,16 @@
-from textual.app import App, ComposeResult
-from textual.widgets import TextLog
 from textual import events
+from textual.app import App, ComposeResult
+from textual.widgets import RichLog
 
 
 class InputApp(App):
     """App to display key events."""
 
     def compose(self) -> ComposeResult:
-        yield TextLog()
+        yield RichLog()
 
     def on_key(self, event: events.Key) -> None:
-        self.query_one(TextLog).write(event)
+        self.query_one(RichLog).write(event)
 
 
 if __name__ == "__main__":

docs/examples/guide/input/key02.py

@@ -1,16 +1,16 @@
-from textual.app import App, ComposeResult
-from textual.widgets import TextLog
 from textual import events
+from textual.app import App, ComposeResult
+from textual.widgets import RichLog
 
 
 class InputApp(App):
     """App to display key events."""
 
     def compose(self) -> ComposeResult:
-        yield TextLog()
+        yield RichLog()
 
     def on_key(self, event: events.Key) -> None:
-        self.query_one(TextLog).write(event)
+        self.query_one(RichLog).write(event)
 
     def key_space(self) -> None:
         self.bell()

docs/examples/guide/input/key03.py

@@ -1,9 +1,9 @@
-from textual.app import App, ComposeResult
-from textual.widgets import TextLog
 from textual import events
+from textual.app import App, ComposeResult
+from textual.widgets import RichLog
 
 
-class KeyLogger(TextLog):
+class KeyLogger(RichLog):
     def on_key(self, event: events.Key) -> None:
         self.write(event)
 

docs/examples/guide/input/mouse01.py

@@ -1,15 +1,15 @@
 from textual import events
 from textual.app import App, ComposeResult
 from textual.containers import Container
-from textual.widgets import Static, TextLog
+from textual.widgets import RichLog, Static
 
 
 class PlayArea(Container):
     def on_mount(self) -> None:
         self.capture_mouse()
 
     def on_mouse_move(self, event: events.MouseMove) -> None:
-        self.screen.query_one(TextLog).write(event)
+        self.screen.query_one(RichLog).write(event)
         self.query_one(Ball).offset = event.offset - (8, 2)
 
 
@@ -21,7 +21,7 @@ class MouseApp(App):
     CSS_PATH = "mouse01.css"
 
     def compose(self) -> ComposeResult:
-        yield TextLog()
+        yield RichLog()
         yield PlayArea(Ball("Textual"))
 
 

docs/examples/guide/reactivity/validate01.py

@@ -1,7 +1,7 @@
 from textual.app import App, ComposeResult
 from textual.containers import Horizontal
 from textual.reactive import reactive
-from textual.widgets import Button, TextLog
+from textual.widgets import Button, RichLog
 
 
 class ValidateApp(App):
@@ -23,14 +23,14 @@ def compose(self) -> ComposeResult:
             Button("-1", id="minus", variant="error"),
             id="buttons",
         )
-        yield TextLog(highlight=True)
+        yield RichLog(highlight=True)
 
     def on_button_pressed(self, event: Button.Pressed) -> None:
         if event.button.id == "plus":
             self.count += 1
         else:
             self.count -= 1
-        self.query_one(TextLog).write(f"{self.count=}")
+        self.query_one(RichLog).write(f"{self.count=}")
 
 
 if __name__ == "__main__":

docs/examples/widgets/log.py

@@ -0,0 +1,28 @@
+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()

docs/examples/widgets/text_log.py renamed to docs/examples/widgets/rich_log.py

@@ -1,13 +1,12 @@
 import csv
 import io
 
-from rich.table import Table
 from rich.syntax import Syntax
+from rich.table import Table
 
-from textual.app import App, ComposeResult
 from textual import events
-from textual.widgets import TextLog
-
+from textual.app import App, ComposeResult
+from textual.widgets import RichLog
 
 CSV = """lane,swimmer,country,time
 4,Joseph Schooling,Singapore,50.39
@@ -37,13 +36,13 @@ def loop_first_last(values: Iterable[T]) -> Iterable[tuple[bool, bool, T]]:
 '''
 
 
-class TextLogApp(App):
+class RichLogApp(App):
     def compose(self) -> ComposeResult:
-        yield TextLog(highlight=True, markup=True)
+        yield RichLog(highlight=True, markup=True)
 
     def on_ready(self) -> None:
         """Called  when the DOM is ready."""
-        text_log = self.query_one(TextLog)
+        text_log = self.query_one(RichLog)
 
         text_log.write(Syntax(CODE, "python", indent_guides=True))
 
@@ -57,10 +56,10 @@ def on_ready(self) -> None:
 
     def on_key(self, event: events.Key) -> None:
         """Write Key events to log."""
-        text_log = self.query_one(TextLog)
+        text_log = self.query_one(RichLog)
         text_log.write(event)
 
 
 if __name__ == "__main__":
-    app = TextLogApp()
+    app = RichLogApp()
     app.run()

docs/guide/input.md

@@ -23,7 +23,7 @@ The most fundamental way to receive input is via [Key][textual.events.Key] event
     ```{.textual path="docs/examples/guide/input/key01.py", press="T,e,x,t,u,a,l,!"}
     ```
 
-When you press a key, the app will receive the event and write it to a [TextLog](../widgets/text_log.md) widget. Try pressing a few keys to see what happens.
+When you press a key, the app will receive the event and write it to a [RichLog](../widgets/rich_log.md) widget. Try pressing a few keys to see what happens.
 
 !!! tip
 
@@ -105,7 +105,7 @@ The following example shows how focus works in practice.
     ```{.textual path="docs/examples/guide/input/key03.py", press="H,e,l,l,o,tab,W,o,r,l,d,!"}
     ```
 
-The app splits the screen in to quarters, with a `TextLog` widget in each quarter. If you click any of the text logs, you should see that it is highlighted to show that the widget has focus. Key events will be sent to the focused widget only.
+The app splits the screen in to quarters, with a `RichLog` widget in each quarter. If you click any of the text logs, you should see that it is highlighted to show that the widget has focus. Key events will be sent to the focused widget only.
 
 !!! tip