An Intro to Asciimatics – Another Python TUI Package
Text-based user interfaces (TUIs) have gained significant popularity in recent years. Even Rust has its own library called Ratatui after all. Python has several different TUI packages to choose from. One of those packages is called Asciimatics.
While Asciimatics is not as full-featured and slick as Textual is, you can do quite a bit with Asciimatics. In fact, there is a special kind of charm to the old-school flavor of the TUIs that you can create using Asciimatics.
In this tutorial, you will learn the basics of Asciimatics:
Installation
Creating a Hello World application
Creating a form
The purpose of this tutorial is not to be exhaustive, but to give you a sense of how easy it is to create a user interface with Asciimatics. Be sure to read the complete documentation and check out their examples to learn more.
For now, let’s get started!
Installation
Asciimatics is a third-party Python package. What that means is that Asciimatics is not included with Python. You will need to install it. You should use a Python virtual environment for installing packages or creating new applications.
Whether you use the virtual environment or not, you can use pip to install Asciimatics:
python -m pip install asciimatics
Once Asciimatics is installed, you can proceed to creating a Hello World application.
Creating a Hello World Application
Creating a simple application is a concrete way to learn how to use an unfamiliar package. You will create a fun little application that “prints” out “Hello from Asciimatics” multiple times and in multiple colors.
Open up your favorite Python IDE or text editor and create a new file called hello_asciimatics.py and then add the following code to it:
This codfe takes in an Asciimatics Screen object. You draw your text on the screen. In this case, you use the screen’s print_at() method to draw the text. You use Python’s handy random module to choose random coordinates in your terminal to draw the text as well as choose random foreground and background colors.
You run this inside an infinite loop. Since the loop runs indefinitely, the text will be drawn all over the screen and over the top of previous iterations of the text. What that means is that you should see the same text over and over again, getting written on top of previous versions of the text.
If the user presses the “Q” button on their keyboard, the application will break out of the loop and exit.
When you run this code, you should see something like this:
Isn’t that neat? Give it a try on your machine and verify that it works.
Now you are ready to create a form!
Creating a Form
When you want to ask the user for some information, you will usually use a form. You will find that this is true in web, mobile and desktop applications.
To make this work in Asciimatics, you will need to create a way to organize your widgets. To do that, you create a Layoutobject. You will find that Asciimatics follow an hierarchy of Screen -> Scene -> Effects and then layouts and widgets.
All of this is kind of abstract though. So it make this easier to understand, you will write some code. Open up your Python IDE and create another new file. Name this new file ascii_form.pyand then add this code to it:
The Form is a subclass of Frame which is an Effect in Asciimatics. In this case, you can think of the frame as a kind of window or dialog within your terminal.
The frame will contain your form. Within the frame, you create a Layoutobject and you tell it to fill the frame. Next you add the widgets to the layout, which will add the widgets vertically, from top to bottom.
Then you create a second layout to hold two buttons: “OK” and “Cancel”. The second layout is defined as having four columns with a size of one. You will then add the buttons and specify which column the button should be put in.
To show the frame to the user, you add the frame to a Scene and then you play() it.
When you run this code, you should see something like the following:
Pretty neat, eh?
Now this example is great for demonstrating how to create a more complex user interface, but it doesn’t show how to get the data from the user as you haven’t written any code to grab the contents of the Text widgets. However, you did show that when you created the buttons, you can bind them to specific methods that get called when the user clicks on those buttons.
Wrapping Up
Asciimatics makes creating simple and complex applications for your terminal easy. However, the applications have a distincly retro-look to them that is reminiscent to the 1980’s or even earlier. The applications are appealing in their own way, though.
This tutorial only scratches the surface of Asciimatics. For full details, you should check out their documentation.
If you wamt to create a more modern looking user interface, you might want to check out Textual instead.
Related Reading
Want to learn how to create TUIs the modern way? Check out my book: Creating TUI Applications with Textual and Python.
Available at the following: