sqliter-py 0.12.0__py3-none-any.whl → 0.17.0__py3-none-any.whl

sqliter/tui/demos/transactions.py

@@ -0,0 +1,177 @@
+"""Transaction demos."""
+
+from __future__ import annotations
+
+import io
+import tempfile
+from pathlib import Path
+
+from sqliter import SqliterDB
+from sqliter.model import BaseDBModel
+from sqliter.tui.demos.base import Demo, DemoCategory, extract_demo_code
+
+
+def _run_context_manager_transaction() -> str:
+    """Use context manager for automatic transaction management.
+
+    The `with db:` block auto-commits on success and rolls back on error.
+    """
+    output = io.StringIO()
+
+    class Account(BaseDBModel):
+        name: str
+        balance: float
+
+    db = SqliterDB(memory=True)
+    db.create_table(Account)
+
+    alice: Account = db.insert(Account(name="Alice", balance=100.0))
+    bob: Account = db.insert(Account(name="Bob", balance=50.0))
+
+    output.write(f"Before: Alice=${alice.balance}, Bob=${bob.balance}\n")
+
+    # Transfer money using context manager
+    with db:
+        alice.balance = alice.balance - 20.0
+        bob.balance = bob.balance + 20.0
+        db.update(alice)
+        db.update(bob)
+        alice_updated = alice
+        bob_updated = bob
+
+    output.write(
+        f"After: Alice=${alice_updated.balance}, Bob=${bob_updated.balance}\n"
+    )
+    output.write("Transaction auto-committed on success\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_rollback() -> str:
+    """Demonstrate transaction rollback behavior.
+
+    When an exception occurs inside a `with db:` block, all changes made
+    within that transaction are automatically rolled back.
+    """
+    output = io.StringIO()
+
+    class Item(BaseDBModel):
+        name: str
+        quantity: int
+
+    # Use file database so we can reconnect after connection closes
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        db_path = f.name
+
+    db = None
+    try:
+        db = SqliterDB(db_filename=db_path)
+        db.create_table(Item)
+
+        item: Item = db.insert(Item(name="Widget", quantity=10))
+        output.write(f"Initial quantity: {item.quantity}\n")
+
+        # Use context manager for automatic rollback on error
+        try:
+            with db:
+                item.quantity = 5
+                db.update(item)
+                output.write("Inside transaction: updated to 5\n")
+                # If error occurs, changes are rolled back
+                error_msg = "Intentional error for rollback"
+                raise RuntimeError(error_msg)  # noqa: TRY301
+        except RuntimeError:
+            output.write("Error occurred - transaction rolled back\n")
+            # Verify rollback with NEW connection
+            db2 = SqliterDB(db_filename=db_path)
+            try:
+                restored = db2.get(Item, item.pk)
+                if restored is not None:
+                    qty_attr = "quantity"  # db.get returns BaseDBModel
+                    restored_quantity = getattr(restored, qty_attr)
+                    msg = f"Database value: {restored_quantity}\n"
+                    output.write(msg)
+                    expected_quantity = 10
+                    if restored_quantity == expected_quantity:
+                        output.write("✓ Rollback worked correctly\n")
+                    else:
+                        msg = (
+                            f"✗ Rollback failed: expected {expected_quantity}, "
+                            f"got {restored_quantity}\n"
+                        )
+                        output.write(msg)
+            finally:
+                db2.close()
+    finally:
+        if db is not None:
+            db.close()
+        Path(db_path).unlink(missing_ok=True)
+
+    return output.getvalue()
+
+
+def _run_manual_commit() -> str:
+    """Manually control transactions with explicit commit.
+
+    Call db.commit() to persist changes when not using context manager.
+    """
+    output = io.StringIO()
+
+    class Log(BaseDBModel):
+        message: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(Log)
+
+    # Manual transaction control
+    db.connect()
+    log1 = db.insert(Log(message="First entry"))
+    output.write(f"Inserted: {log1.message}\n")
+    output.write("Not committed yet\n")
+    db.commit()
+    output.write("Committed\n")
+
+    db.insert(Log(message="Second entry"))
+    db.commit()
+
+    all_logs = db.select(Log).fetch_all()
+    output.write(f"Total logs: {len(all_logs)}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the Transactions demo category."""
+    return DemoCategory(
+        id="transactions",
+        title="Transactions",
+        icon="",
+        demos=[
+            Demo(
+                id="txn_context",
+                title="Context Manager",
+                description="Auto commit/rollback with 'with' statement",
+                category="transactions",
+                code=extract_demo_code(_run_context_manager_transaction),
+                execute=_run_context_manager_transaction,
+            ),
+            Demo(
+                id="txn_rollback",
+                title="Rollback",
+                description="Automatic rollback on errors",
+                category="transactions",
+                code=extract_demo_code(_run_rollback),
+                execute=_run_rollback,
+            ),
+            Demo(
+                id="txn_manual",
+                title="Manual Commit",
+                description="Manually control transactions",
+                category="transactions",
+                code=extract_demo_code(_run_manual_commit),
+                execute=_run_manual_commit,
+            ),
+        ],
+    )

sqliter/tui/runner.py

@@ -0,0 +1,116 @@
+"""Demo execution engine with output capture."""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import traceback
+from contextlib import redirect_stderr, redirect_stdout
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sqliter.tui.demos.base import Demo
+
+
+@dataclass
+class ExecutionResult:
+    """Result of executing a demo.
+
+    Attributes:
+        success: Whether the demo ran without exceptions
+        output: Combined stdout/stderr and returned output
+        error: Exception message if failed
+        traceback: Full traceback string if failed
+    """
+
+    success: bool
+    output: str
+    error: str | None = None
+    traceback: str | None = None
+
+
+class DemoRunner:
+    """Executes demos and captures all output."""
+
+    def __init__(self) -> None:
+        """Initialize the demo runner."""
+        self._last_result: ExecutionResult | None = None
+
+    def run(self, demo: Demo) -> ExecutionResult:
+        """Execute a demo and capture all output.
+
+        Args:
+            demo: The demo to execute.
+
+        Returns:
+            ExecutionResult with output and status.
+        """
+        stdout_capture = io.StringIO()
+        stderr_capture = io.StringIO()
+
+        try:
+            with (
+                redirect_stdout(stdout_capture),
+                redirect_stderr(stderr_capture),
+            ):
+                output = demo.execute()
+
+            # Combine all output sources
+            combined = ""
+            stdout_val = stdout_capture.getvalue()
+            stderr_val = stderr_capture.getvalue()
+
+            if stdout_val:
+                combined += stdout_val
+            if output:
+                if combined and not combined.endswith("\n"):
+                    combined += "\n"
+                combined += output
+            if stderr_val:
+                combined += f"\n[stderr]\n{stderr_val}"
+
+            self._last_result = ExecutionResult(
+                success=True,
+                output=combined or "(No output)",
+            )
+
+        # Catching Exception is necessary here since demo code may raise any
+        # type
+        except Exception:  # noqa: BLE001
+            tb = traceback.format_exc()
+
+            # Combine stdout and stderr for error output
+            combined_output = stdout_capture.getvalue()
+            stderr_val = stderr_capture.getvalue()
+            if stderr_val:
+                combined_output += f"\n[stderr]\n{stderr_val}"
+
+            self._last_result = ExecutionResult(
+                success=False,
+                output=combined_output,
+                error="Exception in demo code",
+                traceback=tb,
+            )
+
+        finally:
+            # Run teardown if defined, ignoring any errors
+            if demo.teardown:
+                with contextlib.suppress(Exception):
+                    demo.teardown()
+
+        return self._last_result
+
+    @property
+    def last_result(self) -> ExecutionResult | None:
+        """Get the last execution result."""
+        return self._last_result
+
+
+# Global runner instance
+_runner = DemoRunner()
+
+
+def run_demo(demo: Demo) -> ExecutionResult:
+    """Run a demo using the global runner."""
+    return _runner.run(demo)

sqliter/tui/styles/app.tcss

@@ -0,0 +1,130 @@
+/* Main application styles for SQLiter TUI Demo */
+
+Screen {
+    background: $surface;
+}
+
+#main-container {
+    layout: grid;
+    grid-size: 2;
+    grid-columns: auto 1fr;
+    height: 100%;
+    padding: 0 1;
+}
+
+/* Left panel - Demo list */
+#demo-list {
+    border: solid $primary;
+    border-title-color: $text;
+    padding: 1;
+}
+
+#demo-list Tree {
+    padding: 0;
+}
+
+#demo-list Tree > .tree--cursor {
+    background: $primary;
+    color: $text;
+}
+
+#demo-list Tree > .tree--highlight {
+    background: $primary 30%;
+}
+
+/* Right panel container */
+#right-panel {
+    padding-left: 1;
+}
+
+/* Code display */
+#code-display {
+    height: 55%;
+    border: solid $primary;
+    border-title-color: $text;
+    padding: 1;
+}
+
+#code-display Static {
+    padding: 0;
+}
+
+/* Output display */
+#output-display {
+    height: 35%;
+    border: solid $secondary;
+    border-title-color: $text;
+    padding: 1;
+}
+
+#output-display.success {
+    border: solid $success;
+}
+
+#output-display.error {
+    border: solid $error;
+}
+
+#output-display Static {
+    padding: 0;
+}
+
+/* Button bar */
+#button-bar {
+    height: auto;
+    align: center middle;
+    padding: 1 0;
+}
+
+#button-bar Button {
+    margin: 0 1;
+}
+
+#run-btn {
+    background: $success;
+}
+
+#clear-btn {
+    background: $primary-darken-2;
+}
+
+/* Help screen */
+HelpScreen {
+    align: center middle;
+}
+
+#help-scroll {
+    width: 70;
+    height: auto;
+    max-height: 80%;
+    padding: 2;
+    border: solid $primary;
+    background: $surface;
+}
+
+#help-content {
+    padding: 0;
+}
+
+/* Footer styling */
+Footer {
+    background: $primary-darken-3;
+}
+
+/* Header styling */
+Header {
+    background: $primary;
+}
+
+/* Scrollbars */
+ScrollableContainer > .scrollbar {
+    background: $surface;
+}
+
+ScrollableContainer > .scrollbar--bar {
+    background: $primary 50%;
+}
+
+ScrollableContainer > .scrollbar--bar:hover {
+    background: $primary;
+}

sqliter/tui/widgets/__init__.py

@@ -0,0 +1,7 @@
+"""TUI widgets for SQLiter demo app."""
+
+from sqliter.tui.widgets.code_display import CodeDisplay
+from sqliter.tui.widgets.demo_list import DemoList, DemoSelected
+from sqliter.tui.widgets.output_display import OutputDisplay
+
+__all__ = ["CodeDisplay", "DemoList", "DemoSelected", "OutputDisplay"]

sqliter/tui/widgets/code_display.py

@@ -0,0 +1,81 @@
+"""Syntax-highlighted code display widget."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.syntax import Syntax
+from textual.containers import ScrollableContainer
+from textual.css.query import NoMatches
+from textual.widgets import Static
+
+if TYPE_CHECKING:  # pragma: no cover
+    from textual.app import ComposeResult
+
+
+class CodeDisplay(ScrollableContainer):
+    """Display syntax-highlighted Python code."""
+
+    def __init__(
+        self,
+        code: str = "",
+        *,
+        widget_id: str | None = None,
+        classes: str | None = None,
+    ) -> None:
+        """Initialize the code display.
+
+        Args:
+            code: Initial code to display.
+            widget_id: Widget ID.
+            classes: CSS classes for the widget.
+        """
+        super().__init__(id=widget_id, classes=classes)
+        self._code = code
+
+    def compose(self) -> ComposeResult:
+        """Compose the code display."""
+        yield Static(id="code-content")
+
+    def on_mount(self) -> None:
+        """Initialize the display on mount."""
+        self._update_display()
+
+    @property
+    def code(self) -> str:
+        """Get the current code."""
+        return self._code
+
+    @code.setter
+    def code(self, value: str) -> None:
+        """Set new code and update display."""
+        self._code = value
+        self._update_display()
+
+    def _update_display(self) -> None:
+        """Update the code display with syntax highlighting."""
+        try:
+            content = self.query_one("#code-content", Static)
+        except NoMatches:
+            return  # Not mounted yet
+
+        if not self._code:
+            content.update("Select a demo to view code")
+            return
+
+        # Use Rich's Syntax for highlighting
+        syntax = Syntax(
+            self._code.strip(),
+            "python",
+            theme="monokai",
+            line_numbers=True,
+            word_wrap=True,
+        )
+        content.update(syntax)
+
+        # Scroll to top when content changes
+        self.scroll_home()
+
+    def set_code(self, code: str) -> None:
+        """Set the code to display (public API)."""
+        self.code = code

sqliter/tui/widgets/demo_list.py

@@ -0,0 +1,65 @@
+"""Demo list widget with expandable categories."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from textual.containers import ScrollableContainer
+from textual.message import Message
+from textual.widgets import Tree
+
+from sqliter.tui.demos import DemoRegistry
+from sqliter.tui.demos.base import Demo, DemoCategory
+
+if TYPE_CHECKING:  # pragma: no cover
+    from textual.app import ComposeResult
+
+
+class DemoSelected(Message):
+    """Message sent when a demo is selected."""
+
+    def __init__(self, demo: Demo) -> None:
+        """Initialize the message.
+
+        Args:
+            demo: The demo that was selected.
+        """
+        self.demo = demo
+        super().__init__()
+
+
+class DemoList(ScrollableContainer):
+    """Scrollable tree of demo categories and items."""
+
+    def compose(self) -> ComposeResult:
+        """Compose the demo tree."""
+        tree: Tree[Demo | DemoCategory] = Tree("SQLiter Demos", id="demo-tree")
+        tree.show_root = False
+
+        # Populate tree with categories and demos
+        for category in DemoRegistry.get_categories():
+            label = (
+                f"{category.icon} {category.title}"
+                if category.icon
+                else category.title
+            )
+            cat_node = tree.root.add(
+                label,
+                data=category,
+                expand=category.expanded,
+            )
+            for demo in category.demos:
+                cat_node.add_leaf(
+                    demo.title,
+                    data=demo,
+                )
+
+        yield tree
+
+    def on_tree_node_selected(
+        self,
+        event: Tree.NodeSelected[Demo | DemoCategory],
+    ) -> None:
+        """Handle tree node selection."""
+        if isinstance(event.node.data, Demo):
+            self.post_message(DemoSelected(event.node.data))

sqliter/tui/widgets/output_display.py

@@ -0,0 +1,92 @@
+"""Output display widget with status indication."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.text import Text
+from textual.containers import ScrollableContainer
+from textual.widgets import Static
+
+if TYPE_CHECKING:  # pragma: no cover
+    from textual.app import ComposeResult
+
+
+class OutputDisplay(ScrollableContainer):
+    """Display demo execution output with status styling."""
+
+    _PLACEHOLDER = "Run a demo to see output here"
+
+    def __init__(
+        self,
+        *,
+        widget_id: str | None = None,
+        classes: str | None = None,
+    ) -> None:
+        """Initialize the output display.
+
+        Args:
+            widget_id: Widget ID.
+            classes: CSS classes for the widget.
+        """
+        super().__init__(id=widget_id, classes=classes)
+
+    def compose(self) -> ComposeResult:
+        """Compose the output display."""
+        yield Static(self._PLACEHOLDER, id="output-content")
+
+    def show_output(self, output: str, *, success: bool = True) -> None:
+        """Display output from demo execution.
+
+        Args:
+            output: The output text to display
+            success: Whether the demo ran successfully
+        """
+        content = self.query_one("#output-content", Static)
+
+        self.remove_class("error", "success")
+        self.add_class("success" if success else "error")
+
+        if success:
+            text = Text()
+            text.append("Success\n\n", style="bold green")
+            text.append(output)
+        else:
+            text = Text()
+            text.append("Error\n\n", style="bold red")
+            text.append(output, style="red")
+
+        content.update(text)
+        self.scroll_home()
+
+    def show_error(
+        self,
+        error: str,
+        traceback_str: str | None = None,
+    ) -> None:
+        """Display an error message.
+
+        Args:
+            error: The error message
+            traceback_str: Optional full traceback
+        """
+        content = self.query_one("#output-content", Static)
+
+        self.remove_class("error", "success")
+        self.add_class("error")
+
+        text = Text()
+        text.append("Error\n\n", style="bold red")
+        text.append(error, style="red")
+        if traceback_str:
+            text.append("\n\nTraceback:\n", style="bold")
+            text.append(traceback_str, style="dim red")
+
+        content.update(text)
+        self.scroll_home()
+
+    def clear(self) -> None:
+        """Clear the output display."""
+        content = self.query_one("#output-content", Static)
+        content.update(self._PLACEHOLDER)
+        self.remove_class("error", "success")