bliplot 0.1.0__tar.gz

bliplot-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.3
+Name: bliplot
+Version: 0.1.0
+Summary: Terminal text-based plotting utility
+Author: abdallah-azzouni
+Author-email: abdallah-azzouni <xara25az@gmail.com>
+Requires-Dist: numpy>=2.5.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# bliplot
+
+Stupidly simple terminal graphs. One function with zero config needed and sub-character resolution.
+
+```python
+from bliplot import plot
+print(plot([1, 4, 2, 8, 5, 7, 3, 9, 6]))
+```
+![first example](assets/img1.png)
+
+That's it. That's the whole API.
+
+## Why
+
+Every terminal-plotting library makes you learn its DSL before you can see a
+single number. `bliplot` is one function that takes a list and gives you back
+a string. Print it, log it, pipe it, stream it... It doesn't care. It's yours !
+
+## Install
+
+```bash
+pip install bliplot
+```
+
+or, if you're using [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add bliplot
+```
+
+## Usage
+
+```python
+import math
+from bliplot import plot
+
+
+def generate_waveform(x: float) -> float:
+    return math.sin(x / 10) * math.cos(x / 5) * 10
+
+
+data_points = [generate_waveform(x) for x in range(100)]
+
+graph = plot(data_points, width=70, height=15, color="CYAN")
+print(graph)
+```
+![waveform](assets/wave.png)
+
+### Live / streaming graphs
+
+Because `plot()` just returns a string, you can call it in a loop for a
+live-updating graph. No special "live mode" needed:
+
+```python
+import math
+import time
+from bliplot import plot
+
+CLEAR = "\033[H\033[J"
+WIDTH = 80
+HEIGHT = 15
+
+# We run this for 200 frames of animation
+for t in range(200):
+    lst = []
+    for x in range(WIDTH):
+        # Moving the x offset by t * 0.2 causes the wave to travel left to right
+        x_moving = x - (t * 0.2)
+
+        # Base wave + high frequency noise
+        wave = math.sin(x_moving * 0.2) * math.cos(x_moving * 0.05)
+        noise = 0.2 * math.sin(x_moving * 1.5)
+
+        # Center envelope to keep the edges clean
+        envelope = math.exp(-((x - (WIDTH / 2)) / (WIDTH / 3)) ** 2)
+
+        lst.append((wave + noise) * envelope)
+
+    # Overwrite the screen
+    print(
+        CLEAR + plot(lst, width=WIDTH, height=HEIGHT, color="GREEN"), end="", flush=True
+    )
+    time.sleep(0.04)  # ~25 frames per second
+```
+![live render](assets/live_render.gif)
+
+The clear-screen escape redraws the graph in place instead of scrolling a
+new one down the terminal on every iteration.
+
+### Parameters
+
+```python
+plot(lst: list, width: int = None, height: int = None, color: str = None) -> str
+```
+
+| Param    | Type   | Default            | Description                                              |
+|----------|--------|---------------------|------------------------------------------------------------|
+| `lst`    | list   | —                   | Y values to plot. X values are inferred from index.        |
+| `width`  | int    | terminal width      | Graph width in characters.                                  |
+| `height` | int    | terminal height     | Graph height in characters.                                 |
+| `color`  | str    | `None` (renders as white) | One of `RESET`, `GREEN`, `CYAN`, `YELLOW`, `RED`, `MAGENTA`, `BLUE`, `WHITE`, `BLACK`. |
+
+Returns a string, ready to `print()`.
+
+`NaN`, `+Inf`, and `-Inf` values in `lst` are treated as `0`.
+
+
+## How it works
+
+Terminal graphs are usually blocky because each character cell can only be
+"on" or "off" so you lose all the resolution between one row of blocks and
+the next. `bliplot` fixes this by spliting each value into an integer part and a fractional
+remainder. The integer part decides how many full blocks (`█`) to stack.
+The remainder picks *which* of the 8 partial block glyphs
+(`▁▂▃▄▅▆▇█`) caps the column, giving you roughly 8x the vertical resolution.
+
+Negative values use the upper-eighth block set (`▔🮂🮃▀🮄🮅🮆█`) so bars
+growing downward from the midline look correct rather than upside-down.
+
+## License
+
+MIT

bliplot-0.1.0/README.md

@@ -0,0 +1,122 @@
+# bliplot
+
+Stupidly simple terminal graphs. One function with zero config needed and sub-character resolution.
+
+```python
+from bliplot import plot
+print(plot([1, 4, 2, 8, 5, 7, 3, 9, 6]))
+```
+![first example](assets/img1.png)
+
+That's it. That's the whole API.
+
+## Why
+
+Every terminal-plotting library makes you learn its DSL before you can see a
+single number. `bliplot` is one function that takes a list and gives you back
+a string. Print it, log it, pipe it, stream it... It doesn't care. It's yours !
+
+## Install
+
+```bash
+pip install bliplot
+```
+
+or, if you're using [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add bliplot
+```
+
+## Usage
+
+```python
+import math
+from bliplot import plot
+
+
+def generate_waveform(x: float) -> float:
+    return math.sin(x / 10) * math.cos(x / 5) * 10
+
+
+data_points = [generate_waveform(x) for x in range(100)]
+
+graph = plot(data_points, width=70, height=15, color="CYAN")
+print(graph)
+```
+![waveform](assets/wave.png)
+
+### Live / streaming graphs
+
+Because `plot()` just returns a string, you can call it in a loop for a
+live-updating graph. No special "live mode" needed:
+
+```python
+import math
+import time
+from bliplot import plot
+
+CLEAR = "\033[H\033[J"
+WIDTH = 80
+HEIGHT = 15
+
+# We run this for 200 frames of animation
+for t in range(200):
+    lst = []
+    for x in range(WIDTH):
+        # Moving the x offset by t * 0.2 causes the wave to travel left to right
+        x_moving = x - (t * 0.2)
+
+        # Base wave + high frequency noise
+        wave = math.sin(x_moving * 0.2) * math.cos(x_moving * 0.05)
+        noise = 0.2 * math.sin(x_moving * 1.5)
+
+        # Center envelope to keep the edges clean
+        envelope = math.exp(-((x - (WIDTH / 2)) / (WIDTH / 3)) ** 2)
+
+        lst.append((wave + noise) * envelope)
+
+    # Overwrite the screen
+    print(
+        CLEAR + plot(lst, width=WIDTH, height=HEIGHT, color="GREEN"), end="", flush=True
+    )
+    time.sleep(0.04)  # ~25 frames per second
+```
+![live render](assets/live_render.gif)
+
+The clear-screen escape redraws the graph in place instead of scrolling a
+new one down the terminal on every iteration.
+
+### Parameters
+
+```python
+plot(lst: list, width: int = None, height: int = None, color: str = None) -> str
+```
+
+| Param    | Type   | Default            | Description                                              |
+|----------|--------|---------------------|------------------------------------------------------------|
+| `lst`    | list   | —                   | Y values to plot. X values are inferred from index.        |
+| `width`  | int    | terminal width      | Graph width in characters.                                  |
+| `height` | int    | terminal height     | Graph height in characters.                                 |
+| `color`  | str    | `None` (renders as white) | One of `RESET`, `GREEN`, `CYAN`, `YELLOW`, `RED`, `MAGENTA`, `BLUE`, `WHITE`, `BLACK`. |
+
+Returns a string, ready to `print()`.
+
+`NaN`, `+Inf`, and `-Inf` values in `lst` are treated as `0`.
+
+
+## How it works
+
+Terminal graphs are usually blocky because each character cell can only be
+"on" or "off" so you lose all the resolution between one row of blocks and
+the next. `bliplot` fixes this by spliting each value into an integer part and a fractional
+remainder. The integer part decides how many full blocks (`█`) to stack.
+The remainder picks *which* of the 8 partial block glyphs
+(`▁▂▃▄▅▆▇█`) caps the column, giving you roughly 8x the vertical resolution.
+
+Negative values use the upper-eighth block set (`▔🮂🮃▀🮄🮅🮆█`) so bars
+growing downward from the midline look correct rather than upside-down.
+
+## License
+
+MIT

bliplot-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "bliplot"
+version = "0.1.0"
+description = "Terminal text-based plotting utility"
+readme = "README.md"
+authors = [
+    { name = "abdallah-azzouni", email = "xara25az@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "numpy>=2.5.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"

bliplot-0.1.0/src/bliplot/__init__.py

@@ -0,0 +1,98 @@
+import numpy as np
+import shutil
+
+
+def plot(lst: list, width: int = None, height: int = None, color: str = None):
+    """_summary_
+    Renders a list of numbers as a text-based graph in the terminal.
+
+
+    Args:
+        lst (list): The Y values to be plotted. The X values are inferred from the index of the list.
+        width (int, optional): The width of the graph in characters. If None, it will use the terminal width.
+        height (int, optional): The height of the graph in characters. If None, it will use the terminal height.
+        color (str, optional):  The color of the graph. Can be one of "RESET", "GREEN", "CYAN", "YELLOW", "RED", "MAGENTA", "BLUE", "WHITE", or "BLACK". If None, it will default to white.
+
+    Returns:
+        _type_: The graph as a string, ready to be printed to the terminal.
+
+    Note:
+        Non-finite values (NaN, +Inf, -Inf) in lst are treated as 0.
+
+    """
+
+    term = shutil.get_terminal_size()
+    w = width if width is not None else term.columns - 1
+    h = height if height is not None else term.lines - 1
+    COLORS = {
+        "RESET": "\033[0m",
+        "GREEN": "\033[32m",
+        "CYAN": "\033[36m",
+        "YELLOW": "\033[33m",
+        "RED": "\033[31m",
+        "MAGENTA": "\033[35m",
+        "BLUE": "\033[34m",
+        "WHITE": "\033[37m",
+        "BLACK": "\033[30m",
+    }
+    color = COLORS.get(
+        color,
+        COLORS["WHITE"],
+    )
+    BLOCKS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+    IBLOCKS = ["▔", "🮂", "🮃", "▀", "🮄", "🮅", "🮆", "█"]
+    middle_point = "·"
+
+    if len(lst) == 0:
+        return ""
+
+    x_scale = np.linspace(0, len(lst) - 1, w)
+    x_new = np.interp(x_scale, np.arange(len(lst)), lst)
+    x_new = np.nan_to_num(x_new, nan=0.0, posinf=0.0, neginf=0.0)
+
+    has_positive = bool(np.any(x_new > 0))
+    has_negative = bool(np.any(x_new < 0))
+
+    if has_negative and has_positive:
+        midpoint = (h - 1) // 2
+        scale_range = midpoint
+    elif has_positive:
+        midpoint = h - 1
+        scale_range = midpoint
+    else:
+        midpoint = 0
+        scale_range = h - 1
+
+    grid = np.empty((h, w), dtype=object)
+    grid.fill(" ")
+
+    max_abs = np.max(np.abs(x_new))
+    normalized = (
+        midpoint + (x_new / max_abs) * scale_range
+        if max_abs != 0
+        else np.full_like(x_new, midpoint)
+    )
+
+    grid[midpoint, :] = middle_point
+
+    for col in range(w):
+        val = normalized[col]
+        remainder = val % 1
+        if val > midpoint:
+            solid_height = int(val - midpoint)
+            solid_row = midpoint - solid_height
+            grid[solid_row:midpoint, col] = BLOCKS[-1]
+            if solid_row > 0:
+                grid[solid_row - 1, col] = BLOCKS[
+                    int(remainder * len(BLOCKS)) % len(BLOCKS)
+                ]
+        elif val < midpoint:
+            solid_height = int(midpoint - val)
+            solid_row = midpoint + solid_height
+            grid[midpoint:solid_row, col] = IBLOCKS[-1]
+            if solid_row < h:
+                grid[solid_row, col] = IBLOCKS[
+                    int((1 - remainder) * len(IBLOCKS)) % len(IBLOCKS)
+                ]
+
+    return f"{color}{chr(10).join(''.join(row) for row in grid)}{COLORS['RESET']}"