screenbuffer 0.1.0__py3-none-any.whl

screenbuffer/__init__.py

@@ -0,0 +1,4 @@
+from .align import align_text
+from .buffer import ScreenBuffer
+
+__all__ = ["ScreenBuffer", "align_text"]

screenbuffer/align.py

@@ -0,0 +1,58 @@
+"""Text alignment helper (no dependencies, easy to unit-test)."""
+import shutil
+import unicodedata
+
+
+def terminal_width():
+    return shutil.get_terminal_size().columns
+
+
+# Width of text as the terminal shows it (emoji and CJK take 2 columns,
+# combining marks take 0), used to pad lines with trailing spaces.
+def _char_width(ch):
+    if unicodedata.category(ch) in ("Mn", "Me", "Cf", "Cc"):
+        return 0
+    return 2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1
+
+
+def display_width(text):
+    return sum(_char_width(ch) for ch in text)
+
+
+def align_text(text, alignment=None, width=None):
+    """Align `text` inside `width` columns (defaults to the terminal width).
+
+    alignment:
+      None / 'left'   -> unchanged
+      'center'        -> centred
+      'right'         -> right-justified
+      int  >= 0       -> that many spaces of left indent
+      int  <  0       -> ends that many columns from the right edge
+      numeric string  -> treated like the int ("5", "-10")
+    """
+    if width is None:
+        width = terminal_width()
+
+    if alignment is None:
+        alignment = "left"
+
+    if isinstance(alignment, str):
+        alignment = alignment.strip()
+        if alignment.lstrip("-").isdigit():
+            alignment = int(alignment)
+
+    if isinstance(alignment, int):
+        if alignment >= 0:
+            return " " * alignment + text
+        end_col = width + alignment
+        start_col = max(0, end_col - len(text))
+        return " " * start_col + text
+
+    if isinstance(alignment, str):
+        keyword = alignment.lower()
+        if keyword == "center":
+            return text.center(width)
+        if keyword == "right":
+            return text.rjust(width)
+
+    return text

screenbuffer/buffer.py

@@ -0,0 +1,568 @@
+"""ScreenBuffer: state, public API and display.
+
+Alignment lives in align.py, file I/O in store.py, and filtering/trimming
+in view.py. This class just ties them together.
+
+Built for Jupyter. display() uses the notebook's own clear_output(wait=True):
+the old output stays on screen until the new text is ready, then the two are
+swapped, so there is no flicker. The new text is exactly what get_text()
+returns (each line aligned, your spacing untouched).
+
+Smooth by design:
+  * The new text is flushed straight away, so the swap happens at once.
+  * A redraw is skipped when nothing on screen would change.
+  * `with sb.batch():` turns several changes into ONE redraw.
+  * Only the max_display window is built when drawing, so a frame costs the
+    same for 100 lines or 100,000.
+  * Disk writes never block drawing: they are queued in order and written
+    outside the buffer lock. Appending a line appends to the files (it does not
+    rewrite them), and the history trim only reads the file when it is over limit.
+"""
+import collections
+import contextlib
+import os
+import threading
+from datetime import datetime
+
+from .align import align_text, terminal_width
+from .store import LogStore
+from .view import build_view, validate_selector
+
+try:
+    from IPython.display import clear_output
+except ImportError:  # not running where IPython exists (plain script): no clearing
+    def clear_output(wait=False):
+        pass
+
+
+class ScreenBuffer:
+    EMOJI_STATES = {
+        0: "🟢",
+        1: "🟡",
+        2: "🔴",
+    }
+
+    FILLER = "<<FILLER>>"
+
+    _PLAIN_SETTINGS = {
+        "wait", "max_main", "max_wait", "max_display", "shift_max_display",
+        "auto_clean_edges", "auto_clean_silent_only_display",
+        "header_alignment", "footer_alignment", "width",
+    }
+
+    def __init__(
+        self,
+        wait=True,
+        log_file=None,
+        max_main=None,
+        max_wait=None,
+        max_display=None,
+        start=False,
+        header=None,
+        header_alignment=None,
+        footer=None,
+        footer_alignment=None,
+        show_header=None,
+        show_footer=None,
+        silent_display=None,
+        only_display=None,
+        auto_clean_edges=False,
+        auto_clean_silent_only_display=False,
+        shift_max_display=True,
+        width=None,
+    ):
+        # State first, so nothing can run display() before it exists.
+        self.buffer = []
+        self.alignments = {}
+        self.buffer_lock = threading.RLock()
+        self.display_lock = threading.RLock()
+
+        self._last_text = None          # what the screen shows now (skip identical redraws)
+        self._batch_depth = 0           # >0 while inside `with sb.batch():`
+        self._batch_dirty = False
+        self._batch_lock = threading.Lock()
+
+        # Disk writes are queued (in buffer order) and run outside buffer_lock.
+        self._jobs = collections.deque()
+        self._io_lock = threading.Lock()
+        # Lines the wait file will hold once the queued writes have run.
+        # None = unknown, so the next change rewrites the file in full.
+        self._wait_n = None
+
+        self.wait = wait
+
+        if silent_display is not None and only_display is not None:
+            raise ValueError("silent_display and only_display cannot be used simultaneously")
+        self.silent_display = validate_selector(silent_display, "silent_display")
+        self.only_display = validate_selector(only_display, "only_display")
+
+        self.max_main = max_main
+        self.max_wait = max_wait
+        self.max_display = max_display
+        self.shift_max_display = shift_max_display
+
+        # None = detect the terminal width; set it if your environment
+        # reports the wrong one (alignment 'center'/'right' depends on it)
+        self.width = width
+
+        self.auto_clean_edges = auto_clean_edges
+        self.auto_clean_silent_only_display = auto_clean_silent_only_display
+
+        self._check_limits(self.max_wait, self.max_display)
+
+        # header/footer that are memory-only (set with save_to_file=False)
+        self._memory_only = set()
+
+        self.header = header if isinstance(header, str) else None
+        self.footer = footer if isinstance(footer, str) else None
+        self.show_header = show_header if show_header is not None else bool(self.header)
+        self.show_footer = show_footer if show_footer is not None else bool(self.footer)
+        self.header_alignment = header_alignment
+        self.footer_alignment = footer_alignment
+
+        self.store = LogStore(log_file, max_main=max_main, max_wait=max_wait)
+
+        if start:
+            self._reset_all()
+        else:
+            # an explicit header/footer must win over a stale file from an earlier run
+            if self.header is not None:
+                self.store.write_part("header", self.header)
+            if self.footer is not None:
+                self.store.write_part("footer", self.footer)
+        self.refresh_buffer_from_wait_log()
+
+        if not self.wait:
+            self.display()
+
+    # ------------------------------------------------- file-path properties
+    @property
+    def log_file(self):
+        return self.store.log_file
+
+    @property
+    def wait_log_file(self):
+        return self.store.wait_log_file
+
+    @property
+    def header_file(self):
+        return self.store.header_file
+
+    @property
+    def footer_file(self):
+        return self.store.footer_file
+
+    # ---------------------------------------------------------------- helpers
+    @staticmethod
+    def _check_limits(max_wait, max_display):
+        if max_wait is not None and max_display is not None:
+            if max_wait < max_display:
+                raise ValueError("max_wait cannot be less than max_display")
+
+    def _refresh_if_live(self):
+        """Redraw after a change (only in live mode, wait=False)."""
+        if self.wait:
+            return
+        with self._batch_lock:
+            if self._batch_depth:
+                self._batch_dirty = True   # drawn once when the batch ends
+                return
+        self._draw(skip_same=True)
+
+    @contextlib.contextmanager
+    def batch(self):
+        """with sb.batch(): ...  Make several changes and redraw ONCE at the end.
+
+        Without it, every put()/update() in live mode redraws, so a quick run of
+        changes flashes through half-updated screens.
+        """
+        with self._batch_lock:
+            self._batch_depth += 1
+        try:
+            yield self
+        finally:
+            with self._batch_lock:
+                self._batch_depth -= 1
+                redraw = self._batch_depth == 0 and self._batch_dirty
+                if redraw:
+                    self._batch_dirty = False
+            if redraw and not self.wait:
+                self._draw(skip_same=True)
+
+    # ---- ordered, non-blocking disk writes -----------------------------------
+    def _queue_wait_write(self, appended_from=None):
+        """Queue the wait-file write for the change just made. Call with
+        buffer_lock held.
+
+        appended_from=i : lines i.. were just added at the end. If the file is in
+                          step, they are simply appended (cheap).
+        otherwise       : rewrite the file with the newest max_wait lines.
+        """
+        if not self.store.enabled:
+            return
+        n = len(self.buffer)
+        limit = self.max_wait
+        if appended_from is not None and self._wait_n is not None:
+            added = n - appended_from
+            if limit is None or self._wait_n + added <= limit:
+                entries = [
+                    (self.buffer[i], self.alignments.get(i, "left"))
+                    for i in range(appended_from, n)
+                ]
+                self._wait_n += added
+                self._jobs.append(lambda e=entries: self.store.append_wait(e))
+                return
+        if limit is None:
+            start = 0
+        elif limit <= 0:
+            start = n
+        else:
+            start = max(n - limit, 0)
+        entries = [(self.buffer[i], self.alignments.get(i, "left")) for i in range(start, n)]
+        self._wait_n = len(entries)
+        self._jobs.append(lambda e=entries: self.store.write_wait(e))
+
+    def _drain_io(self, block=False):
+        """Write queued jobs in order. If another thread is already writing, it
+        will also write ours, so this returns at once (drawing never waits on disk).
+        block=True waits for that thread, so everything is on disk when it returns."""
+        error = None
+        while True:
+            if not self._io_lock.acquire(blocking=block):
+                break
+            try:
+                while self._jobs:
+                    job = self._jobs.popleft()
+                    try:
+                        job()
+                    except Exception as e:      # keep writing the rest, report the first failure
+                        if error is None:
+                            error = e
+            finally:
+                self._io_lock.release()
+            if not self._jobs:                   # a job may have been queued meanwhile
+                break
+        if error is not None:
+            raise error
+
+    def _wait_io(self):
+        self._drain_io(block=True)
+
+    def _reset_all(self):
+        with self.buffer_lock:
+            self.buffer.clear()
+            self.alignments.clear()
+            if self.store.enabled:
+                self._wait_n = 0   # the files are about to be emptied, so they match
+        self.store.reset_all(self.header or "", self.footer or "")
+
+    def refresh_buffer_from_wait_log(self):
+        """Reload the buffer from the wait log, only if the buffer is empty."""
+        if not self.store.enabled:
+            return
+        entries = self.store.read_wait()
+        if not entries:
+            return
+        with self.buffer_lock:
+            if self.buffer:
+                return
+            self.buffer = [text for text, _ in entries]
+            self.alignments = {
+                i: align for i, (_, align) in enumerate(entries) if align != "left"
+            }
+
+    # ------------------------------------------------------- header / footer
+    def _resolve_part(self, name, current, show):
+        if not show or current is None:
+            return ""
+        if name in self._memory_only:
+            return current
+        stored = self.store.read_part(name)
+        return stored if stored else current
+
+    def get_header(self):
+        """Raw header text ('' when hidden). Alignment is applied at display."""
+        return self._resolve_part("header", self.header, self.show_header)
+
+    def get_footer(self):
+        """Raw footer text ('' when hidden). Alignment is applied at display."""
+        return self._resolve_part("footer", self.footer, self.show_footer)
+
+    def set_header(self, new_header, save_to_file=True, refresh=True):
+        self.header = new_header if isinstance(new_header, str) else None
+        if save_to_file:
+            self.store.write_part("header", self.header)
+            self._memory_only.discard("header")
+        else:
+            self._memory_only.add("header")
+        if self.header:
+            self.show_header = True
+        if refresh:
+            self._refresh_if_live()
+
+    def set_footer(self, new_footer, save_to_file=True, refresh=True):
+        self.footer = new_footer if isinstance(new_footer, str) else None
+        if save_to_file:
+            self.store.write_part("footer", self.footer)
+            self._memory_only.discard("footer")
+        else:
+            self._memory_only.add("footer")
+        if self.footer:
+            self.show_footer = True
+        if refresh:
+            self._refresh_if_live()
+
+    # -------------------------------------------------------------- mutation
+    def put(self, text, state=0, index=None, fill_value=None, alignment=None):
+        # Pick up a saved buffer once, before the first change of this session.
+        if not self.buffer and self._wait_n is None:
+            self.refresh_buffer_from_wait_log()
+
+        now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        emoji = self.EMOJI_STATES.get(state, "🟢")
+        if not isinstance(text, str):
+            text = str(text)
+        fill_value = self.FILLER if fill_value is None else fill_value
+
+        with self.buffer_lock:
+            old_len = len(self.buffer)
+            if index is None:
+                index = old_len
+                self.buffer.append(text)
+                appended_from = old_len
+            else:
+                if index < 0:
+                    index += old_len
+                if index < 0:
+                    raise IndexError("Negative index out of range after adjustment")
+                if index >= old_len:
+                    self.buffer.extend([fill_value] * (index - old_len))
+                    self.buffer.append(text)
+                    appended_from = old_len
+                else:
+                    self.buffer[index] = text
+                    appended_from = None
+
+            if alignment is not None:
+                self.alignments[index] = alignment
+
+            if self.store.enabled:
+                self._queue_wait_write(appended_from)
+                line = f"{now} {emoji} {text} [📍{index}]"
+                self._jobs.append(lambda ln=line: self.store.append_log(ln))
+
+        self._drain_io()
+        self._refresh_if_live()
+
+    @staticmethod
+    def _line_matches(line, contains, exact):
+        if contains is None:
+            return True
+        line_lower = line.lower()
+        contains_lower = contains.lower()
+        if exact:
+            return contains_lower in line_lower.split()
+        return contains_lower in line_lower
+
+    def delete(self, index, contains=None, exact=True):
+        if not isinstance(index, (int, slice)):
+            raise TypeError("Index must be int or slice")
+
+        with self.buffer_lock:
+            total = len(self.buffer)
+            if isinstance(index, int):
+                i = index + total if index < 0 else index
+                if not (0 <= i < total):
+                    raise IndexError("Index out of range")
+                targets = [i]
+            else:
+                targets = range(*index.indices(total))
+
+            doomed = {
+                i for i in targets
+                if self._line_matches(self.buffer[i], contains, exact)
+            }
+            if doomed:
+                kept = [i for i in range(total) if i not in doomed]
+                # re-key alignments so they follow their lines
+                self.alignments = {
+                    new: self.alignments[old]
+                    for new, old in enumerate(kept)
+                    if old in self.alignments
+                }
+                self.buffer = [self.buffer[i] for i in kept]
+                self._queue_wait_write()
+
+        self._drain_io()
+        self._refresh_if_live()
+
+    def clear(self):
+        with self.buffer_lock:
+            self.buffer.clear()
+            self.alignments.clear()
+            if self.store.enabled:
+                self._wait_n = 0
+                self._jobs.append(self.store.clear_wait)
+        self._drain_io()
+        self._refresh_if_live()
+
+    def clear_all(self):
+        with self.buffer_lock:
+            self.buffer.clear()
+            self.alignments.clear()
+            if self.store.enabled:
+                self._wait_n = 0
+                self._jobs.append(lambda: self.store.reset_all("", ""))
+        self.header = None
+        self.footer = None
+        self.show_header = False
+        self.show_footer = False
+        self._drain_io()
+        self._refresh_if_live()
+
+    def update(self, **kwargs):
+        if kwargs.get("silent_display") is not None and kwargs.get("only_display") is not None:
+            raise ValueError("silent_display and only_display cannot be used simultaneously")
+
+        for key in ("silent_display", "only_display"):
+            if key in kwargs:
+                kwargs[key] = validate_selector(kwargs[key], key)
+
+        # Validate everything before changing anything, so a failed update
+        # leaves the object exactly as it was.
+        known = self._PLAIN_SETTINGS | {
+            "header", "footer", "show_header", "show_footer",
+            "silent_display", "only_display", "log_file",
+        }
+        for key in kwargs:
+            if key not in known:
+                raise ValueError(f"Unknown setting: {key}")
+        self._check_limits(
+            kwargs.get("max_wait", self.max_wait),
+            kwargs.get("max_display", self.max_display),
+        )
+
+        for key, value in kwargs.items():
+            if key == "header":
+                self.set_header(value, save_to_file=True, refresh=False)
+            elif key == "footer":
+                self.set_footer(value, save_to_file=True, refresh=False)
+            elif key == "show_header":
+                self.show_header = bool(value)
+            elif key == "show_footer":
+                self.show_footer = bool(value)
+            elif key == "silent_display":
+                self.silent_display = value
+                if value is not None:
+                    self.only_display = None
+            elif key == "only_display":
+                self.only_display = value
+                if value is not None:
+                    self.silent_display = None
+            elif key == "log_file":
+                self._wait_io()                  # finish writes queued for the old file
+                with self.buffer_lock:
+                    self.store.set_log_file(value)
+                    self._wait_n = None          # new file: next change writes it in full
+            else:  # a plain setting
+                setattr(self, key, value)
+
+        self.store.max_main = self.max_main
+        self.store.max_wait = self.max_wait
+        self._refresh_if_live()
+
+    # --------------------------------------------------------------- display
+    def format_text_for_display(self):
+        """Return [[text, alignment], ...] for what should currently be shown."""
+        with self.buffer_lock:
+            lines = list(self.buffer)
+            alignments = dict(self.alignments)
+
+        return build_view(
+            lines,
+            alignments,
+            header=self.get_header(),
+            footer=self.get_footer(),
+            header_alignment=self.header_alignment,
+            footer_alignment=self.footer_alignment,
+            max_display=self.max_display,
+            shift_max_display=self.shift_max_display,
+            only_display=self.only_display,
+            silent_display=self.silent_display,
+            clean_silent_only=self.auto_clean_silent_only_display,
+            clean_edges=self.auto_clean_edges,
+            filler=self.FILLER,
+        )
+
+    def _width(self):
+        return self.width if self.width else terminal_width()
+
+    def _lines(self):
+        width = self._width()
+        return [
+            align_text(text, alignment, width)
+            for text, alignment in self.format_text_for_display()
+        ]
+
+    def get_text(self):
+        """The whole view as one string (each line aligned, joined by newline)."""
+        return "\n".join(self._lines())
+
+    def _draw(self, skip_same):
+        with self.display_lock:
+            text = self.get_text()
+            if skip_same and text == self._last_text:
+                return                    # nothing would change on screen
+            # wait=True keeps the old output until the new text arrives.
+            # With nothing to print it would never be replaced, so clear now.
+            clear_output(wait=bool(text))
+            if text:
+                # flush=True sends the new text immediately; otherwise the
+                # notebook may hold it for up to 0.2 s while the old frame stays.
+                print(text, flush=True)
+            self._last_text = text
+
+    def display(self):
+        """Replace what is on screen with the current buffer (flicker-free).
+        Always draws, even if nothing changed."""
+        self._draw(skip_same=False)
+
+    def read_log(self, last=None, show=True):
+        """Read the history log. The first line of the result is the file's location.
+
+        last=None  -> every entry;  last=N -> only the newest N entries.
+        show=True  -> print it (nothing returned, so a notebook doesn't show it twice).
+        show=False -> return it as one string instead.
+        """
+        if not self.store.enabled:
+            raise ValueError("No log_file set, so there is no log to read")
+        if last is not None:
+            if isinstance(last, bool) or not isinstance(last, int):
+                raise TypeError("last must be a whole number or None")
+            if last < 0:
+                raise ValueError("last cannot be negative")
+
+        self._wait_io()                   # make sure queued writes are on disk
+        entries = self.store.read_main()
+        total = len(entries)
+        if last is not None:
+            entries = entries[total - last:] if last else []
+
+        path = os.path.abspath(self.store.log_file)
+        shown = f"{len(entries)} of {total} entries" if last is not None else f"{total} entries"
+        head = [f"Log file: {path}", f"({shown})", "-" * 40]
+        text = "\n".join(head + (entries or ["(no entries)"]))
+        if not show:
+            return text
+        print(text)
+
+    def display_index(self):
+        with self.buffer_lock:
+            for i, line in enumerate(self.buffer):
+                print(f"[{i}]: {repr(line)}")
+
+    def flush(self):
+        """Clear the notebook output right away."""
+        with self.display_lock:
+            clear_output(wait=False)
+            self._last_text = None