uscript 1.6.4__py3-none-any.whl

hoodlib/__init__.py

@@ -0,0 +1,9 @@
+"""hoodlib — the small standard library that ships with U-Script.
+
+Only what Python's own library doesn't already give you in one call. Everything
+here is standard-library Python: no dependencies, importable from .us or .py.
+
+    from hoodlib import chart, disk
+"""
+
+__all__ = ["chart", "disk"]

hoodlib/chart.py

@@ -0,0 +1,167 @@
+"""hoodlib.chart — plots that fit in a terminal, standard library only.
+
+    from hoodlib import chart
+    holla chart.sparkline([1, 5, 2, 8, 3])        # ⣰⣸⡄   (Braille: 2 points per cell, 4 levels)
+    holla chart.bar_chart({"corn": 12, "beans": 7}, title="Bag")
+    holla chart.histogram(samples, bins=8)
+
+Everything returns a string; nothing writes to the terminal for you, so the
+output can be logged, tested, or `holla`'d. Colour is off unless you ask
+(`color=True`), and then it is plain ANSI, no dependency.
+
+Errors are the Python exceptions the crash reporter already explains: an empty
+series is a `ValueError` (BadValueTrip) that says so; a non-number is a
+`TypeError` (WrongKindTrip) that names the offending value.
+"""
+
+from __future__ import annotations
+
+import math
+import shutil
+from collections.abc import Iterable, Mapping, Sequence
+
+__all__ = ["sparkline", "bar_chart", "histogram", "show_bag", "BLOCKS"]
+
+# Braille cell: 2 columns × 4 rows. Bits, bottom-up, per column.
+_LEFT = (0x40, 0x04, 0x02, 0x01)     # dots 7, 3, 2, 1
+_RIGHT = (0x80, 0x20, 0x10, 0x08)    # dots 8, 6, 5, 4
+BLOCKS = "▁▂▃▄▅▆▇█"                  # the 1-column-per-point alternative
+
+_RESET = "\x1b[0m"
+_PALETTE = ("\x1b[36m", "\x1b[32m", "\x1b[33m", "\x1b[35m", "\x1b[34m", "\x1b[31m")
+
+
+def _numbers(data: Iterable[object], what: str) -> list[float]:
+    out: list[float] = []
+    for i, v in enumerate(data):
+        if isinstance(v, bool) or not isinstance(v, (int, float)):
+            raise TypeError(f"{what} needs numbers, but item {i} is {v!r} ({type(v).__name__})")
+        f = float(v)
+        if not math.isfinite(f):
+            raise ValueError(f"{what} can't plot {v!r} (item {i}): every value must be a finite number")
+        out.append(f)
+    if not out:
+        raise ValueError(f"{what} got an empty series; there is nothing to plot")
+    return out
+
+
+def _levels(values: Sequence[float], steps: int) -> list[int]:
+    """Scale each value to 1..steps: the minimum still shows one dot, so every
+    point is visible. A flat series sits in the middle."""
+    lo, hi = min(values), max(values)
+    if hi == lo:
+        return [(steps + 1) // 2 for _ in values]
+    span = hi - lo
+    return [1 + min(steps - 1, int(round((v - lo) / span * (steps - 1)))) for v in values]
+
+
+def _term_width(default: int = 80) -> int:
+    try:
+        return shutil.get_terminal_size((default, 24)).columns
+    except (AttributeError, ValueError, OSError):
+        return default
+
+
+def _paint(text: str, i: int, color: bool) -> str:
+    return f"{_PALETTE[i % len(_PALETTE)]}{text}{_RESET}" if color else text
+
+
+# --------------------------------------------------------------------------- sparkline
+
+def sparkline(data: Iterable[object], *, style: str = "braille", width: int | None = None) -> str:
+    """One line for a series. `braille` packs two points per character on a
+    4-dot scale (so 80 columns show 160 points); `blocks` uses one ▁▂▃ block
+    per point. `width` caps the output in characters; the series is resampled
+    (by picking evenly spaced points) rather than cut off."""
+    values = _numbers(data, "sparkline()")
+    if style not in ("braille", "blocks"):
+        raise ValueError(f"sparkline() style must be 'braille' or 'blocks', not {style!r}")
+    per_char = 2 if style == "braille" else 1
+    if width is not None:
+        if width < 1:
+            raise ValueError("sparkline() width must be at least 1 character")
+        cap = width * per_char
+        if len(values) > cap:
+            step = (len(values) - 1) / (cap - 1) if cap > 1 else 0
+            values = [values[int(round(k * step))] for k in range(cap)]
+    if style == "blocks":
+        return "".join(BLOCKS[n - 1] for n in _levels(values, len(BLOCKS)))
+    levels = _levels(values, 4)
+    if len(levels) % 2:
+        levels.append(-1)                      # odd count: last cell's right column stays empty
+    cells = []
+    for a, b in zip(levels[0::2], levels[1::2], strict=True):
+        bits = 0
+        for k in range(a):
+            bits |= _LEFT[k]
+        for k in range(max(b, 0)):
+            bits |= _RIGHT[k]
+        cells.append(chr(0x2800 + bits))
+    return "".join(cells)
+
+
+# --------------------------------------------------------------------------- bar chart
+
+def bar_chart(values: Mapping[str, object], *, title: str | None = None, width: int | None = None,
+              color: bool = False, sort: bool = False, fill: str = "█") -> str:
+    """Horizontal bars, one per key, labels left-aligned and values shown at
+    the end of each bar. Bars scale to the longest so the chart fits `width`
+    columns (default: the terminal). Negative values draw an empty bar with
+    the number, rather than pretending they are zero."""
+    if not values:
+        raise ValueError("bar_chart() got an empty mapping; there is nothing to plot")
+    nums = _numbers(values.values(), "bar_chart()")
+    items = list(zip((str(k) for k in values), nums, strict=True))
+    if sort:
+        items.sort(key=lambda kv: kv[1], reverse=True)
+    width = width or _term_width()
+    label_w = max(len(k) for k, _ in items)
+    num_strs = [_fmt(v) for _, v in items]
+    num_w = max(len(s) for s in num_strs)
+    bar_w = max(4, width - label_w - num_w - 4)   # "label │bar value"
+    top = max(v for _, v in items)
+    lines = []
+    if title:
+        lines.append(title)
+        lines.append("─" * min(width, max(len(title), label_w + bar_w + num_w + 4)))
+    for i, ((label, v), s) in enumerate(zip(items, num_strs, strict=True)):
+        n = int(round(v / top * bar_w)) if top > 0 and v > 0 else 0
+        bar = _paint(fill * n, i, color)
+        lines.append(f"{label.ljust(label_w)} │{bar}{' ' * (bar_w - n)} {s.rjust(num_w)}")
+    return "\n".join(lines)
+
+
+def _fmt(v: float) -> str:
+    return str(int(v)) if v == int(v) else f"{v:.2f}"
+
+
+# --------------------------------------------------------------------------- histogram
+
+def histogram(data: Iterable[object], *, bins: int = 10, width: int | None = None,
+              color: bool = False, fill: str = "█") -> str:
+    """Counts per equal-width bin, drawn as a bar chart whose labels are the bin
+    ranges. `bins` must be at least 1; a flat series gets one bin."""
+    values = _numbers(data, "histogram()")
+    if bins < 1:
+        raise ValueError("histogram() needs at least 1 bin")
+    lo, hi = min(values), max(values)
+    if hi == lo:
+        return bar_chart({f"{_fmt(lo)}": len(values)}, width=width, color=color, fill=fill)
+    edges = [lo + (hi - lo) * k / bins for k in range(bins + 1)]
+    counts = [0] * bins
+    for v in values:
+        k = min(bins - 1, int((v - lo) / (hi - lo) * bins))
+        counts[k] += 1
+    labels = {f"{_fmt(edges[k])}–{_fmt(edges[k + 1])}": counts[k] for k in range(bins)}
+    return bar_chart(labels, width=width, color=color, fill=fill)
+
+
+# --------------------------------------------------------------------------- games
+
+def show_bag(bag: Mapping[str, object], *, title: str = "Bag", **kw: object) -> str:
+    """The farm drone's `bot.bag` (or any inventory mapping) as a bar chart.
+    An empty bag is a line saying so, not an error — an empty inventory is a
+    normal game state."""
+    if not bag:
+        return f"{title}: empty"
+    return bar_chart(bag, title=title, **kw)  # type: ignore[arg-type]

hoodlib/disk.py

@@ -0,0 +1,177 @@
+"""hoodlib.disk — files that don't get corrupted.
+
+Atomic, thread-safe JSON and CSV read/write with backups. Every write goes to a
+temp file in the same directory, is flushed and fsynced, then renamed over the
+target (os.replace is atomic on every platform Python supports), so a crash or
+a second writer can never leave a half-written file. One lock per path keeps
+threads in one process from interleaving.
+
+Errors are the Python exceptions U-Script already explains: FileNotFoundError
+(MissingFileTrip), PermissionError (NoAccessTrip), ValueError (BadValueTrip) for
+malformed content.
+
+    from hoodlib import disk
+    disk.write_json("scores.json", {"khris": 42})
+    data = disk.read_json("scores.json", default={})
+    disk.append_csv("log.csv", ["2026-09-12", "win"], header=["date", "result"])
+    rows = disk.read_csv("log.csv")          # list of dicts
+    disk.backup("scores.json")               # scores.json.2026-09-12T10-30-00.bak
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import os
+import shutil
+import threading
+from collections.abc import Iterable, Sequence
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+__all__ = ["read_json", "write_json", "read_csv", "write_csv", "append_csv", "write_text", "backup", "atomic_write"]
+
+_LOCKS: dict[str, threading.Lock] = {}
+_LOCKS_GUARD = threading.Lock()
+_MISSING = object()
+
+
+def _lock_for(path: Path) -> threading.Lock:
+    key = str(path.resolve())
+    with _LOCKS_GUARD:
+        lock = _LOCKS.get(key)
+        if lock is None:
+            lock = _LOCKS[key] = threading.Lock()
+        return lock
+
+
+def atomic_write(path: str | os.PathLike[str], data: str | bytes, *, encoding: str = "utf-8") -> Path:
+    """Write `data` to `path` atomically: readers see the old file or the new one, never a mix."""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    payload = data.encode(encoding) if isinstance(data, str) else data
+    with _lock_for(target):
+        tmp = target.with_name(f".{target.name}.tmp.{os.getpid()}.{threading.get_ident()}")
+        try:
+            with open(tmp, "wb") as fh:
+                fh.write(payload)
+                fh.flush()
+                os.fsync(fh.fileno())
+            os.replace(tmp, target)
+        finally:
+            if tmp.exists():
+                tmp.unlink(missing_ok=True)
+    return target
+
+
+def write_text(path: str | os.PathLike[str], text: str, *, encoding: str = "utf-8") -> Path:
+    """Atomic text write."""
+    return atomic_write(path, text, encoding=encoding)
+
+
+def read_json(path: str | os.PathLike[str], default: Any = _MISSING) -> Any:
+    """Read a JSON file. With `default`, a missing file returns it instead of raising.
+    Malformed JSON raises ValueError naming the file and the position."""
+    target = Path(path)
+    with _lock_for(target):
+        try:
+            text = target.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            if default is not _MISSING:
+                return default
+            raise
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"{target.name} is not valid JSON: {e.msg} (line {e.lineno}, column {e.colno})") from None
+
+
+def write_json(path: str | os.PathLike[str], data: Any, *, indent: int = 2, sort_keys: bool = False) -> Path:
+    """Serialize `data` and write it atomically. Non-JSON values raise ValueError
+    naming the offending type, not Python's `TypeError: Object of type X is not
+    JSON serializable`."""
+    try:
+        text = json.dumps(data, indent=indent, sort_keys=sort_keys, ensure_ascii=False) + "\n"
+    except TypeError as e:
+        raise ValueError(f"can't save this to JSON: {e}") from None
+    return atomic_write(path, text)
+
+
+def read_csv(path: str | os.PathLike[str], *, header: bool = True) -> list[dict[str, str]] | list[list[str]]:
+    """Read a CSV file: a list of dicts when it has a header row (default), else a
+    list of lists. A missing file raises FileNotFoundError."""
+    target = Path(path)
+    with _lock_for(target), open(target, encoding="utf-8", newline="") as fh:   # newline="" per the csv docs
+        text = fh.read()
+    if header:
+        return list(csv.DictReader(io.StringIO(text)))
+    return list(csv.reader(io.StringIO(text)))
+
+
+def write_csv(path: str | os.PathLike[str], rows: Iterable[Sequence[Any] | dict[str, Any]],
+              *, header: Sequence[str] | None = None) -> Path:
+    """Write rows atomically. Rows may be sequences or dicts; with dicts the header is
+    taken from the first row's keys when not given."""
+    rows = list(rows)
+    buf = io.StringIO(newline="")
+    if rows and isinstance(rows[0], dict):
+        fields = list(header) if header is not None else list(rows[0].keys())
+        writer = csv.DictWriter(buf, fieldnames=fields, lineterminator="\n")
+        writer.writeheader()
+        for row in rows:
+            if not isinstance(row, dict):
+                raise ValueError("write_csv: mixed dict and list rows")
+            writer.writerow(row)
+    else:
+        writer = csv.writer(buf, lineterminator="\n")
+        if header is not None:
+            writer.writerow(list(header))
+        for row in rows:
+            if isinstance(row, dict):
+                raise ValueError("write_csv: mixed dict and list rows")
+            writer.writerow(list(row))
+    return atomic_write(path, buf.getvalue())
+
+
+def append_csv(path: str | os.PathLike[str], row: Sequence[Any] | dict[str, Any],
+               *, header: Sequence[str] | None = None) -> Path:
+    """Append one row. Creates the file (with `header`, if given) when it doesn't
+    exist. The whole file is rewritten atomically, so a crash mid-append leaves
+    the previous complete file, never a torn line."""
+    target = Path(path)
+    existing: list[list[str]] = []
+    if target.exists():
+        existing = read_csv(target, header=False)  # type: ignore[assignment]
+    elif header is not None:
+        existing = [list(header)]
+    if isinstance(row, dict):
+        fields = existing[0] if existing else (list(header) if header else list(row.keys()))
+        if not existing:
+            existing = [list(fields)]
+        existing.append([str(row.get(f, "")) for f in fields])
+    else:
+        existing.append([str(v) for v in row])
+    return write_csv(target, existing)
+
+
+def backup(path: str | os.PathLike[str], *, keep: int | None = None) -> Path:
+    """Copy `path` to `<name>.<timestamp>.bak` next to it and return the copy.
+    With `keep=N`, only the N newest backups of that file are retained."""
+    target = Path(path)
+    if not target.exists():
+        raise FileNotFoundError(f"[Errno 2] No such file or directory: '{target}'")
+    stamp = datetime.now().strftime("%Y-%m-%dT%H-%M-%S")
+    dest = target.with_name(f"{target.name}.{stamp}.bak")
+    n = 0
+    with _lock_for(target):
+        while dest.exists():
+            n += 1
+            dest = target.with_name(f"{target.name}.{stamp}-{n}.bak")
+        shutil.copy2(target, dest)
+        if keep is not None:
+            old = sorted(target.parent.glob(f"{target.name}.*.bak"), key=lambda p: p.stat().st_mtime)
+            for stale in old[:-keep] if keep > 0 else old:
+                stale.unlink(missing_ok=True)
+    return dest

uarcade/__init__.py

@@ -0,0 +1,9 @@
+"""U-Script Cultural Arcade Engine (uarcade).
+
+Gamified terminal programming learning suite celebrating Black pop culture:
+- Big Mama's Cookout: The Spades & Grill Protocol
+- BeatLab 808: The MPC Matrix
+- Drop Day: Sole Runner & Deadstock Logistics
+"""
+
+__version__ = "1.0.0"