pytermgui

Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more!

pip3 install pytermgui

---

Archival notice

PyTermGUI is no longer in development. The latest release will remain available, alongside its documentation. The MIT license allows for free modification of the library, as long as you include credit to its original author. Thank you for everything.

---

Why?

Mostly because terminals are cool, but creating terminal apps has historically been difficult. PyTermGUI aims to provide a simple, readable and modular way to make the app of your dreams!

Terminal apps are (often):

• Easier to install
• Faster & more resource efficient
• Less prone to differences between environments (no IE7 here!)

…than their web or native counterparts.

How?

We provide a couple of things to make your life easier:

• Sensible abstractions over most terminal standards
• A fully fledged, desktop-inspired window manager system with modals and completely customizable windows
• Mouse support out of the box with 0 configuration
• YAML (or Python) based styling engines
• TIM, our markup language for creating styled terminal text with expressive text, including systems for aliases & macros
• A bunch of things I can’t think of right now :slightly_smiling_face:

Additionally, there are a couple of neat tools to make your general Python development easier:

• An inspection utility
• A pretty printer for both the REPL and IPython
• A way to create SVG and HTML screenshots of your terminal

Terminal compatibility

PyTermGUI relies on ANSI virtual-terminal sequences for rendering, cursor reports, keyboard input, and mouse input. On Windows, support depends on the terminal emulator’s ANSI compatibility. Windows Terminal supports the expected cursor and mouse protocols, while the legacy Windows Console Host (conhost.exe) may provide reduced functionality. This does not depend on whether PowerShell or Command Prompt is running inside the emulator. Mouse support also depends on the emulator forwarding the requested events.

Examples

All images below are generated directly from the source displayed by a PyTermGUI-powered SVG exporter tool, Termage.

Your first application, a simple clock:

import time

import pytermgui as ptg

def macro_time(fmt: str) -> str:
    return time.strftime(fmt)

ptg.tim.define("!time", macro_time)

with ptg.WindowManager() as manager:
    manager.layout.add_slot("Body")
    manager.add(
        ptg.Window("[bold]The current time is:[/]\n\n[!time 75]%c", box="EMPTY")
    )

Since strings are converted into the Label widget, and all widgets use markup for styling, we can use a custom-defined TIM macro function to return the current time. After running the above, you should see something like:

For something a bit more in-depth, see this contact form inspired by asciimatics’ example:

import pytermgui as ptg

CONFIG = """
config:
    InputField:
        styles:
            prompt: dim italic
            cursor: '@72'
    Label:
        styles:
            value: dim bold

    Window:
        styles:
            border: '60'
            corner: '60'

    Container:
        styles:
            border: '96'
            corner: '96'
"""

with ptg.YamlLoader() as loader:
    loader.load(CONFIG)

with ptg.WindowManager() as manager:
    window = (
        ptg.Window(
            "",
            ptg.InputField("Balazs", prompt="Name: "),
            ptg.InputField("Some street", prompt="Address: "),
            ptg.InputField("+11 0 123 456", prompt="Phone number: "),
            "",
            ptg.Container(
                "Additional notes:",
                ptg.InputField(
                    "A whole bunch of\nMeaningful notes\nand stuff", multiline=True
                ),
                box="EMPTY_VERTICAL",
            ),
            "",
            ["Submit", lambda *_: submit(manager, window)],
            width=60,
            box="DOUBLE",
        )
        .set_title("[210 bold]New contact")
        .center()
    )

    manager.add(window)

This showcases the YAML-based config system, as well as some additional API. I recommended checking out the source file to see how the submit callback works.

Not a fan of colors? We’ve got you!

PyTermGUI is one of the only TUI libraries that offers NO_COLOR support that doesn’t suck ruin the usability & design of your apps.

This is how the above example looks like with the environment variable NO_COLOR set to anything. Note how contrast between colors is retained, as well as the inclusion of background colors:

Older terminals? No problem!

We use algorithms based on human vision to convert and downgrade colors when the current terminal emulator doesn’t support them. Here is a cool screenshot:

Questions? See the docs!

Pretty much every name in the library, private or public, has an insightful docstring attached to it, alongside walkthrough-based documentation articles. See them all on the documentation website!

Project status

PyTermGUI has reached its final release and is no longer under active development. The repository and its documentation are retained as an archive for existing users.