gridhour 0.1.0__py3-none-any.whl

gridhour/__init__.py

@@ -0,0 +1,3 @@
+"""gridhour: when British electricity is green and cheap, in the terminal."""
+
+__version__ = "0.1.0"

gridhour/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

gridhour/app.py

@@ -0,0 +1,224 @@
+"""The interactive session.
+
+Everything that can happen arrives as an event on one queue: key presses from a reader thread,
+"resize" from the SIGWINCH handler, "data" when a background fetch finishes, and a "tick" when
+the queue stays quiet until the next whole second. The main loop takes one event, updates the
+state, draws a frame and writes only the rows that differ from the previous frame.
+"""
+import os
+import queue
+import shutil
+import signal
+import sys
+import threading
+import time
+from datetime import UTC, datetime
+
+from .compose import compose
+from .grid import load
+from .keys import handle_key
+from .themes import C
+
+RELOAD = 5 * 60         # rebuild the window from cache this often; the network is hit only when it is stale
+
+
+def utcnow():
+    return datetime.now(UTC)
+
+
+# ---------------------------------------------------------------- background data
+
+_fetch_lock = threading.Lock()
+
+
+def fetch(st, force=False, notify=None):
+    """Load in a thread. Routine refreshes are skipped while one is running; a forced one (new
+    postcode, R) always starts, and the newest request wins."""
+    with _fetch_lock:
+        if st.loading and not force:
+            return
+        st.gen += 1
+        gen = st.gen
+        st.loading = True
+
+    def work():
+        fc, failure = None, None
+        try:
+            fc = load(utcnow(), st.postcode, st.region_id, st.gsp, st.prices, force=force)
+        except Exception as e:  # noqa: BLE001 - a background failure must reach the status line, not stderr
+            failure = "update failed (%s)" % type(e).__name__
+        with _fetch_lock:
+            if gen == st.gen:
+                if fc is not None:
+                    st.fc = fc
+                    if fc.errors:
+                        st.say(fc.errors[0], C.AMBER, 6)
+                    elif force:
+                        st.say("forecast updated", C.GREEN)
+                else:
+                    st.say(failure, C.RED, 8)
+                st.loading = False
+        if notify:
+            notify("data")
+
+    threading.Thread(target=work, name="gridhour-fetch", daemon=True).start()
+
+
+# ---------------------------------------------------------------- keyboard
+
+class KeyDecoder:
+    """Cuts a byte stream into keys: plain characters, CSI sequences (ESC [ ... final) and
+    SS3 sequences (ESC O x). A sequence split across two reads is held until it is complete;
+    an ESC with nothing after it in the same read is the Escape key itself."""
+
+    def __init__(self):
+        self.pending = ""
+
+    def feed(self, text):
+        self.pending += text
+        keys = []
+        while self.pending:
+            key, used = self._next(self.pending)
+            if used == 0:
+                break               # an unfinished sequence, wait for more bytes
+            keys.append(key)
+            self.pending = self.pending[used:]
+        return keys
+
+    def flush(self):
+        """Whatever is still pending is taken literally (a lone ESC, say)."""
+        keys = list(self.pending)
+        self.pending = ""
+        return keys
+
+    @staticmethod
+    def _next(s):
+        if s[0] != "\x1b":
+            return s[0], 1
+        if len(s) == 1:
+            return None, 0
+        if s[1] == "O":
+            return (s[:3], 3) if len(s) >= 3 else (None, 0)
+        if s[1] != "[":
+            return "\x1b", 1        # ESC followed by an ordinary key: two keys
+        for j in range(2, len(s)):
+            if "\x40" <= s[j] <= "\x7e":
+                return s[:j + 1], j + 1
+        return None, 0
+
+
+def read_keys(fd, events):
+    """Reader thread: decoded keys go onto the event queue."""
+    dec = KeyDecoder()
+    while True:
+        try:
+            data = os.read(fd, 1024)
+        except OSError:
+            return
+        if not data:
+            return
+        for k in dec.feed(data.decode("utf-8", "ignore")):
+            events.put(("key", k))
+        if dec.pending == "\x1b":       # nothing followed the ESC in this read
+            for k in dec.flush():
+                events.put(("key", k))
+
+
+# ---------------------------------------------------------------- terminal
+
+class Terminal:
+    """Cbreak mode on the alternate screen with the cursor hidden; all of it undone on exit."""
+
+    # autowrap off (?7l): if a row is ever wider than the terminal it is cut, not wrapped and scrolled
+    ENTER = "\x1b[?1049h\x1b[?25l\x1b[?7l\x1b[2J"
+    LEAVE = "\x1b[0m\x1b[?7h\x1b[?25h\x1b[?1049l"
+
+    def __init__(self, fd, out):
+        self.fd, self.out, self.saved = fd, out, None
+
+    def __enter__(self):
+        import termios
+        import tty
+        self.saved = termios.tcgetattr(self.fd)
+        tty.setcbreak(self.fd)
+        self.out.write(self.ENTER)
+        self.out.flush()
+        return self
+
+    def __exit__(self, *exc):
+        import termios
+        termios.tcsetattr(self.fd, termios.TCSADRAIN, self.saved)
+        self.out.write(self.LEAVE)
+        self.out.flush()
+        return False
+
+
+class Screen:
+    """Remembers what is on screen and sends only the rows that changed, in one write."""
+
+    def __init__(self, out):
+        self.out = out
+        self.shown = []
+        self.size = None
+
+    def show(self, lines, size):
+        parts = []
+        if size != self.size:
+            parts.append("\x1b[2J")
+            self.shown, self.size = [], size
+        for y, line in enumerate(lines):
+            if y >= len(self.shown) or self.shown[y] != line:
+                parts.append("\x1b[%d;1H" % (y + 1) + line)
+        if parts:
+            self.out.write("".join(parts))
+            self.out.flush()
+        self.shown = lines
+
+
+# ---------------------------------------------------------------- loop
+
+def run(st):
+    fd, out = sys.stdin.fileno(), sys.stdout
+    # SimpleQueue.put is reentrant, so the SIGWINCH handler may call it while the main thread is
+    # inside get(); a plain Queue would deadlock on its own lock there.
+    events = queue.SimpleQueue()
+    previous = signal.signal(signal.SIGWINCH, lambda *a: events.put(("resize", None)))
+    try:
+        with Terminal(fd, out):
+            threading.Thread(target=read_keys, args=(fd, events), name="gridhour-keys", daemon=True).start()
+            _loop(st, events, Screen(out))
+    finally:
+        signal.signal(signal.SIGWINCH, previous if previous is not None else signal.SIG_DFL)
+
+
+def _loop(st, events, screen):
+    notify = lambda kind: events.put((kind, None))  # noqa: E731
+    fetch(st, notify=notify)
+    reloaded, hour = time.monotonic(), utcnow().hour
+    while True:
+        live = utcnow()
+        if time.monotonic() - reloaded > RELOAD or live.hour != hour:
+            reloaded, hour = time.monotonic(), live.hour
+            fetch(st, notify=notify)
+        W, H = shutil.get_terminal_size((100, 30))
+        now = st.frozen or live.replace(microsecond=0)
+        screen.show(compose(W, H, st, now, live.replace(microsecond=0)).lines(), (W, H))
+        try:
+            kind, value = events.get(timeout=max(0.05, 1.0 - live.microsecond / 1e6))
+        except queue.Empty:
+            continue                                    # the clock ticked, draw again
+        batch = [(kind, value)]
+        while True:                                     # take everything already waiting, draw once
+            try:
+                batch.append(events.get_nowait())
+            except queue.Empty:
+                break
+        for kind, value in batch:
+            if kind != "key":
+                continue
+            action = handle_key(st, value, utcnow())
+            if action == "quit":
+                return
+            if action in ("fetch", "refetch"):
+                reloaded = time.monotonic()
+                fetch(st, force=action == "refetch", notify=notify)

gridhour/canvas.py

@@ -0,0 +1,108 @@
+"""An off-screen frame: a grid of cells that turns into ANSI text.
+
+Each cell holds a character, a foreground, a background and a bold flag. When the frame is
+turned into text, an emitter tracks the terminal's current attributes and writes only the ones
+that change from one cell to the next, so a run of same-coloured cells costs one escape code.
+"""
+import re
+from dataclasses import dataclass
+
+from .themes import C
+
+# C0 and C1 control characters, DEL included. Text from the network or the config file goes through
+# put(), so an ESC in a region name or an error message can never reach the terminal as a sequence.
+UNSAFE = re.compile(r"[\x00-\x1f\x7f-\x9f]")
+
+
+def clean(text):
+    return UNSAFE.sub("?", str(text))
+
+
+@dataclass
+class Cell:
+    char: str = " "
+    fg: tuple = None
+    bg: tuple = None
+    bold: bool = False
+
+
+class Canvas:
+    def __init__(self, w, h):
+        self.w, self.h = w, h
+        self.rows = [[Cell(bg=C.BG) for _ in range(w)] for _ in range(h)]
+
+    def cell(self, x, y):
+        """The cell at (x, y), or None off the edge."""
+        if 0 <= y < self.h and 0 <= x < self.w:
+            return self.rows[y][x]
+        return None
+
+    def bg_at(self, x, y):
+        c = self.cell(x, y)
+        return c.bg if c else C.BG
+
+    def put(self, x, y, text, fg=None, bg=None, bold=False):
+        """Write ``text`` from (x, y) rightwards. ``bg=None`` keeps each cell's own background."""
+        for i, ch in enumerate(clean(text)):
+            c = self.cell(x + i, y)
+            if c is None:
+                continue
+            c.char, c.fg, c.bold = ch, fg, bold
+            if bg is not None:
+                c.bg = bg
+
+    def fill(self, x, y, w, bg):
+        """Blank ``w`` cells and give them background ``bg``."""
+        for i in range(w):
+            c = self.cell(x + i, y)
+            if c is not None:
+                c.char, c.fg, c.bg, c.bold = " ", None, bg, False
+
+    def tint(self, x, y, bg):
+        """Change only the background of one cell."""
+        c = self.cell(x, y)
+        if c is not None:
+            c.bg = bg
+
+    def text(self):
+        """The characters alone, one string per row (for tests)."""
+        return ["".join(c.char for c in row) for row in self.rows]
+
+    def lines(self):
+        """One ANSI string per row. Every row starts and ends with attributes reset."""
+        return [_Emitter().row(row) for row in self.rows]
+
+
+class _Emitter:
+    """Writes cells while remembering what the terminal is already set to."""
+
+    def __init__(self):
+        self.fg = self.bg = None        # None is the terminal default, which is what reset leaves
+        self.bold = False
+        self.out = ["\x1b[0m"]
+
+    def row(self, cells):
+        for c in cells:
+            self.style(c)
+            self.out.append(c.char)
+        self.out.append("\x1b[0m")
+        return "".join(self.out)
+
+    def style(self, c):
+        codes = []
+        if c.bold != self.bold:
+            # there is no portable "bold off" that leaves colours alone, so a change resets
+            if self.bold:
+                codes.append("0")
+                self.fg = self.bg = None
+            else:
+                codes.append("1")
+            self.bold = c.bold
+        if c.fg != self.fg:
+            codes.append("39" if c.fg is None else "38;2;%d;%d;%d" % c.fg)
+            self.fg = c.fg
+        if c.bg != self.bg:
+            codes.append("49" if c.bg is None else "48;2;%d;%d;%d" % c.bg)
+            self.bg = c.bg
+        if codes:
+            self.out.append("\x1b[" + ";".join(codes) + "m")

gridhour/cli.py

@@ -0,0 +1,126 @@
+"""Command line entry point."""
+import argparse
+import os
+import re
+import shutil
+import sys
+
+from . import __version__
+from .app import run, utcnow
+from .compose import MAX_H, MAX_W, compose
+from .grid import cache_dir, load, normalize_postcode, parse_time, region_from_arg
+from .output import json_output, line_output, watch
+from .plan import MODES, parse_job
+from .state import config_path, state_from_config
+from .themes import THEME_ORDER, apply_theme
+
+
+def parse_size(text):
+    m = re.fullmatch(r"([0-9]{1,4})x([0-9]{1,4})", text.strip().lower())
+    if not m:
+        raise ValueError("--size looks like 120x40")
+    W, H = int(m.group(1)), int(m.group(2))
+    if not (40 <= W <= MAX_W and 8 <= H <= MAX_H):
+        raise ValueError("--size must be between 40x8 and %dx%d" % (MAX_W, MAX_H))
+    return W, H
+
+
+def reset():
+    """Delete the config and the cache (cache file names contain the postcode)."""
+    gone = 0
+    paths = [config_path()]
+    try:
+        paths += [os.path.join(cache_dir(), n) for n in os.listdir(cache_dir())
+                  if n.endswith(".json") and (n.startswith(("carbon-", "prices-", "agile-", ".tmp-")))]
+    except OSError:
+        pass
+    for p in paths:
+        try:
+            os.remove(p)
+            gone += 1
+        except FileNotFoundError:
+            pass
+        except OSError as e:
+            print("gridhour: could not remove %s: %s" % (p, e.strerror), file=sys.stderr)
+    print("gridhour: saved settings and cache removed" if gone else "gridhour: nothing to reset")
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="gridhour",
+                                 description="When British electricity is green and cheap: a 48 hour carbon and "
+                                             "Agile price timeline for the terminal.")
+    ap.add_argument("postcode", nargs="*", help="your postcode, full or the first half (remembered)")
+    ap.add_argument("--region", help="a region instead of a postcode: 1-18, an Agile letter A-P, or a name")
+    ap.add_argument("--no-prices", action="store_true", help="carbon only, skip Octopus Agile prices")
+    ap.add_argument("--mode", choices=MODES, help="rank windows by carbon, price or both")
+    ap.add_argument("--at", help="freeze the clock at this time (ISO 8601, UTC unless it has an offset)")
+    ap.add_argument("--line", action="store_true", help="print one line for a status bar and exit")
+    ap.add_argument("--best", metavar="DURATION", help="with --line/--watch: the best start for a job this long")
+    ap.add_argument("--tmux", action="store_true", help="like --line with tmux colour codes")
+    ap.add_argument("--watch", action="store_true", help="the one-liner, updating in place")
+    ap.add_argument("--json", action="store_true", help="print JSON and exit")
+    ap.add_argument("--once", action="store_true", help="print one frame of the full UI and exit")
+    ap.add_argument("--size", help="WxH for --once (default: terminal size)")
+    ap.add_argument("--theme", choices=THEME_ORDER, help="colour theme")
+    ap.add_argument("--12h", dest="h12", action="store_true", help="12-hour clock")
+    ap.add_argument("--compact", action="store_true", help="small-pane layout without the chart")
+    ap.add_argument("--reset", action="store_true", help="forget saved settings and jobs")
+    ap.add_argument("--version", action="version", version="gridhour " + __version__)
+    args = ap.parse_args(argv)
+    if args.reset:
+        reset()
+        return
+    st = state_from_config()
+    try:
+        if args.postcode:
+            st.postcode = normalize_postcode(" ".join(args.postcode))
+            st.region_id = None
+            st.save()
+        if args.region:
+            st.region_id = region_from_arg(args.region)
+            st.postcode = None
+            st.persist = False
+        best = parse_job("job " + args.best) if args.best else None
+        at = parse_time(args.at) if args.at else None
+        if at and not 2000 <= at.year <= 2100:
+            raise ValueError("--at must be between the years 2000 and 2100")
+        size = parse_size(args.size) if args.size else None
+    except ValueError as e:
+        sys.exit("gridhour: %s" % e)
+    if args.no_prices:
+        st.prices = False
+    if args.mode:
+        st.mode = args.mode
+    if args.theme:
+        apply_theme(args.theme)
+    if args.h12:
+        st.h12 = True
+    if args.compact:
+        st.compact = "on"
+    if args.watch:
+        watch(st, utcnow, "ansi" if sys.stdout.isatty() else "plain", best)
+        return
+    if args.line or args.tmux or args.json or args.once:
+        now = at or utcnow().replace(microsecond=0)
+        st.fc = load(now, st.postcode, st.region_id, st.gsp, st.prices)
+        if args.json:
+            print(json_output(st, now))
+        elif args.once:
+            W, H = size or shutil.get_terminal_size((120, 40))
+            print("\n".join(compose(W, H, st, now, now).lines()))
+        else:
+            color = "tmux" if args.tmux else ("ansi" if sys.stdout.isatty() else "plain")
+            print(line_output(st, now, color, best))
+        return
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        sys.exit("gridhour: needs an interactive terminal (use --once, --line or --json otherwise)")
+    if at:
+        st.frozen = at
+    try:
+        run(st)
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()