beautiful-python-cli 0.0.0-stage → 1.0.0

package/references/layouts-and-tui.md

@@ -0,0 +1,57 @@
+# Layouts and Terminal User Interfaces (TUIs)
+
+Use `rich.layout.Layout` to partition the terminal screen into responsive grids, sidebars, headers, and footers for dashboards and monitoring tools.
+
+## 1. Basic Layout Hierarchy
+
+```python
+from rich.layout import Layout
+from rich.panel import Panel
+
+layout = Layout()
+
+# Split into header, body, and footer
+layout.split_column(
+    Layout(name="header", size=3),
+    Layout(name="body", ratio=1),
+    Layout(name="footer", size=3),
+)
+
+# Split the body into sidebar and main area
+layout["body"].split_row(
+    Layout(name="sidebar", ratio=1),
+    Layout(name="main", ratio=3),
+)
+
+# Populate panels
+layout["header"].update(Panel("[accent]Monitoring Dashboard[/accent]", style="bold"))
+layout["sidebar"].update(Panel("Node Status\n• Node 1: [success]OK[/success]\n• Node 2: [warning]BUSY[/warning]"))
+layout["main"].update(Panel("Recent Telemetry Events", border_style="cyan"))
+layout["footer"].update(Panel("[muted]Press Ctrl+C to exit | Refresh: 1.0s[/muted]"))
+
+console.print(layout)
+```
+
+## 2. Dynamic Live TUI
+
+Combine `Layout` with `rich.live.Live` for continuously updating full-screen or embedded monitoring:
+
+```python
+import time
+from rich.live import Live
+
+with Live(layout, console=console, screen=False, refresh_per_second=4) as live:
+    try:
+        while True:
+            # Update individual panes without re-creating the layout tree
+            layout["main"].update(render_telemetry_table())
+            time.sleep(0.25)
+    except KeyboardInterrupt:
+        pass
+```
+
+## 3. Best Practices
+- **Use `screen=False` by default**: Leaves scrollback history intact when the command terminates. Only use `screen=True` for full-screen curses-style apps.
+- **Set fixed `size` for headers and footers**: Let the body use `ratio=1` to absorb the remaining vertical space.
+- **Test at 80x24**: Ensure the layout degrades gracefully in small terminal windows without raising truncation errors.
+- **Provide clean exit handling**: Catch `KeyboardInterrupt` cleanly so the terminal state restores properly.

package/references/prompts-and-inputs.md

@@ -0,0 +1,91 @@
+# Interactive Prompts and User Input
+
+Use `rich.prompt` to collect interactive input from users in terminal sessions while preserving styling and validation.
+
+## 1. Text Prompt
+
+Collect strings with default values and styling:
+
+```python
+from rich.prompt import Prompt
+
+# Basic prompt with default
+username = Prompt.ask("Enter username", default="admin", console=console)
+
+# Styled prompt with required non-empty input
+project = Prompt.ask(
+    "[bold cyan]Project name[/bold cyan]",
+    default="my-cli",
+    console=console,
+)
+```
+
+## 2. Constrained Choices
+
+Restrict input to a list of allowed values:
+
+```python
+env = Prompt.ask(
+    "Deployment target",
+    choices=["development", "staging", "production"],
+    default="development",
+    case_sensitive=False,
+    console=console,
+)
+```
+
+Rich automatically validates user input against the choices, re-prompting with an error message if an invalid value is entered.
+
+## 3. Confirmations (Yes/No)
+
+Ask binary questions:
+
+```python
+from rich.prompt import Confirm
+
+if Confirm.ask("Proceed with deployment?", default=True, console=console):
+    console.print("[success]Deploying…[/success]")
+else:
+    console.print("[warning]Aborted by user.[/warning]")
+    raise SystemExit(1)
+```
+
+## 4. Typed Numeric Prompts
+
+Enforce integers or floats:
+
+```python
+from rich.prompt import IntPrompt, FloatPrompt
+
+port = IntPrompt.ask("Listen port", default=8080, console=console)
+rate = FloatPrompt.ask("Sample rate", default=0.05, console=console)
+```
+
+## 5. Password & Secret Input
+
+Hide input characters for credentials, tokens, or private keys:
+
+```python
+api_key = Prompt.ask(
+    "[accent]API Token[/accent]",
+    password=True,
+    console=console,
+)
+```
+
+Never print the collected secret back to the terminal or logs.
+
+## 6. Non-Interactive Fallbacks & Guardrails
+
+Interactive prompts will fail or block indefinitely in CI/CD, cron jobs, or redirected stdin (`sys.stdin.isatty() is False`). Always guard prompts:
+
+```python
+import sys
+
+def get_target_environment(cli_flag: str | None) -> str:
+    if cli_flag:
+        return cli_flag
+    if not sys.stdin.isatty():
+        return "development"  # Non-interactive default or fail explicitly
+    return Prompt.ask("Target environment", choices=["dev", "prod"], default="dev")
+```

package/references/rich-components.md

@@ -0,0 +1,118 @@
+# Rich components and API selection
+
+Use this as a focused API map. Confirm exact signatures against the Rich version already installed in the project.
+
+## Console and themes
+
+Create one application-level console. Keep stdout and stderr separate when the command supports machine-readable output.
+
+```python
+from rich.console import Console
+from rich.theme import Theme
+
+theme = Theme({
+    "success": "bold green",
+    "warning": "bold yellow",
+    "error": "bold red",
+    "info": "cyan",
+    "muted": "dim",
+    "accent": "bold bright_magenta",
+})
+
+console = Console(theme=theme)
+error_console = Console(stderr=True, theme=theme)
+```
+
+Do not set `force_terminal=True` in normal application code. Let Rich detect terminal capability. Use `no_color=True` only when an explicit no-color mode is selected.
+
+## Core renderables
+
+| Component | Use it for |
+|---|---|
+| `Panel` | A cohesive summary, warning, or grouped section |
+| `Table` | Structured rows and columns |
+| `Rule` | Major section separators |
+| `Columns` | Compact side-by-side renderables |
+| `Group` | Grouping multiple renderables into one display |
+| `Tree` | Hierarchical data such as directories or attack paths |
+| `Layout` | Responsive screen partitioning (header, body, sidebar, footer) |
+| `Prompt` / `Confirm` | Interactive user input with validation and defaults |
+| `Syntax` | Source code with syntax highlighting |
+| `Traceback` | Readable, formatted stack traces with frame suppression |
+| `Markdown` | Render Markdown in a terminal |
+| `Pretty` / `inspect` | Object introspection and structure formatting |
+| `Text` | Fine-grained spans, styling, and markup-safe text |
+
+Example:
+
+```python
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+table = Table(title="Findings", expand=True)
+table.add_column("Severity", no_wrap=True)
+table.add_column("Finding", ratio=2)
+table.add_column("Status", justify="right")
+
+table.add_row(
+    Text("HIGH", style="bold red"),
+    "Unauthenticated endpoint disclosure",
+    "[warning]Needs review[/warning]",
+)
+
+console.print(Panel(table, title="[accent]Assessment summary[/accent]"))
+```
+
+## Tables
+
+- Use `expand=True` when the table should occupy available width; otherwise let it size naturally.
+- Use `ratio` to allocate flexible width between descriptive columns.
+- Use `no_wrap=True` only for short values such as IDs, severity, and status.
+- Use `overflow="fold"` for descriptions that must remain readable; use `ellipsis` for secondary text.
+- Right-align numeric columns.
+- Add a table caption or explicit empty-state text when no records exist.
+- Avoid very wide tables. Prefer a concise default view and an optional verbose/details view.
+
+## Progress columns
+
+Common columns:
+
+- `SpinnerColumn`
+- `TextColumn`
+- `BarColumn`
+- `TaskProgressColumn`
+- `MofNCompleteColumn`
+- `TimeElapsedColumn`
+- `TimeRemainingColumn`
+- `DownloadColumn`
+- `TransferSpeedColumn`
+- `FileSizeColumn`
+
+Build a reusable `Progress` factory if multiple commands share the same style. Use only columns whose values are meaningful for the task.
+
+## Logging
+
+Use `rich.logging.RichHandler` with the standard `logging` module when possible. Configure it once at the CLI boundary. Avoid configuring handlers from imported library modules.
+
+## Windows and UTF-8 terminal compatibility
+
+On Windows systems (PowerShell / Command Prompt), ensure UTF-8 encoding is enabled to avoid `UnicodeEncodeError`:
+
+```python
+import sys
+
+# Ensure UTF-8 output encoding for terminals
+if sys.platform == "win32" and sys.stdout.encoding.lower() != "utf-8":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except AttributeError:
+        pass
+```
+
+Rich natively handles Windows console color (VT100) via colorama integration. Avoid manual ANSI sequences.
+
+## Dependency policy
+
+Rich is the core dependency. Typer, Click, Questionary, Loguru, and PyFiglet are optional. Do not add them merely for decoration; use the project's existing CLI and logging stack.

package/references/testing-and-accessibility.md

@@ -0,0 +1,81 @@
+# Testing, accessibility, and output contracts
+
+## Terminal and redirected output
+
+- Let Rich detect terminal capability; do not force ANSI output by default.
+- Disable animated progress when `console.is_terminal` is false.
+- Respect `NO_COLOR` and explicit `--no-color`.
+- Test SSH, CI, redirected stdout, and narrow terminal widths.
+- Do not rely on Unicode symbols being available. Use text labels as a fallback.
+- Never use color as the only indicator of severity or success.
+
+## stdout, stderr, and JSON
+
+If stdout is a machine-readable stream, keep it free of banners, progress bars, logs, and status messages.
+
+```python
+import json
+import sys
+from rich.console import Console
+
+data_console = Console(file=sys.stdout, no_color=True)
+diagnostic_console = Console(file=sys.stderr)
+
+if args.json:
+    json.dump(result, sys.stdout)
+    sys.stdout.write("\n")
+else:
+    render_human_result(data_console, result)
+```
+
+Send progress and diagnostics to stderr when stdout is reserved for JSON, CSV, or another pipeable format. Keep `--quiet`, `--plain`, and `--json` behavior documented and tested.
+
+## Narrow widths
+
+- Avoid hardcoded terminal widths in normal rendering.
+- Use flexible table columns and wrapping.
+- Test at widths such as 40, 60, 80, and 120 columns.
+- Keep essential identifiers visible; wrap or truncate only secondary descriptions.
+
+## Snapshot and unit testing
+
+Rich supports an in-memory console:
+
+```python
+from io import StringIO
+from rich.console import Console
+
+buffer = StringIO()
+test_console = Console(
+    file=buffer,
+    force_terminal=True,
+    width=80,
+    record=True,
+)
+test_console.print("[success]Completed[/success]")
+
+plain_text = test_console.export_text(styles=False)
+assert "Completed" in plain_text
+```
+
+Test semantic content, not brittle ANSI escape sequences. Add tests for:
+- empty result sets
+- success and failure states
+- exceptions and Ctrl-C/cancellation
+- `--no-color` / `NO_COLOR`
+- non-TTY and redirected output
+- JSON purity
+- narrow terminal widths
+- progress completion and cleanup
+
+For deterministic snapshots, fix time values and avoid asserting spinner animation frames.
+
+## UX checklist
+
+- Can a user identify the current operation immediately?
+- Is the difference between unknown progress and measurable progress clear?
+- Are success, warning, and failure distinguishable without color?
+- Are tables readable when the terminal is narrow?
+- Can users copy results without decorative noise?
+- Does the application still work when output is piped?
+- Does every spinner/live display stop on all exit paths?

package/references/tracebacks-and-debugging.md

@@ -0,0 +1,88 @@
+# Tracebacks, Syntax, and Introspection
+
+Use Rich's diagnostics to make errors actionable and debugging intuitive without leaking internal implementation details to end users.
+
+## 1. Polished Tracebacks
+
+Install Rich's traceback handler at the application boundary (entry point):
+
+```python
+from rich.traceback import install
+
+# Production mode: concise, syntax-highlighted tracebacks with suppressed internal frames
+install(
+    show_locals=False,
+    max_frames=5,
+    suppress=["click", "typer", "urllib3", "requests"],
+)
+
+# Debug mode (--debug / --verbose): include local variable values for troubleshooting
+if debug_mode:
+    install(show_locals=True, max_frames=20)
+```
+
+### Guidelines
+- In production, keep `show_locals=False` to prevent leaking sensitive variables (tokens, passwords, PII) in stack dumps.
+- Suppress framework frames (`click`, `typer`, `asyncio`) to direct attention to user-authored code.
+- For expected operational errors (e.g. file not found, bad network connection), print a concise error panel instead of dumping a full stack trace:
+
+```python
+try:
+    connect_to_server(host)
+except ConnectionError as err:
+    error_console.print(
+        Panel(
+            f"[error]Could not connect to {host}:[/error] {err}\n"
+            "[muted]Check your network connection or verify --host.[/muted]",
+            title="[error]Connection Failed[/error]",
+            border_style="red",
+        )
+    )
+    raise SystemExit(1)
+```
+
+## 2. Syntax Highlighting
+
+Render snippets of Python, JSON, YAML, or SQL directly in the terminal:
+
+```python
+from rich.syntax import Syntax
+
+code_snippet = """def hello(name: str) -> str:
+    return f"Hello, {name}!"
+"""
+
+syntax = Syntax(
+    code_snippet,
+    lexer="python",
+    theme="monokai",
+    line_numbers=True,
+    word_wrap=True,
+)
+console.print(syntax)
+```
+
+## 3. Object Introspection with `inspect`
+
+Debug complex objects, types, or modules interactively:
+
+```python
+from rich import inspect
+
+# Inspect attributes and methods
+inspect(my_object, methods=True)
+
+# Inspect with docstrings and help
+inspect(my_object, help=True)
+```
+
+## 4. Pretty-Printing Structures
+
+Format complex dictionaries, lists, or dataclasses without messy `pprint`:
+
+```python
+from rich.pretty import pprint
+
+data = {"user": "alice", "roles": ["admin", "developer"], "active": True}
+pprint(data, indent_guides=True, expand_all=False)
+```

package/requirements.txt

@@ -0,0 +1 @@
+rich>=13.7