ttygrid 0.1.1

Simple terminal grid rendering library

ttygrid

ttygrid is a grid-based framework for building terminal simulations, games, and visualizations.

• ttygrid on PyPi

Features

• Grid class and cell class
• Functions to get and set cells
• Inbuilt coloring for different symbols using termcolor
• Auto adjust to terminal size using shutil

v0.1 is out!

Quick Start Guide

You can install ttygrid using pip using:

pip install ttygrid

Alternatively, you could use:

pip3 install ttygrid

Once installed, import with

from ttygrid import Grid, Cell

Example

import random
import time
from ttygrid import Grid

def main():
    grid = Grid()
    while True:
        cells = grid.get_all_cells(empty=True)
        for cell in cells:
            cell.symb = random.choice(['0', '1'])
            grid.draw_cells(cell)
        grid.clear_term()
        print(grid)
        time.sleep(0.1)

if __name__ == "__main__":
    main()

Documentation

Grid()

Grid(rows=80, cols=40, mode="fit", grid=None, color_map=COLORS)

Creates a new ttygrid grid instance that can be manipulated using the library.

Args

• rows (int) - If mode is "custom", the number of rows in the grid. If mode is "fit", the default number of rows in the grid if shutil.get_terminal_size() fails to determine terminal size. Default value 80.

• cols (int) - If mode is "custom", the number of cols in the grid. If mode is "fit", the default number of cols in the grid if shutil.get_terminal_size() fails to determine terminal size. Default value 40.

• mode (str) - Can be either "fit" or "custom" (case-sensitive). If mode is "custom", the dimensions of the grid are given through rows and cols. If mode is "fit", the dimensions are given through shutil.get_terminal_size(), with rows and cols as fallback. Default value "fit"

• color_map (dict[str, str]) - A dict with keys as cell symbols and values as colors recognized by termcolor.colored(). The default value is:

COLORS = {
        '0': "green",
        '1': "black",
        '2': "yellow",
        '3': "blue",
        '4': "light_yellow",
    }

---

str() (Grid)

print(grid)

Prints the formatted grid to the terminal.

---

show_size()

show_size(grid)

Prints the number of Lines (rows) and Columns (cols) in the grid. To get them programmatically, use grid.rows and grid.cols instead.

---

clear_term()

clear_term()

Clears the terminal. Typically used before printing new frames.

---

get_cell()

get_cell(col, row)

Returns the Cell object located at the coordinates (col, row) Raises ValueError if cell does not exist.

---

validate_cell()

validate_cell(cell)

Raises ValueError if cell coordinates not found in grid

---

get_all_cells()

get_all_cells(empty=True)

Get a list of all cells in the grid. If empty is True, empty cells are also included. If empty is False, empty cells are not included. The default value is True

---

draw_cells()

draw_cells(*cells)

Draws all valid cells passed as arguments onto the grid.

---

clear()

clear()

Clears the grid (resets it to all cells being None)

---

redraw_frame()

redraw_frame(cell_map)

The grid is redrawn using cell_map. Effectively, the value of the grid is now cell_map. A cell_map value not made of cells or having irregular sides compared to original grid.rows and grid.cols, results in undefined behaviour. It is best to first call get_all_cells() and pass in modified values of the call to redraw_frame()

---

Cell Class

Cell()

Cell(x, y, symb=None)

Args:

• x - the x (col) position of the Cell
• y - the y (row) position of the Cell
• symb - the symbol represented by the cell. A value of None indicates an empty cell.

---

str()

print(cell)

Prints the cell position and symbol

---

Known Issues

• Extra newline after print (Scheduled to be fixed in v0.2)

---

Roadmap

• Drawing primitives
• Demos
• Customizable status bar for simulation