Textual: The Python library for building TUI and CLI applications, for Linux, Mac or Windows

2023-07-07 08:00:00

Python is a popular programming language known for its simplicity, readability, and versatility. It provides extensive libraries and frameworks that cater to various application domains.

Today we are going to discuss how you can create and run applications on your terminal with a python library called Textual . When you think of an app that runs in the terminal, you think of it as a text-based app but not with Textual .

While the graphical user interface (GUI) has gained popularity, there are applications where the TUI text user interface is preferred, due to its lightweight, fast, and flexible input and output interactions.

What is textual Python?

Textual is an open source Python framework created by Will McGugan , which is intended for rapid application development. Using a simple Python API to create complex text-based user interfaces (TUIs) and command line interfaces (CLIs).

Con Textual you can create rich and interactive console applications by adding widgets such as buttons, context toggles, scroll bars, menus, check boxes, input fields, and more to your terminal programs.

Textual provides several components and tools that make it easy to build command-line applications, which support keyboard events, mouse events, and input handling. You can add layouts, panels, and views to structure your app’s interface. It also contains built-in support for themes, allowing you to customize the appearance of the application.

Here are some cool features of Textual :

rapid development – Use your current Python skills to create stunning user interfaces.
low requirements : if you want, you can run Textual on a single board computer.
Multiplataform : It can run everywhere: Windows, Linux and Mac.
Remote : SSH can be used to run textual applications.
CLI integration – Command Prompt can be used to open and run applications textual .
Open Source : do you want to improve Textual ? You can contribute to the project because the MIT license applies to textual.

Install Textual on Linux, Mac and Windows

to start with Textual , your system must have Python 3.7 or later installed. After that you can install Textual using PyPI which is a software repository for Python programming.

The installation of textual[dev] it is a must if you intend to develop textual applications. Some additional dependencies are installed in the [dev]part for development.

pip install “textual[dev]”
O
pip3 install “textual[dev]”

You can skip the part [dev] if you only want to run text applications as shown.

pip install “textual”
OR
pip3 install “textual”

Let’s not wait and run the following command to see what it is capable of textual .

python -m textual
O
python3 -m textual

It is a demo provided by the library so you can explore the functionalities provided as widgets: buttons, input, trees, etc. and CSS (Cascading Style Sheets) to create a rich user interface.

Textual is based on Rich , which is a Python module that enables amazing formatting and rich text in the terminal. With the help of these, we can display data as JSON or tables very well in the terminal.

Create your first TUI application in Python

After playing around with the demo, it’s time to get your hands dirty and write some real code. You can explore the official documentation for a more detailed explanation.

To create an application ( app.py ) first, we need to import the class App and create a subclass. We then create an instance and use run() it to start the application.

from textual.app import App

class MyApp(App):
pass

if __name__ == “__main__”:
app = MyApp()
app.run()

Now let’s run our application app.py using:

python app.py
O
python3 app.py

You will see the following blank window

It seems boring, right? Exit the application by pressing CTRL + X on your keyboard. Let’s add some text and widgets.

from textual.app import App, ComposeResult
from textual.widgets import Button, Label

class MyApp(App):

def compose(self) -> ComposeResult:
self.close_button = Button(“Cerrar”, id=”close”)
yield Label(“Este es un tutorial de aplicación Texual”)
yield self.close_button

def on_mount(self) -> None:
self.screen.styles.background = “blue”
self.close_button.styles.background = “purple”
def on_button_pressed(self, event: Button.Pressed) -> None:
self.exit(event.button.id)

if __name__ == “__main__”:
app = MyApp()
app.run()

Textual: add widgets to the application

This brought a bit of life to our app. The close button works perfectly. Try clicking the mouse to exit. the attribute self.screen.styles.background is assigned to ” blue ” by controller on_mount which, as you can probably guess, makes the background blue.

The last step is to develop an on_button_pressed() method that serves as an event handler to detect button presses. Your program ends when the close button is pressed, which calls the function on_button_pressed().

Add CSS to the app

Cascading Style Sheets o CSS, is a list of styles and instructions on how to use each style in a web page. The only difference with Textual is that the widgets are designed by the style sheet, but the concept is the same.

Create a CSS file called app.css in the same directory where app.py is present and add the following code.

Screen {
layout: grid;
grid-size: 2;
grid-gutter: 2;
padding: 2;
}

#tutorial {
width: 100%;
height: 100%;
column-span: 2;
content-align: center bottom;
text-style: bold;
}

Button {
width: 100%;
column-span: 2;
}

And make the following changes to your app.pyapplication. We are importing the CSS file that we created using “CSS_PATH = “app.css”” .

from textual.app import App, ComposeResult
from textual.widgets import Button, Label

class MyApp(App):
CSS_PATH = “app.css”

def compose(self) -> ComposeResult:
self.close_button = Button(“Cerrar”, id=”close”)
yield Label(“Este es un tutorial de aplicación Texual”, id=”tutorial”)
yield self.close_button

def on_mount(self) -> None:
self.screen.styles.background = “blue”
self.close_button.styles.background = “purple”

def on_button_pressed(self, event: Button.Pressed) -> None:
self.exit(event.button.id)

if __name__ == “__main__”:
app = MyApp()
app.run()

Then we add ids to the label and the close button. The number two indicates that the grid will be two columns wide and two rows wide when you tell Textual you want to use a grid layout.

The grid gutter regulates the distance between rows. Last but not least, the padding adjusts to surround the widget content with space.

Our first TUI application created with Textual

Only a few items were discussed in this article. there’s a lot to Textual can do.

Conclusion

In conclusion, the library textual allows Python developers to effortlessly create rich and interactive user interfaces in the terminal. With its simple API and versatile features, Textual enables seamless development of command line applications with a focus on usability and engagement.

Whether you’re building command-line tools or text-based games, Textual offers a powerful and intuitive framework for creating immersive experiences in the world of text-based interfaces.

Text Terminal Application

Start exploring Textual today and unlock the potential of text-based interactivity in your Python applications.