PyTermGUI 3.1.0

A simple and robust terminal UI library, written in Python.

A simple yet powerful TUI framework for your Python (3.7+) applications

pip3 install pytermgui

Batteries included or bare-metal. It's your choice.

PyTermGUI has both higher and lower level interfaces. If you're only here for the terminal APIs, ansi_interface will be your friend.

Zero dependencies

Everything here is home made, just like your grandmas cookies. There is only one optional dependency, PyYaml, which you won't have to install unless you plan on using YAML features.

Adapting to your needs

Here are just a couple of ways to define the same widget structure:

Using the basic class structure

# -- demo.py --
import pytermgui as ptg

demo = ptg.Window(
   ptg.Label("[210 bold]Hello world!"),
   ptg.Label(),
   ptg.InputField(prompt="Who are you?"),
   ptg.Label(),
   ptg.Button("Submit!")
)

Using data-pattern conversion

# -- demo.py --
import pytermgui as ptg

demo = (
    ptg.Window()
    + "[210 bold]Hello world!"
    + ""
    + ptg.InputField(prompt="Who are you?")
    + ""
    + ["Submit!"]
)

Using YAML

# -- demo.yaml --
widgets:
  demo:
    type: Window
    widgets:
      - Label:
          value: "[210 bold]Hello world!"
      - Label: {}

      - InputField:
          prompt: Who are you?
      - Label: {}

      - Button:
          label: Submit!

None of these is better than any other, it is all up to individual taste. We don't force you to do what we want, rather encourage you to morph the library around your needs.

By the way, this is what the created Window looks like. Nifty, huh?

A powerful CLI

The cli simultaneously serves as a set of powerful tooling for TUI related work, as well as a nice usage example of the higher level part of the library. You can run ptg --getch to get information about a keypress, ptg --size to get the current terminal dimensions and ptg --file <file> to interpret & run a YAML markup file inside of a window manager.

For more info, check out ptg -h.

Fully documented

The documentation details every public name in the library, making its usage as easy as possible. For more complete projects, check out examples, or some of the projects using PTG.

Projects using pytermgui

We take pride in seeing others use the library. If you have a project you'd like us to add here, create a PR!

Project name	Project description	Demo image
sipedon	An interactive aquarium for your terminal.
tracers	Easily debug and trace attribute changes in your Python classes

Some showcase images

Click on each image to see their source code!

A hello world program

The markup playground app

Note: Use ptg --markapp to try

A simple window manager demo in 13 lines of code, lifted from the docs

Projects to check out

The TUI game has been heating up as of recent. Here are some other interesting projects in the sphere:

• Winman - A window-manager add-on to the golang library tview. This project was a big inspiration for that specific aspect of PyTermGUI.
• Rich & Textual - Another Python-based set of TUI libraries. Some of the Rich markup syntax & code was used as inspiration for our own.
• pyTermTk - Name and functionality sibling of this project. Great TUI library if you are after tkinter/qt5 mimicking API.
• Jexer - One of the most insane-looking TUI libraries out there. Supports practically everything the terminal can do. I became aware of this project relatively recently, but it's been of great inspiration.
• notcurses - Another ridiculously powerful TUI library. Well worth installing and checking out the examples provided.