Digits (#3073)

* Digits

* digits widget

* update requires str

* digits docs

* simplify

* tweak docs

* snapshot test

* change name

* simplify

* docs

* Update _digits.py superfluous import

* Update _digits.py docstring

* address review

* formatting

* Update tests/snapshot_tests/snapshot_apps/digits.py

Co-authored-by: Dave Pearson <davep@davep.org>

---------

Co-authored-by: Dave Pearson <davep@davep.org>

docs/examples/widgets/clock.py

@@ -0,0 +1,31 @@
+from datetime import datetime
+
+from textual.app import App, ComposeResult
+from textual.widgets import Digits
+
+
+class ClockApp(App):
+    CSS = """
+    Screen {
+        align: center middle;
+    }
+    #clock {
+        width: auto;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Digits("", id="clock")
+
+    def on_ready(self) -> None:
+        self.update_clock()
+        self.set_interval(1, self.update_clock)
+
+    def update_clock(self) -> None:
+        clock = datetime.now().time()
+        self.query_one(Digits).update(f"{clock:%T}")
+
+
+if __name__ == "__main__":
+    app = ClockApp()
+    app.run()

docs/examples/widgets/digits.py

@@ -0,0 +1,22 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Digits
+
+
+class DigitApp(App):
+    CSS = """
+    Screen {
+        align: center middle;
+    }
+    #pi {
+        border: double green;
+        width: auto;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Digits("3.141,592,653,5897", id="pi")
+
+
+if __name__ == "__main__":
+    app = DigitApp()
+    app.run()

docs/widget_gallery.md

@@ -52,6 +52,15 @@ A powerful data table, with configurable cursors.
 ```{.textual path="docs/examples/widgets/data_table.py"}
 ```
 
+## Digits
+
+Display numbers in tall characters.
+
+[Digits reference](./widgets/digits.md){ .md-button .md-button--primary }
+
+```{.textual path="docs/examples/widgets/digits.py"}
+```
+
 ## DirectoryTree
 
 A tree view of files and folders.

docs/widgets/digits.md

@@ -0,0 +1,66 @@
+# Digits
+
+!!! tip "Added in version 0.33.0"
+
+A widget to display numerical values in tall multi-line characters.
+
+The digits 0-9 are supported, in addition to the following characters `+`, `-`, `^`, `:`, and `×`.
+Other characters will be displayed in a regular size font.
+
+You can set the text to be displayed in the constructor, or call [`update()`][textual.widgets.Digits.update] to change the text after the widget has been mounted.
+
+!!! note "This widget will respect the [text-align](../styles/text_align.md) rule."
+
+- [ ] Focusable
+- [ ] Container
+
+
+## Example
+
+The following example displays a few digits of Pi:
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/digits.py"}
+    ```
+
+=== "digits.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/digits.py"
+    ```
+
+Here's another example which uses `Digits` to display the current time:
+
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/clock.py"}
+    ```
+
+=== "clock.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/clock.py"
+    ```
+
+## Reactive attributes
+
+This widget has no reactive attributes.
+
+## Bindings
+
+This widget has no bindings.
+
+## Component classes
+
+This widget has no component classes.
+
+
+
+---
+
+
+::: textual.widgets.Digits
+    options:
+      heading_level: 2