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

sqliter/tui/demos/string_filters.py

@@ -0,0 +1,210 @@
+"""String Filter demos."""
+
+from __future__ import annotations
+
+import io
+
+from sqliter import SqliterDB
+from sqliter.model import BaseDBModel
+from sqliter.tui.demos.base import Demo, DemoCategory, extract_demo_code
+
+
+def _run_startswith() -> str:
+    """Filter strings that start with a specific prefix.
+
+    Use __startswith to match records where a field begins with
+    the specified value.
+    """
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        username: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(User)
+
+    db.insert(User(username="alice_wonder"))
+    db.insert(User(username="alice_smith"))
+    db.insert(User(username="bob_builder"))
+
+    # Find usernames starting with "alice"
+    results = db.select(User).filter(username__startswith="alice").fetch_all()
+    output.write(f"Users starting with 'alice': {len(results)}\n")
+    for user in results:
+        output.write(f"  - {user.username}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_endswith() -> str:
+    """Filter strings that end with a specific suffix.
+
+    Use __endswith to match records where a field ends with
+    the specified value.
+    """
+    output = io.StringIO()
+
+    class File(BaseDBModel):
+        filename: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(File)
+
+    db.insert(File(filename="document.txt"))
+    db.insert(File(filename="image.png"))
+    db.insert(File(filename="notes.txt"))
+    db.insert(File(filename="data.csv"))
+
+    # Find files ending with ".txt"
+    results = db.select(File).filter(filename__endswith=".txt").fetch_all()
+    output.write(f"Text files: {len(results)}\n")
+    for file in results:
+        output.write(f"  - {file.filename}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_contains() -> str:
+    """Filter strings that contain a specific substring.
+
+    Use __contains to match records where a field contains
+    the specified value anywhere within it.
+    """
+    output = io.StringIO()
+
+    class Product(BaseDBModel):
+        name: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(Product)
+
+    db.insert(Product(name="Apple iPhone"))
+    db.insert(Product(name="Samsung Galaxy"))
+    db.insert(Product(name="Apple iPad"))
+    db.insert(Product(name="Google Pixel"))
+
+    # Find products containing "Apple"
+    results = db.select(Product).filter(name__contains="Apple").fetch_all()
+    output.write(f"Products containing 'Apple': {len(results)}\n")
+    for product in results:
+        output.write(f"  - {product.name}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_case_insensitive() -> str:
+    """Filter strings ignoring case with __istartswith and __iendswith.
+
+    Use case-insensitive operators to match strings regardless of
+    capitalization.
+    """
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        email: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(User)
+
+    db.insert(User(email="ALICE@example.com"))
+    db.insert(User(email="bob@EXAMPLE.com"))
+    db.insert(User(email="charlie@test.com"))
+
+    # Find emails ending with "@example.com" (case-insensitive)
+    results = (
+        db.select(User).filter(email__iendswith="@example.com").fetch_all()
+    )
+    output.write(f"Emails ending with '@example.com': {len(results)}\n")
+    for user in results:
+        output.write(f"  - {user.email}\n")
+
+    # Find emails starting with "BOB" (case-insensitive)
+    bob_results = db.select(User).filter(email__istartswith="BOB").fetch_all()
+    output.write(f"\nEmails starting with 'BOB': {len(bob_results)}\n")
+    for user in bob_results:
+        output.write(f"  - {user.email}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_icontains() -> str:
+    """Filter strings containing a substring, ignoring case.
+
+    Use __icontains for case-insensitive substring matching.
+    """
+    output = io.StringIO()
+
+    class Article(BaseDBModel):
+        title: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(Article)
+
+    db.insert(Article(title="Python Programming Guide"))
+    db.insert(Article(title="Advanced PYTHON Techniques"))
+    db.insert(Article(title="Web Development"))
+    db.insert(Article(title="python for Beginners"))
+
+    # Find articles containing "python" (case-insensitive)
+    results = db.select(Article).filter(title__icontains="python").fetch_all()
+    output.write(f"Articles containing 'python': {len(results)}\n")
+    for article in results:
+        output.write(f"  - {article.title}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the String Filters demo category."""
+    return DemoCategory(
+        id="string_filters",
+        title="String Filters",
+        icon="",
+        demos=[
+            Demo(
+                id="string_startswith",
+                title="Starts With (__startswith)",
+                description="Match strings starting with prefix",
+                category="string_filters",
+                code=extract_demo_code(_run_startswith),
+                execute=_run_startswith,
+            ),
+            Demo(
+                id="string_endswith",
+                title="Ends With (__endswith)",
+                description="Match strings ending with suffix",
+                category="string_filters",
+                code=extract_demo_code(_run_endswith),
+                execute=_run_endswith,
+            ),
+            Demo(
+                id="string_contains",
+                title="Contains (__contains)",
+                description="Match strings containing substring",
+                category="string_filters",
+                code=extract_demo_code(_run_contains),
+                execute=_run_contains,
+            ),
+            Demo(
+                id="string_case_insensitive",
+                title="Case-Insensitive (__i*)",
+                description="Match strings ignoring case",
+                category="string_filters",
+                code=extract_demo_code(_run_case_insensitive),
+                execute=_run_case_insensitive,
+            ),
+            Demo(
+                id="string_icontains",
+                title="Contains Case-Insensitive",
+                description="Match substring ignoring case",
+                category="string_filters",
+                code=extract_demo_code(_run_icontains),
+                execute=_run_icontains,
+            ),
+        ],
+    )

sqliter/tui/demos/timestamps.py

@@ -0,0 +1,126 @@
+"""Auto Timestamp demos."""
+
+from __future__ import annotations
+
+import io
+import time
+from datetime import datetime, timezone
+
+from sqliter import SqliterDB
+from sqliter.model import BaseDBModel
+from sqliter.tui.demos.base import Demo, DemoCategory, extract_demo_code
+
+
+def _run_created_at() -> str:
+    """Automatically track when records are created.
+
+    The created_at field is set automatically when you insert a record.
+    """
+    output = io.StringIO()
+
+    class Article(BaseDBModel):
+        title: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(Article)
+
+    article1 = db.insert(Article(title="First Post"))
+    dt1 = datetime.fromtimestamp(article1.created_at, tz=timezone.utc)
+    formatted_dt1 = dt1.strftime("%Y-%m-%d %H:%M:%S")
+    output.write(f"Article: {article1.title}\n")
+    output.write(f"Created: {article1.created_at} ({formatted_dt1} UTC)\n")
+
+    time.sleep(0.1)
+
+    article2 = db.insert(Article(title="Second Post"))
+    dt2 = datetime.fromtimestamp(article2.created_at, tz=timezone.utc)
+    formatted_dt2 = dt2.strftime("%Y-%m-%d %H:%M:%S")
+    output.write(f"\nArticle: {article2.title}\n")
+    output.write(f"Created: {article2.created_at} ({formatted_dt2} UTC)\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_updated_at() -> str:
+    """Automatically track when records are last modified.
+
+    The updated_at field changes automatically when you update a record.
+    """
+    output = io.StringIO()
+
+    class Task(BaseDBModel):
+        title: str
+        done: bool = False
+
+    db = SqliterDB(memory=True)
+    db.create_table(Task)
+
+    task = db.insert(Task(title="Original Task"))
+    created_dt = datetime.fromtimestamp(task.created_at, tz=timezone.utc)
+    updated_dt = datetime.fromtimestamp(task.updated_at, tz=timezone.utc)
+    formatted_created_dt = created_dt.strftime("%Y-%m-%d %H:%M:%S")
+    formatted_updated_dt = updated_dt.strftime("%Y-%m-%d %H:%M:%S")
+    output.write(f"Task: {task.title}\n")
+    output.write(f"Created: {task.created_at} ({formatted_created_dt} UTC)\n")
+    output.write(f"Updated: {task.updated_at} ({formatted_updated_dt} UTC)\n")
+
+    # Sleep for 1 second to ensure different timestamps on fast machines
+    time.sleep(1)
+
+    task.title = "Updated Task"
+    task.done = True
+    db.update(task)
+    updated_task = task
+    updated_created_dt = datetime.fromtimestamp(
+        updated_task.created_at, tz=timezone.utc
+    )
+    updated_updated_dt = datetime.fromtimestamp(
+        updated_task.updated_at, tz=timezone.utc
+    )
+    formatted_updated_created_dt = updated_created_dt.strftime(
+        "%Y-%m-%d %H:%M:%S"
+    )
+    formatted_updated_updated_dt = updated_updated_dt.strftime(
+        "%Y-%m-%d %H:%M:%S"
+    )
+    output.write("\nAfter update:\n")
+    output.write(f"Title: {updated_task.title}\n")
+    output.write(
+        f"Created: {updated_task.created_at} "
+        f"({formatted_updated_created_dt} UTC)\n"
+    )
+    output.write(
+        f"Updated: {updated_task.updated_at} "
+        f"({formatted_updated_updated_dt} UTC)\n"
+    )
+
+    db.close()
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the Auto Timestamp demo category."""
+    return DemoCategory(
+        id="timestamps",
+        title="Auto Timestamps",
+        icon="",
+        demos=[
+            Demo(
+                id="timestamp_created",
+                title="Auto created_at",
+                description="Track when records are created",
+                category="timestamps",
+                code=extract_demo_code(_run_created_at),
+                execute=_run_created_at,
+            ),
+            Demo(
+                id="timestamp_updated",
+                title="Auto updated_at",
+                description="Track when records are modified",
+                category="timestamps",
+                code=extract_demo_code(_run_updated_at),
+                execute=_run_updated_at,
+            ),
+        ],
+    )

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)