Metadata-Version: 2.4
Name: stgl
Version: 1.0.2
Summary: Simple Text-based Graphical Library - an MLX-like terminal graphics API built on tinting + blessed
Author-email: Italo Almeida <italoalmeida@hezz.it>
License: MIT
Project-URL: Homepage, https://github.com/italoalmeida0/stgl
Project-URL: Repository, https://github.com/italoalmeida0/stgl
Project-URL: Documentation, https://github.com/italoalmeida0/stgl#readme
Project-URL: Issues, https://github.com/italoalmeida0/stgl/issues
Project-URL: Changelog, https://github.com/italoalmeida0/stgl/releases
Keywords: mlx,terminal,tui,graphics,42,pacman,retro
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Terminals
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tinting>=0.1.0
Requires-Dist: blessed>=1.47.0
Dynamic: license-file

# stgl — Simple Text-based Graphical Library

[![PyPI version](https://img.shields.io/pypi/v/stgl.svg)](https://pypi.org/project/stgl/)
[![Python](https://img.shields.io/pypi/pyversions/stgl.svg)](https://pypi.org/project/stgl/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/italoalmeida0/stgl/actions/workflows/ci.yml/badge.svg)](https://github.com/italoalmeida0/stgl/actions)

`stgl` is an MLX-like terminal graphics library for Python. It is a thin,
opinionated wrapper around [`tinting`](https://pypi.org/project/tinting/)
(markup-based ANSI coloring) and [`blessed`](https://pypi.org/project/blessed/)
(terminal input/event loop), exposing an API where **each function has an
equivalent in the [MinilibX](https://harm-smits.gitbooks.io/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

```bash
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

```python
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:

```python
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

| MLX                              | stgl                                              |
| -------------------------------- | ------------------------------------------------- |
| `mlx_init`                       | `stgl.init`                                        |
| `mlx_release`                    | `stgl.release`                                     |
| `mlx_new_window`                 | `stgl.new_window`                                  |
| `mlx_clear_window`               | `stgl.clear_window`                                |
| `mlx_destroy_window`             | `stgl.destroy_window`                               |
| `mlx_pixel_put`                  | `stgl.pixel_put`                                    |
| `mlx_string_put`                 | `stgl.string_put`                                   |
| `mlx_new_image`                  | `stgl.new_image`                                    |
| `mlx_get_data_addr`              | `stgl.get_data_addr`                                |
| `mlx_put_image_to_window`        | `stgl.put_image_to_window`                          |
| `mlx_destroy_image`              | `stgl.destroy_image`                                |
| `mlx_xpm_file_to_image`         | `stgl.xpm_file_to_image`                            |
| `mlx_png_file_to_image`         | `stgl.png_file_to_image`                            |
| `mlx_loop`                       | `stgl.loop`                                         |
| `mlx_loop_exit`                  | `stgl.loop_exit`                                    |
| `mlx_key_hook`                   | `stgl.key_hook`                                     |
| `mlx_mouse_hook`                 | `stgl.mouse_hook`                                   |
| `mlx_expose_hook`                | `stgl.expose_hook`                                  |
| `mlx_loop_hook`                  | `stgl.loop_hook`                                    |
| `mlx_hook`                       | `stgl.hook`                                         |
| `mlx_mouse_hide/show/move`       | `stgl.mouse_hide`/`mouse_show`/`mouse_move`          |
| `mlx_mouse_get_pos`              | `stgl.mouse_get_pos`                                |
| `mlx_do_key_autorepeatoff/on`    | `stgl.do_key_autorepeatoff`/`do_key_autorepeaton`   |
| `mlx_get_screen_size`            | `stgl.get_screen_size`                              |
| `mlx_do_sync` / `mlx_sync`       | `stgl.do_sync` / `stgl.sync`                        |

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](LICENSE) for full text.

## Author

Italo Almeida — [italoalmeida@hezz.it](mailto:italoalmeida@hezz.it)
