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

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
+    )

sqliter/tui/demos/constraints.py

@@ -0,0 +1,211 @@
+"""Unique & Foreign Key constraint demos."""
+
+from __future__ import annotations
+
+import io
+from typing import Annotated, Optional
+
+from sqliter import SqliterDB
+from sqliter.model import BaseDBModel
+from sqliter.model.unique import unique
+from sqliter.orm.foreign_key import ForeignKey
+from sqliter.tui.demos.base import Demo, DemoCategory, extract_demo_code
+
+
+def _run_unique_field() -> str:
+    """Enforce uniqueness on a field to prevent duplicate values.
+
+    Use unique() to ensure no two records have the same value for
+    a specific field (like email).
+    """
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        email: Annotated[str, unique()]
+        name: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(User)
+
+    user1 = db.insert(User(email="alice@example.com", name="Alice"))
+    output.write(f"Created: {user1.name} ({user1.email})\n")
+
+    user2 = db.insert(User(email="bob@example.com", name="Bob"))
+    output.write(f"Created: {user2.name} ({user2.email})\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_multi_field_unique() -> str:
+    """Enforce uniqueness on multiple fields.
+
+    Each unique() field is constrained independently (not a composite
+    unique constraint).
+    """
+    output = io.StringIO()
+
+    class Enrollment(BaseDBModel):
+        student_id: Annotated[int, unique()]
+        course_id: Annotated[int, unique()]
+
+    db = SqliterDB(memory=True)
+    db.create_table(Enrollment)
+
+    output.write("Table created with unique fields (each column independent)\n")
+    enrollment = db.insert(Enrollment(student_id=1, course_id=101))
+    output.write(
+        f"Enrolled student {enrollment.student_id} in course "
+        f"{enrollment.course_id}\n"
+    )
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_foreign_key_cascade() -> str:
+    """Automatically delete related records when parent is deleted.
+
+    CASCADE on_delete means deleting a record also deletes all
+    records that reference it via foreign key.
+    """
+    output = io.StringIO()
+
+    class Author(BaseDBModel):
+        name: str
+
+    class Book(BaseDBModel):
+        title: str
+        author_id: ForeignKey[Author] = ForeignKey(
+            Author,
+            on_delete="CASCADE",
+            on_update="CASCADE",
+            null=True,
+        )
+
+    db = SqliterDB(memory=True)
+    db.create_table(Author)
+    db.create_table(Book)
+
+    author = db.insert(Author(name="Jane Austen"))
+    book = db.insert(Book(title="Pride and Prejudice", author_id=author.pk))
+    output.write(f"Book '{book.title}' linked to author {author.pk}\n")
+    output.write("Foreign key: CASCADE on delete/update\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_foreign_key_restrict() -> str:
+    """Prevent deletion of records that are referenced by others.
+
+    RESTRICT on_delete prevents deleting a record if other records
+    reference it via foreign key.
+    """
+    output = io.StringIO()
+
+    class Category(BaseDBModel):
+        name: str
+
+    class Product(BaseDBModel):
+        name: str
+        category_id: ForeignKey[Category] = ForeignKey(
+            Category, on_delete="RESTRICT"
+        )
+
+    db = SqliterDB(memory=True)
+    db.create_table(Category)
+    db.create_table(Product)
+
+    category = db.insert(Category(name="Electronics"))
+    product = db.insert(Product(name="Laptop", category_id=category.pk))
+    output.write(f"Product '{product.name}' in category '{category.name}'\n")
+    output.write(
+        "Foreign key: RESTRICT prevents deletion of referenced records\n"
+    )
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_foreign_key_set_null() -> str:
+    """Set foreign key to NULL when referenced record is deleted.
+
+    SET NULL on_delete sets the foreign key field to None when the
+    referenced record is deleted (requires nullable FK).
+    """
+    output = io.StringIO()
+
+    class Department(BaseDBModel):
+        name: str
+
+    class Employee(BaseDBModel):
+        name: str
+        department_id: Optional[ForeignKey[Department]] = ForeignKey(
+            Department,
+            on_delete="SET NULL",
+            null=True,
+        )
+
+    db = SqliterDB(memory=True)
+    db.create_table(Department)
+    db.create_table(Employee)
+
+    dept = db.insert(Department(name="Engineering"))
+    emp = db.insert(Employee(name="Alice", department_id=dept.pk))
+    output.write(f"Employee '{emp.name}' in department {emp.department_id}\n")
+    output.write("Foreign key: SET NULL on delete of referenced record\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the Constraints demo category."""
+    return DemoCategory(
+        id="constraints",
+        title="Constraints",
+        icon="",
+        demos=[
+            Demo(
+                id="constraint_unique_field",
+                title="Unique Field",
+                description="Enforce uniqueness on a field",
+                category="constraints",
+                code=extract_demo_code(_run_unique_field),
+                execute=_run_unique_field,
+            ),
+            Demo(
+                id="constraint_multi_unique",
+                title="Multiple Unique Fields",
+                description="Multiple unique fields in one table",
+                category="constraints",
+                code=extract_demo_code(_run_multi_field_unique),
+                execute=_run_multi_field_unique,
+            ),
+            Demo(
+                id="constraint_fk_cascade",
+                title="Foreign Key CASCADE",
+                description="Cascade deletes to related records",
+                category="constraints",
+                code=extract_demo_code(_run_foreign_key_cascade),
+                execute=_run_foreign_key_cascade,
+            ),
+            Demo(
+                id="constraint_fk_restrict",
+                title="Foreign Key RESTRICT",
+                description="Prevent deletion of referenced records",
+                category="constraints",
+                code=extract_demo_code(_run_foreign_key_restrict),
+                execute=_run_foreign_key_restrict,
+            ),
+            Demo(
+                id="constraint_fk_set_null",
+                title="Foreign Key SET NULL",
+                description="Set field to NULL on reference deletion",
+                category="constraints",
+                code=extract_demo_code(_run_foreign_key_set_null),
+                execute=_run_foreign_key_set_null,
+            ),
+        ],
+    )