sqliter-py 0.9.0__py3-none-any.whl → 0.16.0__py3-none-any.whl

sqliter/tui/__init__.py

@@ -0,0 +1,62 @@
+"""TUI demo application for SQLiter.
+
+This module provides an interactive terminal-based demonstration of SQLiter
+features using the Textual library.
+
+Usage:
+    python -m sqliter.tui
+    # or
+    sqliter-demo
+
+Requires:
+    uv add sqliter-py[demo]
+"""
+
+from __future__ import annotations
+
+from importlib.util import find_spec
+from typing import TYPE_CHECKING
+
+_TEXTUAL_AVAILABLE = find_spec("textual") is not None
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sqliter.tui.app import SQLiterDemoApp
+
+
+def _missing_dependency_error() -> None:
+    """Raise informative error when textual is not installed."""
+    msg = (
+        "The SQLiter TUI demo requires the 'textual' library.\n"
+        "Install it with: uv add sqliter-py[demo]\n"
+    )
+    raise ImportError(msg)
+
+
+def get_app() -> SQLiterDemoApp:
+    """Get the TUI application instance.
+
+    Returns:
+        The SQLiterDemoApp instance.
+
+    Raises:
+        ImportError: If textual is not installed.
+    """
+    if not _TEXTUAL_AVAILABLE:
+        _missing_dependency_error()
+
+    from sqliter.tui.app import SQLiterDemoApp  # noqa: PLC0415
+
+    return SQLiterDemoApp()
+
+
+def run() -> None:
+    """Run the TUI demo application.
+
+    Raises:
+        ImportError: If textual is not installed.
+    """
+    app = get_app()
+    app.run()
+
+
+__all__ = ["get_app", "run"]

sqliter/tui/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running SQLiter TUI as a module."""
+
+from sqliter.tui import run
+
+if __name__ == "__main__":  # pragma: no cover
+    run()

sqliter/tui/app.py

@@ -0,0 +1,179 @@
+"""Main SQLiter TUI demo application."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from typing import TYPE_CHECKING, ClassVar, cast
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import (
+    Container,
+    Horizontal,
+    Vertical,
+    VerticalScroll,
+)
+from textual.css.query import NoMatches
+from textual.screen import ModalScreen
+from textual.widgets import Button, Footer, Header, Markdown, Tree
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sqliter.tui.demos.base import Demo
+
+from sqliter.tui.demos import DemoRegistry
+from sqliter.tui.runner import run_demo
+from sqliter.tui.widgets import (
+    CodeDisplay,
+    DemoList,
+    DemoSelected,
+    OutputDisplay,
+)
+
+
+class HelpScreen(ModalScreen[None]):
+    """Modal help screen."""
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("escape", "dismiss", "Close"),
+        Binding("q", "dismiss", "Close"),
+    ]
+
+    def compose(self) -> ComposeResult:
+        """Compose the help screen."""
+        with VerticalScroll(id="help-scroll"):
+            yield Markdown(
+                """
+# SQLiter Demo - Help
+
+## Navigation
+
+| Key | Action |
+|-----|--------|
+| Up/Down or j/k | Navigate demo list |
+| Left/Right or h/l | Collapse/expand category |
+| Enter | Select demo / Run demo |
+| Tab | Move focus between panels |
+
+## Actions
+
+| Key | Action |
+|-----|--------|
+| F5 | Run selected demo |
+| F8 | Clear output |
+| ? or F1 | Show this help |
+| q | Quit application |
+
+## Mouse
+
+- Click categories to expand/collapse
+- Click demos to select and view code
+- Click buttons to run/clear
+
+Press Escape or q to close this help.
+                """,
+                id="help-content",
+            )
+
+
+class SQLiterDemoApp(App[None]):
+    """Main SQLiter TUI demo application."""
+
+    CSS_PATH = "styles/app.tcss"
+    TITLE = "SQLiter Interactive Demo"
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("q", "quit", "Quit", show=True, priority=True),
+        Binding("f5", "run_demo", "Run", show=True),
+        Binding("f8", "clear_output", "Clear", show=True),
+        Binding("question_mark", "show_help", "Help", show=True),
+        Binding("f1", "show_help", show=False),
+        Binding("j", "tree_cursor_down", show=False),
+        Binding("k", "tree_cursor_up", show=False),
+    ]
+
+    def __init__(self) -> None:
+        """Initialize the application."""
+        super().__init__()
+        self._current_demo: Demo | None = None
+
+    def compose(self) -> ComposeResult:
+        """Compose the application layout."""
+        yield Header()
+        with Container(id="main-container"):
+            yield DemoList(id="demo-list")
+            with Vertical(id="right-panel"):
+                yield CodeDisplay(widget_id="code-display")
+                yield OutputDisplay(widget_id="output-display")
+                with Horizontal(id="button-bar"):
+                    yield Button(
+                        "Run Demo (F5)", id="run-btn", variant="primary"
+                    )
+                    yield Button("Clear Output (F8)", id="clear-btn")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Set initial focus on the demo list."""
+        with suppress(NoMatches):
+            demo_list = self.query_one("#demo-list", DemoList)
+            tree = demo_list.query_one("#demo-tree", Tree)
+            tree.focus()
+
+    def on_demo_selected(self, event: DemoSelected) -> None:
+        """Handle demo selection from the list."""
+        self._current_demo = event.demo
+        code_display = self.query_one("#code-display", CodeDisplay)
+        code_display.set_code(DemoRegistry.get_demo_code(event.demo.id))
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle button presses."""
+        if event.button.id == "run-btn":
+            self.action_run_demo()
+        elif event.button.id == "clear-btn":
+            self.action_clear_output()
+
+    def action_run_demo(self) -> None:
+        """Run the currently selected demo."""
+        if self._current_demo is None:
+            output_display = self.query_one("#output-display", OutputDisplay)
+            output_display.show_output(
+                "Please select a demo first.", success=False
+            )
+            return
+
+        result = run_demo(self._current_demo)
+        output_display = self.query_one("#output-display", OutputDisplay)
+
+        if result.success:
+            output_display.show_output(result.output, success=True)
+        else:
+            output_display.show_error(
+                result.error or "Unknown error",
+                result.traceback,
+            )
+
+    def action_clear_output(self) -> None:
+        """Clear the output display."""
+        output_display = self.query_one("#output-display", OutputDisplay)
+        output_display.clear()
+
+    def action_show_help(self) -> None:
+        """Show the help screen."""
+        self.push_screen(HelpScreen())
+
+    def action_tree_cursor_down(self) -> None:
+        """Move cursor down in the tree (vim-style j key)."""
+        try:
+            demo_list = self.query_one(DemoList)
+            tree = cast("Tree[object]", demo_list.query_one("#demo-tree"))
+            tree.action_cursor_down()
+        except NoMatches:
+            pass  # Tree might not be focused
+
+    def action_tree_cursor_up(self) -> None:
+        """Move cursor up in the tree (vim-style k key)."""
+        try:
+            demo_list = self.query_one(DemoList)
+            tree = cast("Tree[object]", demo_list.query_one("#demo-tree"))
+            tree.action_cursor_up()
+        except NoMatches:
+            pass  # Tree might not be focused

sqliter/tui/demos/__init__.py

@@ -0,0 +1,96 @@
+"""Demo registry for managing all available demos."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from sqliter.tui.demos import (
+    caching,
+    connection,
+    constraints,
+    crud,
+    errors,
+    field_selection,
+    filters,
+    models,
+    ordering,
+    orm,
+    results,
+    string_filters,
+    timestamps,
+    transactions,
+)
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Sequence
+
+    from sqliter.tui.demos.base import Demo, DemoCategory
+
+
+class DemoRegistry:
+    """Registry for all available demos."""
+
+    _categories: ClassVar[list[DemoCategory]] = []
+    _demos_by_id: ClassVar[dict[str, Demo]] = {}
+
+    @classmethod
+    def register_category(cls, category: DemoCategory) -> None:
+        """Register a demo category with all its demos."""
+        cls._categories.append(category)
+        for demo in category.demos:
+            if demo.id in cls._demos_by_id:
+                msg = f"Duplicate demo id: {demo.id}"
+                raise ValueError(msg)
+            cls._demos_by_id[demo.id] = demo
+
+    @classmethod
+    def get_categories(cls) -> Sequence[DemoCategory]:
+        """Get all registered categories in order."""
+        return tuple(cls._categories)
+
+    @classmethod
+    def get_demo(cls, demo_id: str) -> Demo | None:
+        """Get a demo by its unique ID."""
+        return cls._demos_by_id.get(demo_id)
+
+    @classmethod
+    def get_demo_code(cls, demo_id: str) -> str:
+        """Get the display code for a demo (including setup if any)."""
+        demo = cls.get_demo(demo_id)
+        if demo is None:
+            return ""
+        code_parts: list[str] = []
+        if demo.setup_code:
+            code_parts.append(f"# Setup\n{demo.setup_code}\n")
+        code_parts.append(demo.code)
+        return "\n".join(code_parts)
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the registry (for testing).
+
+        After calling reset(), call _init_registry() to repopulate.
+        """
+        cls._categories = []
+        cls._demos_by_id = {}
+
+
+def _init_registry() -> None:
+    """Initialize the demo registry with all categories."""
+    DemoRegistry.register_category(connection.get_category())
+    DemoRegistry.register_category(models.get_category())
+    DemoRegistry.register_category(crud.get_category())
+    DemoRegistry.register_category(filters.get_category())
+    DemoRegistry.register_category(results.get_category())
+    DemoRegistry.register_category(ordering.get_category())
+    DemoRegistry.register_category(field_selection.get_category())
+    DemoRegistry.register_category(string_filters.get_category())
+    DemoRegistry.register_category(constraints.get_category())
+    DemoRegistry.register_category(orm.get_category())
+    DemoRegistry.register_category(caching.get_category())
+    DemoRegistry.register_category(timestamps.get_category())
+    DemoRegistry.register_category(transactions.get_category())
+    DemoRegistry.register_category(errors.get_category())
+
+
+_init_registry()

sqliter/tui/demos/base.py

@@ -0,0 +1,114 @@
+"""Base classes for demo definitions."""
+
+from __future__ import annotations
+
+import inspect
+import textwrap
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Callable
+
+
+def extract_demo_code(func: Callable[..., str]) -> str:
+    """Extract and format source code from a demo function.
+
+    This function uses Python's inspect module to dynamically extract the
+    source code from a demo function, ensuring the displayed code always
+    matches what's actually executed.
+
+    Removes demo infrastructure (function definition, output setup, return)
+    but keeps the docstring for context.
+
+    Args:
+        func: The demo function to extract code from
+
+    Returns:
+        Formatted source code string with proper dedentation and whitespace
+    """
+    # Get the source code and split into lines
+    source = inspect.getsource(func)
+    lines = source.splitlines()
+
+    # Skip decorator lines and function definition
+    start_idx = 0
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped.startswith(("def ", "async def ")):
+            start_idx = i + 1
+            break
+    lines = lines[start_idx:]
+
+    # Dedent the remaining code
+    code = textwrap.dedent("\n".join(lines))
+    lines = code.splitlines()
+
+    # Filter out unwanted lines
+    filtered: list[str] = []
+    for original_line in lines:
+        # Skip output setup
+        if "output = io.StringIO()" in original_line:
+            continue
+        # Rename output.write to print
+        line = original_line
+        if "output.write(" in line:
+            line = line.replace("output.write(", "print(")
+        # Stop at return statement
+        if "return output.getvalue()" in line:
+            break
+
+        filtered.append(line)
+
+    # Remove trailing empty lines
+    while filtered and not filtered[-1].strip():
+        filtered.pop()
+
+    return "\n".join(filtered).strip()
+
+
+__all__ = ["Demo", "DemoCategory", "extract_demo_code"]
+
+
+@dataclass
+class Demo:
+    """Represents a single demo example.
+
+    Attributes:
+        id: Unique identifier for the demo (e.g., "conn_memory")
+        title: Display title in the list (e.g., "In-memory Database")
+        description: Brief description shown as tooltip/subtitle
+        category: Category ID this demo belongs to
+        code: The Python code to display (syntax highlighted)
+        execute: Callable that runs the demo and returns output string
+        setup_code: Optional setup code shown before main code
+        teardown: Optional cleanup function called after execution
+    """
+
+    id: str
+    title: str
+    description: str
+    category: str
+    code: str
+    execute: Callable[[], str]
+    setup_code: Optional[str] = None
+    teardown: Optional[Callable[[], None]] = None
+
+
+@dataclass
+class DemoCategory:
+    """A category of related demos.
+
+    Attributes:
+        id: Unique identifier (e.g., "connection")
+        title: Display title (e.g., "Connection & Setup")
+        icon: Optional emoji icon for the category
+        demos: List of demos in this category
+        expanded: Whether category starts expanded in the tree
+    """
+
+    id: str
+    title: str
+    icon: str = ""
+    demos: list[Demo] = field(default_factory=list)
+    expanded: bool = False