Python TUIs with Textual, Rich & prompt_toolkit

from rich.console import Console

console = Console()                    # writes to stdout
err = Console(stderr=True)             # writes to stderr

console.print("[bold green]shelf[/] is ready")
console.log("catalogue loaded")        # adds a time column and the calling location
console.rule("Loans")

if console.is_terminal:                # True when attached to a terminal
    console.print("interactive session")

with console.status("Reading catalogue..."):    # spinner around a block of work
    pass

import sys

from rich import box
from rich.console import Console
from rich.markup import escape
from rich.table import Table
from rich.tree import Tree

BOOKS = [
    ("978-0-13-468599-1", "The Pragmatic Programmer", "Hunt and Thomas", 2019, None),
    ("978-0-262-03384-8", "Introduction to Algorithms", "Cormen et al.", 2009, "ana"),
    ("978-1-4919-5017-4", "Fluent Python", "Ramalho", 2022, None),
]


def list_books(console: Console) -> None:
    if not console.is_terminal:
        for isbn, title, author, year, borrower in BOOKS:
            print(isbn, title, author, year, borrower or "", sep="\t")
        return

    table = Table(title="Bookshelf", box=box.MINIMAL_DOUBLE_HEAD, row_styles=["dim", ""])
    table.add_column("ISBN", no_wrap=True)
    table.add_column("Title", style="magenta")
    table.add_column("Author")
    table.add_column("Year", justify="right", style="cyan")
    table.add_column("Status")
    for isbn, title, author, year, borrower in BOOKS:
        status = f"[yellow]on loan to {escape(borrower)}[/]" if borrower else "[green]available[/]"
        table.add_row(isbn, escape(title), escape(author), str(year), status)
    console.print(table)


def list_by_author(console: Console) -> None:
    tree = Tree("Bookshelf")
    for _, title, author, _, _ in BOOKS:
        tree.add(escape(author)).add(escape(title))
    console.print(tree)


if __name__ == "__main__":
    console = Console()
    list_books(console)
    if len(sys.argv) > 1 and sys.argv[1] == "--by-author":
        list_by_author(console)

import time

from rich.console import Console
from rich.live import Live
from rich.progress import (
    BarColumn,
    MofNCompleteColumn,
    Progress,
    SpinnerColumn,
    TextColumn,
    TimeRemainingColumn,
)
from rich.table import Table

console = Console(stderr=True)       # progress goes to stderr, results to stdout


def import_catalogue(paths: list[str]) -> None:
    with Progress(
        SpinnerColumn(),
        TextColumn("{task.description}"),
        BarColumn(),
        MofNCompleteColumn(),
        TimeRemainingColumn(),
        console=console,
        transient=True,                # remove the bar when the import is finished
    ) as progress:
        task = progress.add_task("Importing", total=len(paths))
        for path in paths:
            time.sleep(0.2)            # parse one file here
            progress.console.print(f"imported {path}")    # printed above the bar
            progress.advance(task)


def watch_loans() -> None:
    table = Table("ISBN", "Borrower")
    with Live(table, refresh_per_second=4, transient=True, console=console) as live:
        for isbn, borrower in [("978-0-13-468599-1", "ana"), ("978-1-4919-5017-4", "bo")]:
            time.sleep(0.4)
            table.add_row(isbn, borrower)
            live.update(table)

import logging

from rich.logging import RichHandler
from rich.traceback import install

install(show_locals=True)            # every uncaught exception is rendered by Rich

logging.basicConfig(
    level="INFO",
    format="%(message)s",
    datefmt="[%X]",
    handlers=[RichHandler(rich_tracebacks=True, markup=False)],
)

log = logging.getLogger("shelf")
log.info("catalogue loaded")

/* shelf.tcss */
Screen { layout: vertical; }

#search { dock: top; margin: 0 1; }

#main { height: 1fr; }

#catalogue { width: 2fr; }

#side { width: 1fr; }

#details { height: 1fr; border: round $primary; padding: 0 1; }

#loans { height: 1fr; }

LoanDialog { align: center middle; }

#dialog {
    width: 50;
    height: auto;
    padding: 1 2;
    border: thick $primary;
    background: $surface;
}

# shelf_tui.py
from __future__ import annotations

import sys
import time
from dataclasses import dataclass

from textual import on, work
from textual.app import App, ComposeResult
from textual.binding import Binding
from textual.containers import Horizontal, Vertical
from textual.markup import escape
from textual.message import Message
from textual.reactive import reactive
from textual.screen import ModalScreen
from textual.widgets import DataTable, Footer, Header, Input, Label, Static
from textual.worker import get_current_worker


@dataclass(frozen=True)
class Book:
    isbn: str
    title: str
    author: str
    year: int


def read_catalogue() -> list[Book]:
    """Blocking read; in the real tool this calls the same function as 'shelf list'."""
    time.sleep(0.3)
    return [
        Book("978-0-13-468599-1", "The Pragmatic Programmer", "Hunt and Thomas", 2019),
        Book("978-0-262-03384-8", "Introduction to Algorithms", "Cormen et al.", 2009),
        Book("978-1-4919-5017-4", "Fluent Python", "Ramalho", 2022),
    ]


class Catalogue(DataTable):
    """The list of books. Posts BookChosen when the user presses Enter on a row."""

    class BookChosen(Message):
        def __init__(self, isbn: str) -> None:
            super().__init__()
            self.isbn = isbn

    def on_mount(self) -> None:
        self.cursor_type = "row"
        self.zebra_stripes = True
        self.add_columns("Title", "Author", "Year")

    def show(self, books: list[Book]) -> None:
        self.clear()
        for book in books:
            self.add_row(book.title, book.author, str(book.year), key=book.isbn)

    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
        event.stop()                                  # do not let the App see the raw message
        if event.row_key.value is not None:
            self.post_message(self.BookChosen(event.row_key.value))


class Details(Static):
    """Shows the highlighted book; refreshes itself when 'book' changes."""

    book: reactive[Book | None] = reactive(None)

    def watch_book(self, book: Book | None) -> None:
        if book is None:
            self.update("Select a book")
        else:
            self.update(
                f"[b]{escape(book.title)}[/b]\n{escape(book.author)}, {book.year}\nISBN {book.isbn}"
            )


class LoanDialog(ModalScreen[str | None]):
    """Asks who borrows the book; dismisses with the name, or None when cancelled."""

    BINDINGS = [Binding("escape", "cancel", "Cancel")]

    def __init__(self, title: str) -> None:
        super().__init__()
        self.book_title = title

    def compose(self) -> ComposeResult:
        with Vertical(id="dialog"):
            yield Label(f"Loan: {escape(self.book_title)}")
            yield Input(placeholder="Borrower", id="borrower")

    @on(Input.Submitted, "#borrower")
    def submit(self, event: Input.Submitted) -> None:
        self.dismiss(event.value.strip() or None)

    def action_cancel(self) -> None:
        self.dismiss(None)


class ShelfApp(App[None]):
    CSS_PATH = "shelf.tcss"
    TITLE = "shelf"
    BINDINGS = [
        Binding("s", "focus_search", "Search"),
        Binding("l", "loan", "Loan"),
        Binding("r", "return_book", "Return"),
        Binding("f5", "reload", "Reload"),
    ]

    def __init__(self) -> None:
        super().__init__()
        self.books: list[Book] = []
        self.loans: dict[str, str] = {}

    def compose(self) -> ComposeResult:
        yield Header()
        yield Input(placeholder="Search title or author", id="search")
        with Horizontal(id="main"):
            yield Catalogue(id="catalogue")
            with Vertical(id="side"):
                yield Details(id="details")
                yield DataTable(id="loans", cursor_type="row")
        yield Footer()

    def on_mount(self) -> None:
        self.query_one("#loans", DataTable).add_columns("Title", "Borrower")
        self.query_one(Catalogue).focus()
        self.action_reload()

    # --- background work -------------------------------------------------
    def action_reload(self) -> None:
        self.load_books()

    @work(thread=True, exclusive=True, exit_on_error=False)
    def load_books(self) -> None:
        books = read_catalogue()                      # blocks, so it runs in a thread
        if not get_current_worker().is_cancelled:
            self.call_from_thread(self.set_books, books)

    def set_books(self, books: list[Book]) -> None:
        self.books = books
        self.apply_filter(self.query_one("#search", Input).value)

    # --- messages -------------------------------------------------------
    @on(Input.Changed, "#search")
    def search_changed(self, event: Input.Changed) -> None:
        self.apply_filter(event.value)

    def apply_filter(self, needle: str) -> None:
        needle = needle.casefold()
        shown = [b for b in self.books if needle in b.title.casefold() or needle in b.author.casefold()]
        self.query_one(Catalogue).show(shown)

    @on(DataTable.RowHighlighted, "#catalogue")
    def highlighted(self, event: DataTable.RowHighlighted) -> None:
        self.query_one(Details).book = self.find(event.row_key.value)

    def on_catalogue_book_chosen(self, message: Catalogue.BookChosen) -> None:
        self.query_one(Details).book = self.find(message.isbn)
        self.action_loan()

    def find(self, isbn: str | None) -> Book | None:
        return next((b for b in self.books if b.isbn == isbn), None)

    # --- actions ----------------------------------------------------------
    def action_focus_search(self) -> None:
        self.query_one("#search", Input).focus()

    def action_loan(self) -> None:
        book = self.query_one(Details).book
        if book is None or book.isbn in self.loans:
            self.bell()
            return

        def done(borrower: str | None) -> None:       # called when the dialog is dismissed
            if borrower:
                self.loans[book.isbn] = borrower
                self.refresh_loans()

        self.push_screen(LoanDialog(book.title), done)

    def action_return_book(self) -> None:
        book = self.query_one(Details).book
        if book is not None and self.loans.pop(book.isbn, None) is not None:
            self.refresh_loans()

    def refresh_loans(self) -> None:
        table = self.query_one("#loans", DataTable)
        table.clear()
        for isbn, borrower in self.loans.items():
            book = self.find(isbn)
            table.add_row(book.title if book else isbn, borrower, key=isbn)


if __name__ == "__main__":
    app = ShelfApp()
    app.run()
    sys.exit(app.return_code or 0)

from collections.abc import Iterable

from textual.app import App, SystemCommand
from textual.command import Hit, Hits, Provider
from textual.screen import Screen


class ShelfCommands(Provider):
    async def search(self, query: str) -> Hits:
        matcher = self.matcher(query)
        label = "Reload catalogue"
        score = matcher.match(label)
        if score > 0:
            yield Hit(score, matcher.highlight(label), self.app.action_reload, help="Read the books again")


class PaletteDemo(App):
    COMMANDS = App.COMMANDS | {ShelfCommands}

    def get_system_commands(self, screen: Screen) -> Iterable[SystemCommand]:
        yield from super().get_system_commands(screen)
        yield SystemCommand("Ring the bell", "Beep", self.bell)

python shelf_tui.py                      # full-screen application mode
textual run shelf_tui.py --dev           # same, with live CSS reload and devtools
textual serve shelf_tui.py               # serve the same app in a web browser

textual console                          # terminal 1: receives logs, print output and events
textual run --dev shelf_tui.py           # terminal 2: runs the app connected to the console
textual console -x EVENT -x SYSTEM       # hide message groups; -v is verbose, --port sets the port

# pytest.ini
[pytest]
asyncio_mode = auto

# test_shelf_tui.py
from textual.widgets import DataTable, Input

from shelf_tui import ShelfApp


async def test_search_filters_catalogue():
    app = ShelfApp()
    async with app.run_test(size=(100, 30)) as pilot:
        await pilot.pause(delay=0.5)               # the thread worker delivers the books
        table = app.query_one("#catalogue", DataTable)
        assert table.row_count == 3

        await pilot.press("s")                     # focus the search box
        await pilot.press("p", "y", "t", "h", "o", "n")
        await pilot.pause()
        assert app.query_one("#search", Input).value == "python"
        assert table.row_count == 0


async def test_loan_dialog_records_borrower():
    app = ShelfApp()
    async with app.run_test(size=(100, 30)) as pilot:
        await pilot.pause(delay=0.5)
        await pilot.press("l")                     # open the dialog for the highlighted book
        await pilot.press("a", "n", "a", "enter")
        await pilot.pause()
        assert list(app.loans.values()) == ["ana"]


def test_layout_snapshot(snap_compare):
    assert snap_compare("shelf_tui.py", terminal_size=(100, 30), press=["down"])

# shelf_repl.py
from pathlib import Path

from prompt_toolkit import PromptSession
from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
from prompt_toolkit.completion import FuzzyCompleter, WordCompleter
from prompt_toolkit.history import FileHistory

COMMANDS = ["list", "add", "loan", "return", "quit"]


def main() -> None:
    history_file = Path.home() / ".shelf_history"
    session = PromptSession(history=FileHistory(str(history_file)))
    completer = FuzzyCompleter(WordCompleter(COMMANDS))

    while True:
        try:
            line = session.prompt(
                "shelf> ",
                completer=completer,
                auto_suggest=AutoSuggestFromHistory(),
                bottom_toolbar=lambda: "Type 'quit' to leave",
            )
        except (EOFError, KeyboardInterrupt):      # Ctrl-D and Ctrl-C
            break
        if line.strip() == "quit":
            break
        print(f"you typed: {line}")


if __name__ == "__main__":
    main()

from prompt_toolkit import Application
from prompt_toolkit.buffer import Buffer
from prompt_toolkit.key_binding import KeyBindings
from prompt_toolkit.layout.containers import HSplit, VSplit, Window
from prompt_toolkit.layout.controls import BufferControl, FormattedTextControl
from prompt_toolkit.layout.layout import Layout

kb = KeyBindings()


@kb.add("c-q")
def _(event) -> None:
    event.app.exit()


root = HSplit([
    Window(height=1, content=FormattedTextControl(text="shelf -- Ctrl-Q quits")),
    VSplit([
        Window(content=BufferControl(buffer=Buffer())),                 # search box
        Window(width=1, char="|"),
        Window(content=FormattedTextControl(text="Fluent Python\nRamalho, 2022")),
    ]),
])

Application(layout=Layout(root), key_bindings=kb, full_screen=True).run()