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

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

sqliter/tui/demos/caching.py

@@ -0,0 +1,283 @@
+"""Caching demos."""
+
+from __future__ import annotations
+
+import io
+import tempfile
+import time
+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_enable_cache() -> str:
+    """Demonstrate enabling query result caching for performance.
+
+    Caching stores query results in memory, speeding up repeated queries
+    by avoiding disk I/O. Benefits are most apparent with complex queries
+    and large datasets.
+    """
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        name: str
+        email: str
+        age: int
+
+    # Use file-based database to show real caching benefits
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        db_path = f.name
+
+    db = None
+    try:
+        db = SqliterDB(db_path, cache_enabled=True)
+        db.create_table(User)
+
+        # Insert more data for a more realistic demo
+        for i in range(50):
+            db.insert(
+                User(
+                    name=f"User {i}",
+                    email=f"user{i}@example.com",
+                    age=20 + i,
+                )
+            )
+
+        output.write("Inserted 50 users\n")
+        output.write("Caching stores query results to avoid repeated I/O\n\n")
+
+        # Query with filter (more expensive than simple pk lookup)
+        # First query - cache miss
+        start = time.perf_counter()
+        users = db.select(User).filter(age__gte=40).fetch_all()
+        miss_time = (time.perf_counter() - start) * 1000
+        output.write(f"First query (cache miss): {miss_time:.3f}ms\n")
+        output.write(f"Found {len(users)} users age 40+\n")
+
+        # Second query with same filter - cache hit
+        start = time.perf_counter()
+        users = db.select(User).filter(age__gte=40).fetch_all()
+        hit_time = (time.perf_counter() - start) * 1000
+        output.write(f"Second query (cache hit): {hit_time:.3f}ms\n")
+        output.write(f"Found {len(users)} users age 40+\n")
+
+        # Show speedup
+        if hit_time > 0:
+            speedup = miss_time / hit_time
+            output.write(f"\nCache hit is {speedup:.1f}x faster!\n")
+        output.write("(Benefits increase with query complexity and data size)")
+    finally:
+        if db is not None:
+            db.close()
+        # Cleanup
+        Path(db_path).unlink(missing_ok=True)
+
+    return output.getvalue()
+
+
+def _run_cache_stats() -> str:
+    """Show how to view cache hit/miss statistics.
+
+    Use get_cache_stats() to monitor cache performance and see how
+    effective your caching strategy is.
+    """
+    output = io.StringIO()
+
+    class Product(BaseDBModel):
+        name: str
+        price: float
+
+    db = SqliterDB(memory=True, cache_enabled=True)
+    db.create_table(Product)
+
+    product = db.insert(Product(name="Widget", price=19.99))
+
+    # Perform queries
+    for _ in range(5):
+        db.get(Product, product.pk)
+
+    stats = db.get_cache_stats()
+    output.write("Cache statistics:\n")
+    output.write(f"  - Total queries: {stats['total']}\n")
+    output.write(f"  - Cache hits: {stats['hits']}\n")
+    output.write(f"  - Cache misses: {stats['misses']}\n")
+    output.write(f"  - Hit rate: {stats['hit_rate']}%\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_get_cache_controls() -> str:
+    """Show get() caching, bypass, and TTL overrides."""
+    output = io.StringIO()
+
+    class Product(BaseDBModel):
+        name: str
+        price: float
+
+    db = SqliterDB(memory=True, cache_enabled=True, cache_ttl=60)
+    db.create_table(Product)
+
+    product = db.insert(Product(name="Widget", price=19.99))
+
+    db.get(Product, product.pk)
+    stats = db.get_cache_stats()
+    output.write("After first get (miss):\n")
+    output.write(f"  - Hits: {stats['hits']}\n")
+    output.write(f"  - Misses: {stats['misses']}\n")
+
+    db.get(Product, product.pk)
+    stats = db.get_cache_stats()
+    output.write("After second get (hit):\n")
+    output.write(f"  - Hits: {stats['hits']}\n")
+    output.write(f"  - Misses: {stats['misses']}\n")
+
+    db.get(Product, product.pk, bypass_cache=True)
+    stats = db.get_cache_stats()
+    output.write("After bypass_cache=True (stats unchanged):\n")
+    output.write(f"  - Hits: {stats['hits']}\n")
+    output.write(f"  - Misses: {stats['misses']}\n")
+
+    db.get(Product, product.pk, cache_ttl=5)
+    output.write("Per-call TTL override set to 5s for this lookup\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_cache_bypass() -> str:
+    """Bypass the cache to fetch fresh data from the database.
+
+    Use bypass_cache() when you need to ensure you're getting the most
+    up-to-date data, ignoring any cached results.
+    """
+    output = io.StringIO()
+
+    class Item(BaseDBModel):
+        name: str
+
+    db = SqliterDB(memory=True, cache_enabled=True)
+    db.create_table(Item)
+
+    # Insert item to query
+    db.insert(Item(name="Item 1"))
+
+    # First query - uses cache
+    db.select(Item).filter(name__eq="Item 1").fetch_one()
+    output.write("First query: cached\n")
+
+    # Bypass cache for fresh data - skips cache, hits DB
+    db.select(Item).filter(name__eq="Item 1").bypass_cache().fetch_one()
+    output.write("Second query: bypassed cache for fresh data\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_cache_ttl() -> str:
+    """Set a time-to-live (TTL) for cached entries.
+
+    Cache entries automatically expire after the specified number of seconds,
+    ensuring stale data isn't served indefinitely.
+    """
+    output = io.StringIO()
+
+    class Article(BaseDBModel):
+        title: str
+
+    db = SqliterDB(memory=True, cache_enabled=True, cache_ttl=60)
+    db.create_table(Article)
+
+    article = db.insert(Article(title="News Article"))
+    output.write(f"Created: {article.title}\n")
+    output.write("Cache TTL set to 60 seconds\n")
+    output.write("Cached entries expire after TTL\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_cache_clear() -> str:
+    """Manually clear the cache to free memory or force refresh.
+
+    Use clear_cache() when you need to invalidate all cached results
+    and start fresh.
+    """
+    output = io.StringIO()
+
+    class Document(BaseDBModel):
+        title: str
+
+    db = SqliterDB(memory=True, cache_enabled=True)
+    db.create_table(Document)
+
+    doc = db.insert(Document(title="Doc 1"))
+    db.get(Document, doc.pk)
+    output.write("Query executed and cached\n")
+
+    db.clear_cache()
+    output.write("Cache cleared\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the Caching demo category."""
+    return DemoCategory(
+        id="caching",
+        title="Caching",
+        icon="",
+        demos=[
+            Demo(
+                id="cache_enable",
+                title="Enable Cache",
+                description="Enable query result caching",
+                category="caching",
+                code=extract_demo_code(_run_enable_cache),
+                execute=_run_enable_cache,
+            ),
+            Demo(
+                id="cache_stats",
+                title="Cache Statistics",
+                description="View cache hit/miss statistics",
+                category="caching",
+                code=extract_demo_code(_run_cache_stats),
+                execute=_run_cache_stats,
+            ),
+            Demo(
+                id="cache_get_controls",
+                title="Get Cache Controls",
+                description="Cache, bypass, and TTL for get()",
+                category="caching",
+                code=extract_demo_code(_run_get_cache_controls),
+                execute=_run_get_cache_controls,
+            ),
+            Demo(
+                id="cache_bypass",
+                title="Cache Bypass",
+                description="Bypass cache for fresh data",
+                category="caching",
+                code=extract_demo_code(_run_cache_bypass),
+                execute=_run_cache_bypass,
+            ),
+            Demo(
+                id="cache_ttl",
+                title="Cache TTL",
+                description="Set cache expiration time",
+                category="caching",
+                code=extract_demo_code(_run_cache_ttl),
+                execute=_run_cache_ttl,
+            ),
+            Demo(
+                id="cache_clear",
+                title="Clear Cache",
+                description="Manually clear the cache",
+                category="caching",
+                code=extract_demo_code(_run_cache_clear),
+                execute=_run_cache_clear,
+            ),
+        ],
+    )

sqliter/tui/demos/connection.py

@@ -0,0 +1,150 @@
+"""Connection & Setup 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_memory_db() -> str:
+    """Create an in-memory SQLite database.
+
+    Use memory=True for fast, temporary databases that don't persist.
+    """
+    output = io.StringIO()
+
+    db = SqliterDB(memory=True)
+    output.write(f"Created database: {db}\n")
+    output.write(f"Is memory: {db.is_memory}\n")
+    output.write(f"Filename: {db.filename}\n")
+
+    db.connect()
+    output.write(f"Connected: {db.is_connected}\n")
+
+    db.close()
+    output.write(f"After close: {db.is_connected}\n")
+
+    return output.getvalue()
+
+
+def _run_file_db() -> str:
+    """Create a file-based SQLite database for persistent storage.
+
+    Provide a file path to store data that persists across sessions.
+    """
+    output = io.StringIO()
+
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        db_path = f.name
+
+    try:
+        db = SqliterDB(db_path)
+        output.write("Created file database\n")
+        output.write(f"Filename: {db.filename}\n")
+        output.write(f"Is memory: {db.is_memory}\n")
+
+        db.connect()
+        output.write(f"Connected to: {db_path}\n")
+        db.close()
+    finally:
+        Path(db_path).unlink(missing_ok=True)
+        output.write("Cleaned up database file\n")
+
+    return output.getvalue()
+
+
+def _run_debug_mode() -> str:
+    """Enable debug mode to see SQL queries being executed.
+
+    Set debug=True to log all SQL queries to the console for debugging.
+    """
+    output = io.StringIO()
+
+    output.write("Debug mode enables SQL query logging.\n")
+    output.write("When debug=True, all SQL queries are logged.\n\n")
+
+    class User(BaseDBModel):
+        name: str
+
+    db = SqliterDB(memory=True, debug=True)
+    db.create_table(User)
+
+    output.write("SQL queries would be logged to console:\n")
+    output.write('  CREATE TABLE IF NOT EXISTS "users" (...)\n')
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_context_manager() -> str:
+    """Use context manager for automatic connection management.
+
+    The `with db:` block handles connection, transactions, and cleanup.
+    """
+    output = io.StringIO()
+
+    class Task(BaseDBModel):
+        title: str
+        done: bool = False
+
+    output.write("Using context manager for transactions:\n\n")
+
+    db = SqliterDB(memory=True)
+
+    with db:
+        db.create_table(Task)
+        task = db.insert(Task(title="Learn SQLiter", done=False))
+        output.write(f"Inserted: {task.title} (pk={task.pk})\n")
+        output.write("Transaction auto-commits on exit\n")
+
+    output.write(f"\nAfter context: connected={db.is_connected}\n")
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the Connection & Setup demo category."""
+    return DemoCategory(
+        id="connection",
+        title="Connection & Setup",
+        icon="",
+        demos=[
+            Demo(
+                id="conn_memory",
+                title="In-memory Database",
+                description="Create a temporary in-memory database",
+                category="connection",
+                code=extract_demo_code(_run_memory_db),
+                execute=_run_memory_db,
+            ),
+            Demo(
+                id="conn_file",
+                title="File-based Database",
+                description="Create a persistent file database",
+                category="connection",
+                code=extract_demo_code(_run_file_db),
+                execute=_run_file_db,
+            ),
+            Demo(
+                id="conn_debug",
+                title="Debug Mode",
+                description="Enable SQL query logging",
+                category="connection",
+                code=extract_demo_code(_run_debug_mode),
+                execute=_run_debug_mode,
+            ),
+            Demo(
+                id="conn_context",
+                title="Context Manager",
+                description="Auto commit/rollback with 'with' statement",
+                category="connection",
+                code=extract_demo_code(_run_context_manager),
+                execute=_run_context_manager,
+            ),
+        ],
+        expanded=True,  # First category starts expanded
+    )