rich-transient 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

rich_transient/__init__.py

@@ -1,8 +1,9 @@
-"""Reusable Rich-based braille spinner and transient live panel for CLI output.
+"""Reusable Rich-based braille spinner, transient live panel, and CLI styling for 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
+- Consistent section headers, separators, and key-value panels (Rule + Panel)
 
 Dependencies: rich
 """
@@ -14,15 +15,95 @@ import time
 from contextlib import contextmanager
 from dataclasses import dataclass, fields, replace
 from types import SimpleNamespace
-from typing import Callable, Literal, TypeVar
+from typing import Callable, Literal, Sequence, TypeVar
 
 from rich.console import Console
 from rich.live import Live
 from rich.panel import Panel
+from rich.rule import Rule
 from rich.text import Text
+from rich.theme import Theme
 
 T = TypeVar("T")
 
+# --- Semantic style names (raw colors; use with Rule/Panel when not using a theme) ---
+STYLE_SECTION: str = "blue"
+STYLE_SUCCESS: str = "green"
+STYLE_WARNING: str = "yellow"
+STYLE_DIM: str = "dim"
+
+# --- Theme style keys: use these with Console(theme=get_theme(...)) then style="section" etc. ---
+THEME_STYLE_SECTION: str = "section"
+THEME_STYLE_SUCCESS: str = "success"
+THEME_STYLE_WARNING: str = "warning"
+THEME_STYLE_DIM: str = "dim"
+
+# --- Built-in themes (same keys, different palettes); use with Console(theme=get_theme("name")) ---
+THEMES: dict[str, Theme] = {
+    "default": Theme({
+        THEME_STYLE_SECTION: "blue",
+        THEME_STYLE_SUCCESS: "green",
+        THEME_STYLE_WARNING: "yellow",
+        THEME_STYLE_DIM: "dim",
+    }),
+    "ngate": Theme({
+        THEME_STYLE_SECTION: "blue",
+        THEME_STYLE_SUCCESS: "green",
+        THEME_STYLE_WARNING: "yellow",
+        THEME_STYLE_DIM: "dim",
+    }),
+    "muted": Theme({
+        THEME_STYLE_SECTION: "dim blue",
+        THEME_STYLE_SUCCESS: "dim green",
+        THEME_STYLE_WARNING: "dim yellow",
+        THEME_STYLE_DIM: "dim",
+    }),
+    "high_contrast": Theme({
+        THEME_STYLE_SECTION: "bold bright_blue",
+        THEME_STYLE_SUCCESS: "bold bright_green",
+        THEME_STYLE_WARNING: "bold bright_yellow",
+        THEME_STYLE_DIM: "dim",
+    }),
+    "mono": Theme({
+        THEME_STYLE_SECTION: "bold",
+        THEME_STYLE_SUCCESS: "bold",
+        THEME_STYLE_WARNING: "italic",
+        THEME_STYLE_DIM: "dim",
+    }),
+    "nord": Theme({
+        THEME_STYLE_SECTION: "#5e81ac",
+        THEME_STYLE_SUCCESS: "#a3be8c",
+        THEME_STYLE_WARNING: "#ebcb8b",
+        THEME_STYLE_DIM: "dim",
+    }),
+    "dracula": Theme({
+        THEME_STYLE_SECTION: "#bd93f9",
+        THEME_STYLE_SUCCESS: "#50fa7b",
+        THEME_STYLE_WARNING: "#f1fa8c",
+        THEME_STYLE_DIM: "dim",
+    }),
+}
+
+
+def get_theme(name: str) -> Theme:
+    """Return a built-in theme by name. Use with Console(theme=get_theme(\"muted\")).
+
+    Available names: default, ngate, muted, high_contrast, mono, nord, dracula.
+    Falls back to \"default\" if name is unknown.
+    """
+    return THEMES.get(name, THEMES["default"])
+
+
+def themed_console(theme_name: str = "default", **console_kwargs: object) -> Console:
+    """Return a Console using a built-in theme. Use theme style names in helpers (e.g. style=\"section\").
+
+    Example:
+        console = themed_console(\"muted\")
+        console.print(section_rule(\"Fetch complete\", style=\"section\"))
+        console.print(key_value_panel([...], border_style=\"success\"))
+    """
+    return Console(theme=get_theme(theme_name), **console_kwargs)
+
 # Braille spinner frames (one per refresh) so the status line visibly animates.
 SPINNER_BRAILLE: tuple[str, ...] = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
 
@@ -96,6 +177,81 @@ TRANSIENT_PANEL_PRESETS: dict[str, TransientPanelConfig] = {
 }
 
 
+# --- CLI styling helpers (section rules, key-value panels) ---
+
+
+def section_rule(
+    title: str,
+    *,
+    style: str = STYLE_SECTION,
+) -> Rule:
+    """Return a Rule with a bold section title (e.g. for command headers or stage labels).
+
+    Example:
+        console.print(section_rule("FETCH (THE FEED)"))
+        console.print(section_rule("Finding top source categories", style=STYLE_SECTION))
+    """
+    return Rule(f"[bold {style}]{title}[/]", style=style)
+
+
+def dim_rule() -> Rule:
+    """Return a dim Rule for a subtle separator between sections."""
+    return Rule(style=STYLE_DIM)
+
+
+def key_value_panel(
+    lines: Sequence[tuple[str, str | None]] | Sequence[str],
+    *,
+    title: str | None = None,
+    border_style: str = STYLE_SECTION,
+    padding: tuple[int, int] = (0, 1),
+    label_markup: str = "[bold]",
+    skip_none: bool = True,
+) -> Panel:
+    """Build a Panel from key-value pairs or preformatted lines.
+
+    Args:
+        lines: Either (label, value) pairs (values shown as plain; use markup in label)
+               or a sequence of already-marked-up line strings.
+        title: Optional panel title (e.g. "[bold blue]Top source[/]").
+        border_style: Panel border color (STYLE_SECTION, STYLE_SUCCESS, etc.).
+        padding: Panel padding (default (0, 1) for compact layout).
+        label_markup: Markup for labels when lines are (label, value) pairs.
+        skip_none: When True, omit pairs whose value is None.
+
+    Example (key-value pairs):
+        key_value_panel([
+            ("Backend", "sumologic"),
+            ("Hours Back", "24"),
+            ("Limit", "10000"),
+        ], title="[bold blue]Run settings[/]")
+
+    Example (preformatted lines):
+        key_value_panel([
+            "  [bold]Size[/]  [white]1,234[/]",
+            "  [bold]Rate[/]  [cyan]0.5 GB/hour[/]",
+        ], border_style=STYLE_SUCCESS)
+    """
+    if not lines:
+        content = ""
+    elif isinstance(lines[0], str):
+        content = "\n".join(lines)
+    else:
+        parts = []
+        for item in lines:
+            label, value = item[0], item[1]
+            if skip_none and value is None:
+                continue
+            parts.append(f"  {label_markup}{label}:[/] {value}")
+        content = "\n".join(parts)
+    return Panel(
+        content,
+        title=title,
+        border_style=border_style,
+        padding=padding,
+    )
+
+
 def _resolve_panel_config(
     preset: Literal["default", "streaming"] | None = None,
     config: TransientPanelConfig | None = None,
@@ -221,10 +377,24 @@ def transient_live_panel(
 __all__ = [
     "SPINNER_BRAILLE",
     "LIVE_REFRESH_PER_SECOND",
+    "STYLE_DIM",
+    "STYLE_SECTION",
+    "STYLE_SUCCESS",
+    "STYLE_WARNING",
+    "THEMES",
+    "THEME_STYLE_DIM",
+    "THEME_STYLE_SECTION",
+    "THEME_STYLE_SUCCESS",
+    "THEME_STYLE_WARNING",
     "TransientPanelConfig",
     "TRANSIENT_PANEL_PRESETS",
     "braille_spinner_for_status",
+    "dim_rule",
     "get_braille_frame",
+    "get_theme",
+    "key_value_panel",
     "register_braille_spinner",
+    "section_rule",
+    "themed_console",
     "transient_live_panel",
 ]

{rich_transient-0.1.0.dist-info → rich_transient-0.1.1.dist-info}/METADATA

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: rich-transient
-Version: 0.1.0
+Version: 0.1.1
 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
+Project-URL: Homepage, https://github.com/maravedi/rich-transient
+Project-URL: Repository, https://github.com/maravedi/rich-transient
+Project-URL: Documentation, https://github.com/maravedi/rich-transient#readme
+Author: David Frazer <david.frazer336@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
 Keywords: cli,live,panel,progress,rich,spinner,terminal
@@ -17,7 +18,7 @@ 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-Python: >=3.12
 Requires-Dist: rich>=13.7.1
 Description-Content-Type: text/markdown
 
@@ -38,13 +39,7 @@ 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
+pip install -e ./rich_transient
 ```
 
 ---
@@ -231,15 +226,124 @@ with transient_live_panel("Custom", config=custom) as panel:
 
 ---
 
+## CLI styling helpers (section rules and key-value panels)
+
+For consistent command headers and summary blocks (e.g. run settings, completion messages), use semantic style constants and helpers so all commands share the same look.
+
+**Semantic style constants** (use with `border_style=` or `style=`):
+
+- `STYLE_SECTION` — `"blue"` (section headers, info panels)
+- `STYLE_SUCCESS` — `"green"` (completion, success panels)
+- `STYLE_WARNING` — `"yellow"` (warnings)
+- `STYLE_DIM` — `"dim"` (separators)
+
+**Section header (Rule):**
+
+```python
+from rich.console import Console
+from rich_transient import section_rule, dim_rule, STYLE_SUCCESS
+
+console = Console()
+
+console.print(section_rule("FETCH (THE FEED)"))
+# ... content ...
+console.print(dim_rule())
+
+console.print(section_rule("Fetch complete", style=STYLE_SUCCESS))
+```
+
+**Key-value panel** (static summary box with consistent padding and border):
+
+```python
+from rich_transient import key_value_panel, STYLE_SECTION, STYLE_SUCCESS
+
+# From (label, value) pairs
+console.print(key_value_panel([
+    ("Backend", "sumologic"),
+    ("Hours Back", "24"),
+    ("Limit", "10000"),
+], title="[bold blue]Run settings[/]", border_style=STYLE_SECTION))
+
+# Preformatted lines (full markup control)
+console.print(key_value_panel([
+    "  [bold]Logs saved to:[/] [cyan]/path/to/logs[/]",
+    "  [bold]Next steps:[/]",
+    "    [dim]# Run analysis:[/]",
+    "    [cyan]ngate analyze /path/to/logs/[/]",
+], border_style=STYLE_SUCCESS))
+```
+
+Use these with `transient_live_panel` so that after the transient panel clears, your final summary uses the same `STYLE_SUCCESS` and `key_value_panel` for a consistent “done” block.
+
+---
+
+## Themes
+
+The module provides **themes** so you can keep the same semantic roles (section, success, warning, dim) but switch palettes. Use a themed console and pass **theme style names** (`"section"`, `"success"`, `"warning"`, `"dim"`) to `section_rule`, `key_value_panel`, and `Panel`/`Rule`; the theme maps those names to colors.
+
+**Built-in themes:**
+
+| Theme name       | Description |
+|------------------|-------------|
+| `default` / `ngate` | Blue sections, green success, yellow warning (current nGate-style). |
+| `muted`          | Softer dim blue/green/yellow; good for low-contrast terminals. |
+| `high_contrast`  | Bold bright blue/green/yellow for accessibility. |
+| `mono`           | No color: bold for section/success, italic for warning, dim for separator. |
+| `nord`           | [Nord](https://www.nordtheme.com/) palette (blue, green, yellow). |
+| `dracula`        | [Dracula](https://draculatheme.com/) palette (purple, green, yellow). |
+
+**Using a theme:**
+
+```python
+from rich_transient import (
+    themed_console,
+    get_theme,
+    section_rule,
+    key_value_panel,
+    THEME_STYLE_SECTION,
+    THEME_STYLE_SUCCESS,
+)
+
+# Option 1: themed_console (one-liner)
+console = themed_console("muted")
+console.print(section_rule("Fetch complete", style=THEME_STYLE_SECTION))
+console.print(key_value_panel([("Output", "/path/to/logs")], border_style=THEME_STYLE_SUCCESS))
+
+# Option 2: get_theme with your own Console
+from rich.console import Console
+console = Console(theme=get_theme("nord"))
+console.print(section_rule("Running", style="section"))
+```
+
+**Theme style name constants:** `THEME_STYLE_SECTION`, `THEME_STYLE_SUCCESS`, `THEME_STYLE_WARNING`, `THEME_STYLE_DIM` — use these (or the strings `"section"`, `"success"`, etc.) when printing with a themed console so the theme supplies the actual color.
+
+**Without a theme:** you can still pass raw colors to the helpers, e.g. `section_rule("Title", style=STYLE_SECTION)` (or `style="blue"`). That works with any Console.
+
+---
+
 ## API summary
 
 | Export | Type | Description |
 |--------|------|-------------|
 | `SPINNER_BRAILLE` | `tuple[str, ...]` | Braille spinner frames. |
 | `LIVE_REFRESH_PER_SECOND` | `float` | Default refresh rate for live displays. |
+| `STYLE_SECTION` | `str` | `"blue"` for section headers and info panels. |
+| `STYLE_SUCCESS` | `str` | `"green"` for completion/success. |
+| `STYLE_WARNING` | `str` | `"yellow"` for warnings. |
+| `STYLE_DIM` | `str` | `"dim"` for separators. |
+| `THEMES` | `dict[str, Theme]` | Built-in themes: default, ngate, muted, high_contrast, mono, nord, dracula. |
+| `THEME_STYLE_SECTION` | `str` | Theme key `"section"` for section headers/panels. |
+| `THEME_STYLE_SUCCESS` | `str` | Theme key `"success"` for completion/success. |
+| `THEME_STYLE_WARNING` | `str` | Theme key `"warning"` for warnings. |
+| `THEME_STYLE_DIM` | `str` | Theme key `"dim"` for separators. |
+| `get_theme(name)` | `(str) -> Theme` | Return a built-in theme by name. |
+| `themed_console(theme_name, **kwargs)` | `() -> Console` | Console using a built-in theme. |
 | `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. |
+| `section_rule(title, style=...)` | `() -> Rule` | Rule with bold section title. |
+| `dim_rule()` | `() -> Rule` | Dim Rule separator. |
+| `key_value_panel(lines, ...)` | `() -> Panel` | Panel from (label, value) pairs or preformatted lines; optional title, border_style, padding. |
 | `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.1.dist-info/RECORD

@@ -0,0 +1,5 @@
+rich_transient/__init__.py,sha256=lkYJVgetzboXM5neeGXq8r2V4cc3BubBc4e1OgrJXSY,13092
+rich_transient-0.1.1.dist-info/METADATA,sha256=Tx8-bFA94sJfKRZKTC-aMDgK4hXImaAA_DIpbNFJJDs,12254
+rich_transient-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+rich_transient-0.1.1.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+rich_transient-0.1.1.dist-info/RECORD,,

rich_transient-0.1.0.dist-info/RECORD

@@ -1,5 +0,0 @@
-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,,