Building TUIs with Textual

whoami

Bill Melvin

• First programming language was BASIC
• Programming professionally since late 1980s
• Built systems using Pascal into late 2000s
  • Turbo Pascal
  • Borland Pascal
  • Delphi (Object Pascal)
• Back to BASIC in 2011 (VBA for automating MS-Access)
• Oldest of my own Python scripts I could find was written in 2006
• Started putting Python projects on GitHub in 2020

At work in 1994

Probably working on a Turbo/Borland Pascal program, in a text-only interface, on a PC running MS-DOS.

I suppose in 1994, it could have been running Windows 3.1, but I don't recall.

Original Console / Terminal

• Commands: batch files, executable programs
• Programs with character-based UIs
• 80 x 25 character display
• Limited interactivity

Graphical User Interface (GUI)

The Graphical user interface has largely replaced the earlier text-based UIs.

The term Graphical User Interface may have been used more in the past to make the distinction between this new style versus the text-based user interfaces common at the time GUIs were introduced more widely.

• Desktop applications

• Web browser / applications

• Highly interactive

GUI - Python - Desktop

There are multiple options for creating GUIs in Python:

• Standard Library: tkinter
• wxPython
• Qt for Python
• More: Awesome Python - gui-development

GUI - Python - Web

Web applications are also GUIs, and Python has many options for creating them:

• Django
• Flask
• Quart (if you want async)
• Pyramid
• FastAPI (not just APIs)
• More: Awesome Python - web-frameworks

GUI - Python - Web/Desktop

PgAdmin4 is an example of a web application that can run locally or on a server.

"pgAdmin 4 is a complete rewrite of pgAdmin, built using Python and Javascript/jQuery. A desktop runtime written in NWjs allows it to run standalone for individual users, or the web application code may be deployed directly on a web server for use by one or more users through their web browser."

Do you need a GUI?

If you're building a web, or mobile, application, the answer is yes (by default).

If you're building a utility that will run on a local machine, the answer is it depends.

• If the output is essentially graphical in nature (data visualization, etc.), you probably do want a GUI.
• Otherwise you may want to consider a simpler option.

Inputs to Python apps

CLI

Command-line arguments

• sys.argv
• Argparse
• Click

Promps:

• Input()
• Click prompt=

Python - input

TUI - Textual User Interface

Something in-between a CLI and a GUI

• More dynamic than CLI options and prompts.

Why would you want to build a TUI?

• You like doing things in the console/terminal.

• Your application could use more than command line input, but doesn't warrant a full desktop or web GUI.

Textual

How I heard about Textual

Podcast - Talk Python to Me

Talk Python to Me

Episode #336 - Terminal magic with Rich and Textual

Episode #380 - 7 lessons from building a modern TUI framework

Podcast - Python Bytes

Python Bytes

Episode #299 - Will McGugan drops by

Podcast - Real Python Podcast

Real Python Podcast

Episode #80 - Make Your Python App Interactive With a Text User Interface (TUI)

Article: Python Community Interview With Will McGugan

Will McGugan

github.com/willmcgugan

Will McGugan - Textualize/Rich

Textualize/rich

"Rich is a Python library for rich text and beautiful formatting in the terminal."

Textualize/Textual

textual.textualize.io

Textual App Examples

bloomberg/memray: Memray is a memory profiler for Python

Textualize/frogmouth: A Markdown browser for your terminal

Tutorial

Tutorial

• Stopwatch app

Aspects of Textual

• Widgets

• Composition

• Events

• Reactivity

• Class and Id: DOM Queries

• TCSS: Textual CSS

My Application

A Pomodoro Timer

Pomodoro Technique

Pomodoro Technique

Pomodoro Timer - Classic

Tick, tick, tick... RING!

Pomodoro Timer - Home Office

This one beeps when it's done, but doesn't tick the whole time.

Pomodoro Timer - Cubicle Land

It can be set to blink quietly.

Pomodoro Timer - Not!

Well, it can be, if you want.

Spreadsheet

• I have been using a spreadsheet to track pomodoro sessions.
• It's not a timesheet - I don't track all work.
• I have other things on other tabs, so I want to keep using the spreadsheet.

Git

I use git for source code management.

Some projects are on GitHub. Others are pushed to a local git server.

Some projects, such as one-off utility scripts, are not in git at all, but are backed up locally (and off-site).

pipx

"pipx is made specifically for application installation, as it adds isolation yet still makes the apps available in your shell: pipx creates an isolated environment for each application and its associated packages."

I have been using pipx to install Python command-line applications (not libraries).

pipx - Install Python Applications

I use pipx to install some Python tools.

pipx install hatch

pipx install pgadmin4

I also like to install my own tools, outside of development, using pipx.

pipx install pomodorable

Packages don't have to be on PyPI, but you have to specify the path to a .whl file. One uploaded to a GitHub release will work.

pipx install image_snip@https://github.com/wmelvin/image-snip/releases/download/v2024.03.1/image_snip-2024.3.1-py3-none-any.whl

A .whl file uploaded to a web hosting platform will also work.

pipx install gitramble@https://bogusoft.com/packages/gitramble/gitramble-0.1.dev1-py3-none-any.whl

Project tools

• Hatch - Python project manager (environments, packaging, and more)
• Ruff - linter and code formatter (integrated with Hatch)
• pytest - testing framework
• Just - command runner

ruff

• Linter and Formatter
• configure in pyproject.toml (or ruff.toml)
• Hatch integrates Ruff

Just

just a command runner

"just is a handy way to save and run project-specific commands. Commands, called recipes, are stored in a file called justfile with syntax inspired by make..."

I learned about just looking at some of Simon Willison's projects on GitHub. I saw a file named Justfile and wondered what it does.

Simon Willison

• github.com/simonw
• Post: just-with-django.md
• Post: Python packages with pyproject.toml and nothing else

Textual Development Tools

• Textual Devtools
• tcss-vscode-extension: VS Code extension that enables syntax highlighting for Textual CSS files.
• pytest-textual-snapshot: Snapshot testing for Textual applications

Showstoppers?

When planning a project, it is good to think about potential showstoppers.

• Is what you want the project to do actually possible.

• Are there capabilities needed for the application to succeed that are not available in the language, framework, or platform?

A Toasty Requirement

For a Pomodoro Timer application to be useful, it needs to notify you when the countdown is finished.

It was encouraging to see that Textual has a Toast widget. Unfortunately, Textual's Toast widget only pops up in the terminal. I want a system notification.

Searching for a Python package to do system notifications turned up a few. Some were Windows-only. Some required installing additional system packages.

I settled on plyer:

• part of the Kivy project
• does notifications on multiple platforms

Small POC to verify

Python script toasty

Ran on:

• Multiple Linux PCs and VMs (Debian - based)
• Windows 10 PC
• Windows 11 VM on Azure (I have no PCs that Microsoft considers worthy of running Windows 11 - oh well)
• I have no Mac, so not tested on that OS

Project Setup

hatch init

Running hatch init creates scaffolding for a Python project.

• Directory tree (uses a src layout)
• Default LICENSE and README files
• pyproject.toml

I made some edits before doing the initial git commit.

Project Dependencies

Packages used

• Textual - Textual User Interface framework
• Click - command-line options
• platformdirs - common directories on different platforms
• plyer - system notifications
• python-dotenv - override default settings during development
• tomlkit - store configuration as TOML

Application

Classes

AppConfig

AppData

• config
• file output
• cli_functions

UI(App)

Textual - Bindings

Bindings are declared in the App class.

Actions are implemented with the method name starting with action_ followed by the action defined in the BINDINGS list.

The action descriptions show in the app's Footer.

Click for CLI

• Some options are CLI-only

• Otherwise run the UI

Testing a Textual App

Textual Guide: Testing

Snapshot testing for Textual apps: pytest-textual-snapshot

Using the App

Outputs

Data CSV - Stored in user app data location.

Daily CSV - Aligns with the layout of the spreadsheet I've been using for years.

Daily Markdown - Written to an Obsidian Daily Notes file.

Showstoppers? - Part II

Segfault

• Not sure why this happened, but I suspect I was misusing the timer event and reactivity.

• By default Ubuntu does not write core-dump files for user packages, so there was not one to look at (as if I'd know what I was looking at ;)

What Else?

Some commits to look at (maybe):

• Initial UI mockup phase
• Adding the TimerBar that mimics the markings on the classic timer.

Some aspects to look at in the code:

• Using classes to manage app state.
• Using textual run --dev to see TCSS changes live.

Gotchas

• Events, reactivity, and watchers
• TCSS default styles on widgets (ex. Button min-width 16)
• When to use async

What's Next?

Possible Enhancements

Here are a few things I may (or may not) do with the Pomodorable app:

• Add documentation using Material for MkDocs.

• Add a function to play a sound when a session is finished - maybe the sound of the classic kitchen timer ringing.

• Create an alternate AppData class that talks to a web API instead of the file system. That would require a web back-end, perhaps built using FastAPI.

That's All

Thank you

wmelvin.dev

You can find more of my ramblings in my "stuff" repo on GitHub.