rich-transient 0.1.0__py3-none-any.whl

rich_transient/__init__.py

@@ -0,0 +1,230 @@
+"""Reusable Rich-based braille spinner and transient live panel for CLI output.
+
+This package can be used by any project that needs:
+- A braille-style status spinner (accessible, compact)
+- A transient live panel that streams output and clears on exit
+
+Dependencies: rich
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass, fields, replace
+from types import SimpleNamespace
+from typing import Callable, Literal, TypeVar
+
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.text import Text
+
+T = TypeVar("T")
+
+# Braille spinner frames (one per refresh) so the status line visibly animates.
+SPINNER_BRAILLE: tuple[str, ...] = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
+
+# Shared refresh rate for Live displays (transient panel and other live UIs).
+LIVE_REFRESH_PER_SECOND: float = 8.0
+
+
+def get_braille_frame() -> int:
+    """Return the current animation frame index for the braille spinner (0 to len(SPINNER_BRAILLE)-1).
+
+    Use with SPINNER_BRAILLE[get_braille_frame()] when building custom live UIs (e.g. tables, status lines).
+    """
+    return int(time.monotonic() * LIVE_REFRESH_PER_SECOND) % len(SPINNER_BRAILLE)
+
+
+# Name under which we register the braille spinner in Rich's SPINNERS dict.
+_BRAILLE_SPINNER_NAME = "braille"
+
+
+def register_braille_spinner() -> None:
+    """Register the braille spinner with Rich so console.status(..., spinner='braille') works.
+
+    Idempotent; safe to call multiple times. Call once at startup or rely on braille_spinner_for_status().
+    """
+    try:
+        from rich import _spinners
+
+        _spinners.SPINNERS[_BRAILLE_SPINNER_NAME] = {
+            "frames": list(SPINNER_BRAILLE),
+            "interval": 1000.0 / LIVE_REFRESH_PER_SECOND,
+        }
+    except (ImportError, AttributeError):
+        pass
+
+
+def braille_spinner_for_status() -> str:
+    """Return the Rich spinner name 'braille' for use with console.status(spinner=...).
+
+    Registers the braille frames with Rich on first use, then returns the name so Status
+    can look it up. Rich's Status expects a spinner name (str), not a Spinner instance.
+
+    Example:
+        with console.status("Loading...", spinner=braille_spinner_for_status()):
+            do_work()
+    """
+    register_braille_spinner()
+    return _BRAILLE_SPINNER_NAME
+
+
+@dataclass(frozen=True)
+class TransientPanelConfig:
+    """Configuration for transient live panels. Use presets via transient_live_panel(..., preset='streaming')."""
+
+    max_lines: int = 100
+    display_lines: int = 24
+    refresh_per_second: float = LIVE_REFRESH_PER_SECOND
+    default_status: str = "Running"
+    reserve_lines: int = 12  # Space for title, borders, padding, subtitle
+    border_style: str = "dim"
+    padding: tuple[int, int] = (0, 1)
+
+
+# Presets for consistent behavior across commands.
+TRANSIENT_PANEL_PRESETS: dict[str, TransientPanelConfig] = {
+    "default": TransientPanelConfig(),
+    "streaming": TransientPanelConfig(
+        max_lines=200,
+        display_lines=28,
+        default_status="Running",
+    ),
+}
+
+
+def _resolve_panel_config(
+    preset: Literal["default", "streaming"] | None = None,
+    config: TransientPanelConfig | None = None,
+    **overrides: object,
+) -> TransientPanelConfig:
+    """Resolve config from preset, optional explicit config, and overrides."""
+    base = config or TRANSIENT_PANEL_PRESETS.get(preset or "default") or TRANSIENT_PANEL_PRESETS["default"]
+    valid_names = {f.name for f in fields(TransientPanelConfig)}
+    clean = {k: v for k, v in overrides.items() if k in valid_names and v is not None}
+    if not clean:
+        return base
+    return replace(base, **clean)
+
+
+@contextmanager
+def transient_live_panel(
+    title: str,
+    preset: Literal["default", "streaming"] = "default",
+    config: TransientPanelConfig | None = None,
+    *,
+    max_lines: int | None = None,
+    display_lines: int | None = None,
+    border_style: str | None = None,
+    console: Console | None = None,
+):
+    """Context manager that shows streaming output in a live panel; panel is cleared on exit.
+
+    Use for verbose subprocess output: output streams into the panel while the task runs,
+    then the panel is removed so only the high-level success/failure line remains.
+
+    Presets:
+      - "default": Short steps. max_lines=100, display_lines=24.
+      - "streaming": Long tool output. max_lines=200, display_lines=28.
+
+    Optional kwargs override the preset (e.g. display_lines=30).
+    Pass console= to use a specific Rich Console (e.g. with custom theme).
+
+    Yields an object with:
+      - append(line: str) -> None
+      - set_status(text: str) -> None   -- update the status line (e.g. "Downloading X...")
+      - run_task(task_callable: Callable[[], T]) -> T
+    """
+    target_console = console if console is not None else Console()
+    cfg = _resolve_panel_config(
+        preset=preset,
+        config=config,
+        max_lines=max_lines,
+        display_lines=display_lines,
+        border_style=border_style,
+    )
+    lines_list: list[str] = []
+    current_status: list[str] = [cfg.default_status]
+    lock = threading.Lock()
+    result_holder: list = []
+    try:
+        console_height = target_console.size.height
+    except Exception:
+        console_height = 30
+    tail = min(cfg.display_lines, max(1, console_height - cfg.reserve_lines))
+
+    def append(line: str) -> None:
+        with lock:
+            lines_list.append(line)
+
+    def set_status(text: str) -> None:
+        with lock:
+            current_status[0] = text
+
+    def render() -> Panel:
+        with lock:
+            recent = lines_list[-cfg.max_lines:] if len(lines_list) > cfg.max_lines else lines_list
+            visible = recent[-tail:] if len(recent) > tail else recent
+            content = "\n".join(visible)
+            status_text = current_status[0]
+        if content:
+            try:
+                streamed = Text.from_markup(content)
+            except Exception:
+                streamed = Text(content)
+        else:
+            streamed = Text("")
+        frame_idx = get_braille_frame()
+        status_line = Text(f" {SPINNER_BRAILLE[frame_idx]} {status_text}", style="dim")
+        return Panel(
+            streamed,
+            title=title,
+            subtitle=status_line,
+            border_style=cfg.border_style,
+            padding=cfg.padding,
+            expand=True,
+        )
+
+    def run_task(task_callable: Callable[[], T]) -> T:
+        result_holder.clear()
+        exc_holder: list[BaseException | None] = [None]
+
+        def run() -> None:
+            try:
+                result_holder.append(task_callable())
+            except BaseException as e:
+                exc_holder[0] = e
+
+        th = threading.Thread(target=run)
+        th.start()
+        with Live(
+            render(),
+            refresh_per_second=cfg.refresh_per_second,
+            transient=True,
+            console=target_console,
+        ) as live:
+            while th.is_alive():
+                live.update(render())
+                time.sleep(0.05)
+            live.update(render())
+        th.join()
+        if exc_holder[0] is not None:
+            raise exc_holder[0]
+        return result_holder[0]
+
+    yield SimpleNamespace(append=append, set_status=set_status, run_task=run_task)
+
+
+__all__ = [
+    "SPINNER_BRAILLE",
+    "LIVE_REFRESH_PER_SECOND",
+    "TransientPanelConfig",
+    "TRANSIENT_PANEL_PRESETS",
+    "braille_spinner_for_status",
+    "get_braille_frame",
+    "register_braille_spinner",
+    "transient_live_panel",
+]

rich_transient-0.1.0.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: rich-transient
+Version: 0.1.0
+Summary: Reusable Rich-based braille spinner and transient live panel for CLI output
+Project-URL: Homepage, https://github.com/your-org/rich-transient
+Project-URL: Repository, https://github.com/your-org/rich-transient
+Project-URL: Documentation, https://github.com/your-org/rich-transient#readme
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,live,panel,progress,rich,spinner,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.7.1
+Description-Content-Type: text/markdown
+
+# rich_transient
+
+Reusable [Rich](https://github.com/Textualize/rich)-based **braille spinner** and **transient live panel** for CLI output. Use it to show streaming subprocess or task output in a live-updating panel that disappears when the task finishes, with an animated status line.
+
+**Requires:** Python 3.11+, `rich>=13.7.1`
+
+---
+
+## Installation
+
+**From PyPI:**
+```bash
+pip install rich-transient
+```
+
+**Standalone (from this repo):**
+```bash
+pip install -e /path/to/AutoIaC/rich_transient
+```
+
+**As part of AutoIaC:**
+```bash
+pip install -e /path/to/AutoIaC
+# installs both auto_iac and rich_transient
+```
+
+---
+
+## Quick start: transient live panel
+
+Wrap a long-running task so its output streams into a live panel; when the task ends, the panel is cleared (transient) and only your final message remains.
+
+```python
+from rich_transient import transient_live_panel
+
+with transient_live_panel("Installing dependencies") as panel:
+    def do_work():
+        # Simulate streaming output
+        for i in range(20):
+            print(f"Step {i + 1}/20...")
+        return "done"
+
+    result = panel.run_task(do_work)
+
+print(f"Result: {result}")
+```
+
+The panel shows a scrolling tail of output and an animated braille spinner in the status line; when `run_task` returns, the panel is removed.
+
+---
+
+## Using the panel API
+
+The context manager yields an object with three methods:
+
+| Method | Description |
+|--------|-------------|
+| `panel.append(line: str)` | Add a line to the panel content (e.g. from a subprocess stdout). |
+| `panel.set_status(text: str)` | Update the status line shown next to the spinner (e.g. "Downloading X..."). |
+| `panel.run_task(callable)` | Run a callable in a background thread; the panel refreshes until it completes. Returns the callable's return value; re-raises any exception. |
+
+**Streaming subprocess output into the panel:**
+
+```python
+import subprocess
+from rich_transient import transient_live_panel
+
+with transient_live_panel("Running tests") as panel:
+    def run():
+        proc = subprocess.Popen(
+            ["pytest", "-v"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+        for line in proc.stdout:
+            panel.append(line.rstrip())
+        proc.wait()
+        return proc.returncode
+
+    exit_code = panel.run_task(run)
+print(f"Tests exited with code {exit_code}")
+```
+
+**Updating the status line:**
+
+```python
+with transient_live_panel("Building") as panel:
+    def build():
+        panel.set_status("Compiling...")
+        # do compile
+        panel.set_status("Linking...")
+        # do link
+        return 0
+
+    panel.run_task(build)
+```
+
+---
+
+## Braille spinner
+
+Use the spinner frames for your own live UI (e.g. a custom table or status line).
+
+**With Rich `console.status()`** — use the built-in braille spinner so the whole app shares one style:
+
+```python
+from rich.console import Console
+from rich_transient import braille_spinner_for_status
+
+console = Console()
+
+with console.status("Loading state...", spinner=braille_spinner_for_status()) as status:
+    do_work()
+    status.update("Almost done...")
+```
+
+**Custom live UI** — use `get_braille_frame()` so you don't duplicate the frame math:
+
+```python
+import time
+from rich.console import Console
+from rich.live import Live
+from rich_transient import SPINNER_BRAILLE, LIVE_REFRESH_PER_SECOND, get_braille_frame
+
+console = Console()
+
+def make_status():
+    frame = get_braille_frame()
+    return f"{SPINNER_BRAILLE[frame]} Working..."
+
+with Live(make_status(), refresh_per_second=LIVE_REFRESH_PER_SECOND, console=console) as live:
+    for _ in range(20):
+        time.sleep(0.1)
+        live.update(make_status())
+```
+
+**Exports:**
+
+- `SPINNER_BRAILLE` — tuple of 10 braille characters for animation frames.
+- `LIVE_REFRESH_PER_SECOND` — default refresh rate (8.0) for live displays.
+- `get_braille_frame()` — current animation frame index (use with `SPINNER_BRAILLE[i]`).
+- `braille_spinner_for_status()` — Registers the braille spinner with Rich and returns the name `"braille"` for `console.status(spinner=...)`.
+- `register_braille_spinner()` — Idempotent registration of the braille spinner in Rich's SPINNERS dict (called automatically by `braille_spinner_for_status()`).
+
+---
+
+## Presets and options
+
+**Presets** control buffer size and visible lines:
+
+- `preset="default"` — max_lines=100, display_lines=24 (short steps).
+- `preset="streaming"` — max_lines=200, display_lines=28 (long streaming output).
+
+Override per call:
+
+```python
+with transient_live_panel(
+    "Long log",
+    preset="streaming",
+    max_lines=500,
+    display_lines=40,
+) as panel:
+    panel.run_task(my_task)
+```
+
+**Custom Rich theme:** pass a `Console` so the panel uses your theme:
+
+```python
+from rich.console import Console
+from rich.theme import Theme
+from rich_transient import transient_live_panel
+
+my_theme = Theme({"info": "cyan", "success": "green"})
+console = Console(theme=my_theme)
+
+with transient_live_panel("Task", console=console) as panel:
+    panel.run_task(my_task)
+```
+
+---
+
+## Configuration
+
+For full control, use `TransientPanelConfig` and `TRANSIENT_PANEL_PRESETS`:
+
+```python
+from rich_transient import (
+    TransientPanelConfig,
+    TRANSIENT_PANEL_PRESETS,
+    transient_live_panel,
+)
+
+# Use a built-in preset
+cfg = TRANSIENT_PANEL_PRESETS["streaming"]
+
+# Or build your own
+custom = TransientPanelConfig(
+    max_lines=300,
+    display_lines=30,
+    default_status="Processing...",
+    border_style="blue",
+)
+
+with transient_live_panel("Custom", config=custom) as panel:
+    panel.run_task(my_task)
+```
+
+---
+
+## API summary
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `SPINNER_BRAILLE` | `tuple[str, ...]` | Braille spinner frames. |
+| `LIVE_REFRESH_PER_SECOND` | `float` | Default refresh rate for live displays. |
+| `get_braille_frame()` | `() -> int` | Current animation frame index for use with `SPINNER_BRAILLE`. |
+| `braille_spinner_for_status()` | `() -> str` | Registers braille spinner with Rich and returns `"braille"` for `console.status(spinner=...)`. |
+| `register_braille_spinner()` | `() -> None` | Idempotent registration of braille spinner in Rich's SPINNERS. |
+| `TransientPanelConfig` | dataclass | Panel configuration (max_lines, display_lines, border_style, etc.). |
+| `TRANSIENT_PANEL_PRESETS` | `dict[str, TransientPanelConfig]` | `"default"` and `"streaming"` presets. |
+| `transient_live_panel(...)` | context manager | Yields an object with `append`, `set_status`, `run_task`. |

rich_transient-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+rich_transient/__init__.py,sha256=LZo3iGwMpg1FAB7jushlI9QVcMa3tNC5CM_ovtD8fyY,7619
+rich_transient-0.1.0.dist-info/METADATA,sha256=vg78FBOkmw_lu3v1mmXXjVDkwfYP_IElKMQSqgVU4WQ,7538
+rich_transient-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+rich_transient-0.1.0.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+rich_transient-0.1.0.dist-info/RECORD,,

rich_transient-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

rich_transient-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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.