Python TUI framework with mouse support, modular widget system, customizable and a rapid terminal markup language. |
|
|
Published 2025-03-27 12:25:43 Modified 2025-05-27 13:08:26 |
PyTermGUI: TUIs that don't suck
Python TUI framework with mouse support, modular widget system, customizable and a rapid terminal markup language. (Editor's note: The predecessor of Celadon)
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
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
Examples
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 single name in the library, private or public, has an insightful docstring attached to it, and we are accumulating a growing amount of walkthrough-based documentations articles. See 'em all on the doc website!
Contributions, issues et al.
If you have any problems using the library, feel free to open up a discussion or raise an issue ticket. If you would prefer to hack on the library yourself, see the contribution guidelines.
Pull requests are encouraged, but make sure you aren't trying to fix an issue that others are already working on, for your own sake.
Comments
Related
Sipedon: An aquarium for your terminal ↗ | |
Sipedon is an aquarium simulator that runs in your terminal. It is currently in its early stages, but eventually it should become an aquarium management game. |
|
|
Published 2025-03-27 12:10:48 Modified 2025-05-26 22:09:18 |
CELX: TUI applications over HTTP ↗ | |
CELX is a terminal application framework that delivers interfaces through an HTTP connection. It exists as part of the shade40 family of tooling. |
|
|
Published 2025-03-21 21:46:20 Modified 2025-04-03 00:49:14 |