Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bczsalba/pytermgui
Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more!
https://github.com/bczsalba/pytermgui
ansi ansi-escape-codes ansi-escape-sequences cli command-line console cross-platform gui pytermgui python python3 terminal tui typing
Last synced: 21 minutes ago
JSON representation
Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more!
- Host: GitHub
- URL: https://github.com/bczsalba/pytermgui
- Owner: bczsalba
- License: mit
- Created: 2021-03-31T18:01:08.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-12-29T22:11:17.000Z (16 days ago)
- Last Synced: 2025-01-07T09:15:00.007Z (7 days ago)
- Topics: ansi, ansi-escape-codes, ansi-escape-sequences, cli, command-line, console, cross-platform, gui, pytermgui, python, python3, terminal, tui, typing
- Language: Python
- Homepage: https://ptg.bczsalba.com
- Size: 54.4 MB
- Stars: 2,351
- Watchers: 19
- Forks: 58
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- my-awesome-github-stars - bczsalba/pytermgui - Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more! (Python)
README
> Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more!
```bash
pip3 install pytermgui
```
## Notice
A much better, more complete version of PTG's core ideas now exists over at [Shade 40](https://github.com/shade40). While PTG is not yet fully obsolete,
those libraries will be the primary focus of development going forward.
## 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
## Examples
> All images below are generated directly from the source displayed by a PyTermGUI-powered SVG exporter tool, [Termage](https://github.com/bczsalba/termage).
Your first application, a simple clock:
```python3
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](https://github.com/peterbrittain/asciimatics#how-to-use-it):
```python3
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](https://github.com/bczsalba/pytermgui/blob/master/utils/readme_scripts/contact.py) 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](https://no-color.org) 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:
Disclaimer: Termage currently doesn't play nicely to changing colorsystems during runtime, so this image had to be captured natively :(
## Questions? See the docs!
Pretty much every single name in the library, private or public, has an insightful dockstring attached to it, and we are accumulating a growing amount of walkthrough-based documentations articles. See 'em all on the [doc website](https://ptg.bczsalba.com)!
## 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](https://github.com/bczsalba/pytermgui/blob/master/CONTRIBUTING.md). 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. :slightly_smiling_face: