pyos-tui 0.1.0__tar.gz

pyos_tui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Pinsonault
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyos_tui-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: pyos-tui
+Version: 0.1.0
+Summary: Terminal-first mini-OS framework: Activities, event loop, flex layout, and TUI components.
+Author-email: Joe Pinsonault <joe.pinsonault@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jpinsonault/pyos
+Project-URL: Repository, https://github.com/jpinsonault/pyos
+Project-URL: Issues, https://github.com/jpinsonault/pyos/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Terminals
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru<1,>=0.6
+Provides-Extra: windows
+Requires-Dist: windows-curses>=2.4.0; extra == "windows"
+Dynamic: license-file
+
+# pyos-tui
+
+A terminal-first mini-OS framework for building curses apps in Python. Provides an activity stack, event loop, flex layout engine, and composable UI components — so you can focus on your app instead of wrestling with curses.
+
+## Install
+
+```bash
+pip install pyos-tui
+
+# Windows users
+pip install pyos-tui[windows]
+```
+
+## Quick start
+
+```python
+import curses
+from pyos import Application, Activity
+from pyos.EventTypes import KeyStroke
+from pyos.Keys import ESC
+from pyos.printers.TopBar import TopBar
+from pyos.printers.ScrollList import ScrollList
+from pyos.printers.BottomBar import BottomBar
+from pyos.input_handlers import handle_scroll_list_input, ScrollChange
+
+class HomeActivity(Activity):
+    def on_start(self):
+        self.application.subscribe(KeyStroke, self, self.on_key)
+        self.application.subscribe(ScrollChange, self, self.on_scroll)
+
+        self.display_state = {
+            "top": TopBar.display_state(items={"title": "My App", "help": "ESC quit"}),
+            "list": ScrollList.display_state(
+                screen=self.screen,
+                items=[f"Item {i}" for i in range(1, 51)],
+                selected_index=0,
+                focused=True,
+                input_handler=handle_scroll_list_input,
+                min_height=5, flex=1,
+            ),
+            "bottom": BottomBar.display_state(items={"status": "Ready"}),
+        }
+        self.refresh_screen()
+
+    def on_key(self, event):
+        self.display_state["list"]["input_handler"](
+            "list", self.display_state["list"], event, self.event_queue
+        )
+        if event.key == ESC:
+            self.application.pop_activity()
+        self.refresh_screen()
+
+    def on_scroll(self, event):
+        idx = self.display_state["list"]["selected_index"]
+        self.display_state["bottom"]["items"]["status"] = f"Selected: {idx}"
+        self.refresh_screen()
+
+def main(stdscr):
+    app = Application(stdscr)
+    app.start(HomeActivity())
+
+if __name__ == "__main__":
+    curses.wrapper(main)
+```
+
+## Features
+
+**Activity stack** — Push, pop, and replace screens like a mobile navigation controller. Each Activity owns its UI state and subscriptions; the framework cleans up automatically on pop.
+
+**Event system** — Subscribe to typed events (`KeyStroke`, `TextBoxSubmit`, `ScrollChange`, etc.). Activities subscribe in `on_start` and the framework unsubscribes everything on stop.
+
+**Flex layout** — Regions can be fixed-height, flex (proportional with min/max), or auto-measured. The layout solver distributes terminal rows automatically.
+
+**Composable UI components** — Built-in printers for common patterns:
+
+| Component | Description |
+|---|---|
+| `TopBar` / `BottomBar` | Status bars |
+| `ScrollList` | Scrollable list with selection |
+| `TextInput` | Single-line text field with cursor |
+| `Table` | Auto-sized columns with headers |
+| `ContextMenuList` | List items with inline action menus |
+| `MultilineText` | Read-only text block |
+| `Accordion` | Collapsible sections |
+| `Spacer` | Fills remaining space |
+
+**Input handlers** — Plug-in handlers for text fields (`handle_text_box_input`) and scroll lists (`handle_scroll_list_input`) that manage cursor, selection, and emit events.
+
+**Threading** — `CentralDispatch` provides serial and concurrent dispatch queues. The main queue is safe for UI mutations; background work marshals updates back via `main_thread.submit_async(...)`.
+
+**Error recovery** — Unhandled exceptions push a traceback viewer. Press ESC to attempt stack recovery without crashing.
+
+**Built-in log viewer** — Press F1 to tail `application.log` in a dedicated activity.
+
+**Pytest plugin** — Ships a headful test renderer (`pyos-headful`) as a pytest plugin for watching your TUI tests render in real time.
+
+## Activity lifecycle
+
+```
+_start(application)  →  on_start()  →  refresh_screen()  →  _stop()
+```
+
+Override `on_start()` to set up `display_state` and event subscriptions. Override `on_stop()` for cleanup. Navigate with:
+
+```python
+self.application.segue_to(NextActivity())              # push
+self.application.segue_to(NextActivity(), Segue.REPLACE)  # replace
+self.application.pop_activity()                        # pop (empty stack stops the app)
+```
+
+## Layout
+
+Each entry in `display_state` is a dict with a `"layout"` key:
+
+```python
+{"height": 3}                                    # fixed: exactly 3 rows
+{"flex": 1, "min_height": 5}                     # flex: share remaining space
+{"flex": 2, "min_height": 3, "max_height": 20}   # flex with bounds
+# omit both → auto-measured from line_generator output
+```
+
+## Threading
+
+Only read/write `display_state` on the main thread. From background work:
+
+```python
+self.main_thread.submit_async(self.refresh_screen)
+self.main_thread.submit_async(self.on_new_data, payload)
+```
+
+## Requirements
+
+- Python 3.9+
+- A terminal that supports curses (most Unix terminals; Windows via `windows-curses`)
+
+## License
+
+MIT

pyos_tui-0.1.0/README.md

@@ -0,0 +1,138 @@
+# pyos-tui
+
+A terminal-first mini-OS framework for building curses apps in Python. Provides an activity stack, event loop, flex layout engine, and composable UI components — so you can focus on your app instead of wrestling with curses.
+
+## Install
+
+```bash
+pip install pyos-tui
+
+# Windows users
+pip install pyos-tui[windows]
+```
+
+## Quick start
+
+```python
+import curses
+from pyos import Application, Activity
+from pyos.EventTypes import KeyStroke
+from pyos.Keys import ESC
+from pyos.printers.TopBar import TopBar
+from pyos.printers.ScrollList import ScrollList
+from pyos.printers.BottomBar import BottomBar
+from pyos.input_handlers import handle_scroll_list_input, ScrollChange
+
+class HomeActivity(Activity):
+    def on_start(self):
+        self.application.subscribe(KeyStroke, self, self.on_key)
+        self.application.subscribe(ScrollChange, self, self.on_scroll)
+
+        self.display_state = {
+            "top": TopBar.display_state(items={"title": "My App", "help": "ESC quit"}),
+            "list": ScrollList.display_state(
+                screen=self.screen,
+                items=[f"Item {i}" for i in range(1, 51)],
+                selected_index=0,
+                focused=True,
+                input_handler=handle_scroll_list_input,
+                min_height=5, flex=1,
+            ),
+            "bottom": BottomBar.display_state(items={"status": "Ready"}),
+        }
+        self.refresh_screen()
+
+    def on_key(self, event):
+        self.display_state["list"]["input_handler"](
+            "list", self.display_state["list"], event, self.event_queue
+        )
+        if event.key == ESC:
+            self.application.pop_activity()
+        self.refresh_screen()
+
+    def on_scroll(self, event):
+        idx = self.display_state["list"]["selected_index"]
+        self.display_state["bottom"]["items"]["status"] = f"Selected: {idx}"
+        self.refresh_screen()
+
+def main(stdscr):
+    app = Application(stdscr)
+    app.start(HomeActivity())
+
+if __name__ == "__main__":
+    curses.wrapper(main)
+```
+
+## Features
+
+**Activity stack** — Push, pop, and replace screens like a mobile navigation controller. Each Activity owns its UI state and subscriptions; the framework cleans up automatically on pop.
+
+**Event system** — Subscribe to typed events (`KeyStroke`, `TextBoxSubmit`, `ScrollChange`, etc.). Activities subscribe in `on_start` and the framework unsubscribes everything on stop.
+
+**Flex layout** — Regions can be fixed-height, flex (proportional with min/max), or auto-measured. The layout solver distributes terminal rows automatically.
+
+**Composable UI components** — Built-in printers for common patterns:
+
+| Component | Description |
+|---|---|
+| `TopBar` / `BottomBar` | Status bars |
+| `ScrollList` | Scrollable list with selection |
+| `TextInput` | Single-line text field with cursor |
+| `Table` | Auto-sized columns with headers |
+| `ContextMenuList` | List items with inline action menus |
+| `MultilineText` | Read-only text block |
+| `Accordion` | Collapsible sections |
+| `Spacer` | Fills remaining space |
+
+**Input handlers** — Plug-in handlers for text fields (`handle_text_box_input`) and scroll lists (`handle_scroll_list_input`) that manage cursor, selection, and emit events.
+
+**Threading** — `CentralDispatch` provides serial and concurrent dispatch queues. The main queue is safe for UI mutations; background work marshals updates back via `main_thread.submit_async(...)`.
+
+**Error recovery** — Unhandled exceptions push a traceback viewer. Press ESC to attempt stack recovery without crashing.
+
+**Built-in log viewer** — Press F1 to tail `application.log` in a dedicated activity.
+
+**Pytest plugin** — Ships a headful test renderer (`pyos-headful`) as a pytest plugin for watching your TUI tests render in real time.
+
+## Activity lifecycle
+
+```
+_start(application)  →  on_start()  →  refresh_screen()  →  _stop()
+```
+
+Override `on_start()` to set up `display_state` and event subscriptions. Override `on_stop()` for cleanup. Navigate with:
+
+```python
+self.application.segue_to(NextActivity())              # push
+self.application.segue_to(NextActivity(), Segue.REPLACE)  # replace
+self.application.pop_activity()                        # pop (empty stack stops the app)
+```
+
+## Layout
+
+Each entry in `display_state` is a dict with a `"layout"` key:
+
+```python
+{"height": 3}                                    # fixed: exactly 3 rows
+{"flex": 1, "min_height": 5}                     # flex: share remaining space
+{"flex": 2, "min_height": 3, "max_height": 20}   # flex with bounds
+# omit both → auto-measured from line_generator output
+```
+
+## Threading
+
+Only read/write `display_state` on the main thread. From background work:
+
+```python
+self.main_thread.submit_async(self.refresh_screen)
+self.main_thread.submit_async(self.on_new_data, payload)
+```
+
+## Requirements
+
+- Python 3.9+
+- A terminal that supports curses (most Unix terminals; Windows via `windows-curses`)
+
+## License
+
+MIT

pyos_tui-0.1.0/pyos/Activity.py

@@ -0,0 +1,262 @@
+import functools
+import json
+from queue import Queue
+from typing import Callable
+
+from loguru import logger
+
+from .CentralDispatch import SerialDispatchQueue
+from .ContextUtils import get_fixed_size
+from .exception_utils import try_make_lines, try_print_line
+from pprint import pprint
+
+def solve_layout(display_state: dict, screen_height: int) -> dict:
+    allocated = {}
+    remaining = int(screen_height)
+    if remaining < 0:
+        remaining = 0
+
+    fixed_total = 0
+    flex_items = []
+
+    for key, context in display_state.items():
+        layout = context.get("layout", {})
+        if "height" in layout:
+            h = int(layout["height"])
+            h = max(0, h)
+            allocated[key] = h
+            fixed_total += h
+        else:
+            flex_value = float(layout.get("flex", 0) or 0)
+            if flex_value > 0:
+                min_h = int(layout.get("min_height", 0) or 0)
+                max_h = layout.get("max_height", None)
+                if max_h is None:
+                    max_h = max(0, screen_height)  # large cap so flex distribution is not artificially clamped
+                else:
+                    max_h = int(max_h)
+                    if max_h < 0:
+                        max_h = 0
+                curr = max(0, min_h)
+                cap = max(0, max_h - curr)
+                flex_items.append({
+                    "key": key,
+                    "flex": float(flex_value),
+                    "curr": int(curr),
+                    "cap": int(cap),
+                })
+
+    remaining = max(0, remaining - fixed_total)
+
+    if not flex_items:
+        return allocated
+
+    sum_min = sum(it["curr"] for it in flex_items)
+
+    if remaining <= sum_min:
+        for it in flex_items:
+            allocated[it["key"]] = int(it["curr"])
+        return allocated
+
+    remaining -= sum_min
+
+    active = [it for it in flex_items if it["cap"] > 0 and it["flex"] > 0.0]
+
+    while remaining > 0 and active:
+        total_flex = sum(it["flex"] for it in active)
+        if total_flex <= 0:
+            break
+
+        adds = []
+        frac_order = []
+        gained = 0
+
+        for it in active:
+            share = (it["flex"] / total_flex) * remaining
+            base = int(share)
+            add = min(it["cap"], base)
+            adds.append(add)
+            frac_order.append(share - base)
+
+        for it, add in zip(active, adds):
+            if add > 0:
+                it["curr"] += add
+                it["cap"] -= add
+                remaining -= add
+                gained += add
+
+        if remaining > 0:
+            if gained == 0:
+                order = sorted(range(len(active)), key=lambda i: frac_order[i], reverse=True)
+                for idx in order:
+                    if remaining <= 0:
+                        break
+                    it = active[idx]
+                    if it["cap"] > 0:
+                        it["curr"] += 1
+                        it["cap"] -= 1
+                        remaining -= 1
+                        gained += 1
+            if remaining > 0 and gained == 0:
+                for it in active:
+                    if remaining <= 0:
+                        break
+                    if it["cap"] > 0:
+                        take = min(it["cap"], remaining)
+                        it["curr"] += take
+                        it["cap"] -= take
+                        remaining -= take
+                        gained += take
+
+        active = [it for it in active if it["cap"] > 0 and it["flex"] > 0.0]
+
+    for it in flex_items:
+        allocated[it["key"]] = int(max(0, it["curr"]))
+
+    return allocated
+
+
+class Activity:
+    def __init__(self):
+        self.application = None
+        self.event_queue: Queue = None
+        self.screen = None
+        self.main_thread: SerialDispatchQueue = None
+        self.display_state = {}
+        self.previous_display_state = {}
+        self.lifecycle_state = "init"
+        self.tab_order: list = []
+        self.focus: str = None
+
+    def _set_focus(self, target):
+        """Move focus to *target*, updating ``focused`` flags in display_state."""
+        if self.focus and self.focus in self.display_state:
+            self.display_state[self.focus]["focused"] = False
+        self.focus = target
+        if target and target in self.display_state:
+            self.display_state[target]["focused"] = True
+
+    def cycle_focus(self):
+        """Advance focus to the next entry in ``tab_order``, wrapping around."""
+        if not self.tab_order:
+            return
+        if self.focus in self.tab_order:
+            idx = (self.tab_order.index(self.focus) + 1) % len(self.tab_order)
+        else:
+            idx = 0
+        self._set_focus(self.tab_order[idx])
+
+    def delegate_to_focused(self, event):
+        """Route *event* to the ``input_handler`` of the focused context.
+
+        Returns True if a handler was found and called, False otherwise.
+        """
+        if not self.focus or self.focus not in self.display_state:
+            return False
+        ctx = self.display_state[self.focus]
+        handler = ctx.get("input_handler")
+        if handler:
+            handler(self.focus, ctx, event, self.event_queue)
+            return True
+        return False
+
+    def _start(self, application):
+        self.lifecycle_state = "starting"
+        self.application = application
+        self.event_queue = application.event_queue
+        self.screen = application.curses_screen
+        self.main_thread = application.main_thread
+        self.background_thread = application.background_thread
+        self.on_start()
+        self.lifecycle_state = "started"
+        self.refresh_screen()
+
+    def on_start(self): pass
+
+    def _stop(self):
+        self.on_stop()
+        self.lifecycle_state = "stopped"
+        self.application = None
+
+    def on_stop(self): pass
+
+    def generate_line_printers(self) -> list[Callable]:
+        from .layout import Constraint, solve_constraints
+
+        num_rows, num_cols = self.application.curses_screen.getmaxyx()
+
+        for key, context in self.display_state.items():
+            if "layout" not in context:
+                raise Exception(f"Legacy display_state item detected without 'layout': {key}")
+
+        constraint_keys = {k for k, ctx in self.display_state.items() if isinstance(ctx.get("layout"), Constraint)}
+        dict_keys = {k for k, ctx in self.display_state.items() if isinstance(ctx.get("layout"), dict)}
+
+        if constraint_keys and dict_keys:
+            raise TypeError(
+                f"Cannot mix Constraint layouts with dict layouts in the same display_state. "
+                f"Constraint keys: {sorted(constraint_keys)}, dict keys: {sorted(dict_keys)}"
+            )
+
+        if constraint_keys:
+            heights = solve_constraints(self.display_state, num_rows)
+        else:
+            measured_state = {}
+            for key, context in self.display_state.items():
+                layout = dict(context.get("layout", {}))
+                flex_value = float(layout.get("flex", 0) or 0)
+                is_fixed = "height" in layout
+                is_flex = (flex_value > 0)
+                if not is_fixed and not is_flex:
+                    min_h = int(layout.get("min_height", 0) or 0)
+                    max_h_raw = layout.get("max_height", None)
+                    try:
+                        printers = try_make_lines(context, 1_000_000)
+                        natural = len(list(printers))
+                    except Exception:
+                        natural = min_h
+                    if max_h_raw is None:
+                        natural_h = max(min_h, natural)
+                    else:
+                        max_h = int(max_h_raw)
+                        if max_h < 0:
+                            max_h = 0
+                        natural_h = max(min_h, min(max_h, natural))
+                    ml = layout.copy()
+                    ml["height"] = int(max(0, natural_h))
+                    ml.pop("flex", None)
+                    measured_state[key] = {"layout": ml}
+                else:
+                    measured_state[key] = {"layout": layout}
+
+            heights = solve_layout(measured_state, num_rows)
+
+        next_y_index = 0
+        screen_line_printers = []
+        for key, context in self.display_state.items():
+            allocated = int(heights.get(key, 0))
+            if allocated > 0:
+                line_printers = try_make_lines(context, allocated)
+                line_printers = list(line_printers)[:allocated]
+                screen_line_printers += line_printers
+                next_y_index += len(line_printers)
+            if next_y_index >= num_rows:
+                break
+
+        return screen_line_printers
+
+    def refresh_screen(self):
+        if self.lifecycle_state != "stopped":
+            screen = self.application.curses_screen
+            screen_line_printers = self.generate_line_printers()
+
+            screen.clear()
+            for y, line_printer in enumerate(screen_line_printers):
+                try_print_line(line_printer, screen, y)
+
+            screen.refresh()
+
+        self.previous_display_state = self.display_state
+
+    def async_refresh_screen(self):
+        self.main_thread.submit_async(self.refresh_screen)