stgl — Simple Text-based Graphical Library

stgl is an MLX-like terminal graphics library for Python. It is a thin, opinionated wrapper around tinting (markup-based ANSI coloring) and blessed (terminal input/event loop), exposing an API where each function has an equivalent in the MinilibX (MLX) library.

In MLX you draw pixels in a window; in stgl a "pixel" is a single character cell, a "color" is a tinting palette name ("RED", "BLK"...), an "image" is a grid of styled cells, and the "loop" is the blessed event loop. It is pure text — but the math and the shapes are the same idea, just given different names.

Install

pip install stgl
# or, from the repo:
pip install ./stgl

Requires Python >= 3.10. Dependencies: tinting>=0.1.0, blessed>=1.47.0.

Quick start

import stgl

win = stgl.new_window("BLK", "BLK")          # bg, canvas_bg
stgl.use_image(win, my_canvas)               # my_canvas subclasses stgl.Image
stgl.loop(win)                               # run the event loop

Subclass stgl.Image to build a scene:

import stgl

class HelloCanvas(stgl.Image):
    def base_canvas(self, refresh=False) -> list[str]:
        return ["@WHT[Hello, stgl!]@"]
    def update(self, ticks, s_yx, e_yx) -> list[str]:
        canvas = self.base_canvas()
        self.base_style = stgl.style_grid_noesc(canvas)
        self.grid = [list(stgl.ttext(r, False)) for r in canvas]
        self.grid_og = [list(stgl.ttext(r, False)) for r in canvas]
        return stgl.grid_apply(self.grid, self.base_style, [],
                                start_x=s_yx[1], end_x=e_yx[1],
                                start_y=s_yx[0], end_y=e_yx[0])
    def key_press(self, key) -> bool:
        return False

MLX → stgl reference

Colors: 0xAARRGGBB integers become tinting palette names exposed as constants (stgl.BLK, stgl.WHT, stgl.RED, ...). Use stgl.color(r, g, b, a=255) to build the MLX-style integer if you need it.

License

MIT — see LICENSE for full text.

Author

Italo Almeida — italoalmeida@hezz.it