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

sqliter/tui/demos/crud.py

@@ -0,0 +1,154 @@
+"""CRUD Operations 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_insert() -> str:
+    """Insert new records into the database.
+
+    Use db.insert() to add new records, which returns the inserted
+    object with auto-generated primary key.
+    """
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        name: str
+        email: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(User)
+
+    user1 = db.insert(User(name="Alice", email="alice@example.com"))
+    output.write(f"Inserted: {user1.name} (pk={user1.pk})\n")
+
+    user2 = db.insert(User(name="Bob", email="bob@example.com"))
+    output.write(f"Inserted: {user2.name} (pk={user2.pk})\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_get_by_pk() -> str:
+    """Retrieve a single record by primary key.
+
+    Use db.get(Model, pk) to fetch a specific record quickly.
+    """
+    output = io.StringIO()
+
+    class Task(BaseDBModel):
+        title: str
+        done: bool = False
+
+    db = SqliterDB(memory=True)
+    db.create_table(Task)
+
+    task: Task = db.insert(Task(title="Buy groceries"))
+    output.write(f"Created: {task.title} (pk={task.pk})\n")
+
+    retrieved = db.get(Task, task.pk)
+    if retrieved is not None:
+        output.write(f"Retrieved: {retrieved.title}\n")
+        output.write(f"Same object: {retrieved.pk == task.pk}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_update() -> str:
+    """Update existing records in the database.
+
+    Modify field values and call db.update() to persist changes.
+    """
+    output = io.StringIO()
+
+    class Item(BaseDBModel):
+        name: str
+        quantity: int
+
+    db = SqliterDB(memory=True)
+    db.create_table(Item)
+
+    item = db.insert(Item(name="Apples", quantity=5))
+    output.write(f"Created: {item.name} x{item.quantity}\n")
+
+    item.quantity = 10
+    db.update(item)
+    output.write(f"Updated: {item.name} x{item.quantity}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_delete() -> str:
+    """Delete records from the database.
+
+    Use db.delete(Model, pk) to permanently remove a record.
+    """
+    output = io.StringIO()
+
+    class Note(BaseDBModel):
+        content: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(Note)
+
+    note = db.insert(Note(content="Temporary note"))
+    output.write(f"Created note (pk={note.pk})\n")
+
+    db.delete(Note, note.pk)
+    output.write(f"Deleted note with pk={note.pk}\n")
+
+    all_notes = db.select(Note).fetch_all()
+    output.write(f"Remaining notes: {len(all_notes)}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the CRUD Operations demo category."""
+    return DemoCategory(
+        id="crud",
+        title="CRUD Operations",
+        icon="",
+        demos=[
+            Demo(
+                id="crud_insert",
+                title="Insert Records",
+                description="Create new records in the database",
+                category="crud",
+                code=extract_demo_code(_run_insert),
+                execute=_run_insert,
+            ),
+            Demo(
+                id="crud_get",
+                title="Get by Primary Key",
+                description="Retrieve a record by its primary key",
+                category="crud",
+                code=extract_demo_code(_run_get_by_pk),
+                execute=_run_get_by_pk,
+            ),
+            Demo(
+                id="crud_update",
+                title="Update Records",
+                description="Modify existing records",
+                category="crud",
+                code=extract_demo_code(_run_update),
+                execute=_run_update,
+            ),
+            Demo(
+                id="crud_delete",
+                title="Delete Records",
+                description="Remove records from the database",
+                category="crud",
+                code=extract_demo_code(_run_delete),
+                execute=_run_delete,
+            ),
+        ],
+    )

sqliter/tui/demos/errors.py

@@ -0,0 +1,231 @@
+"""Error Handling demos."""
+
+from __future__ import annotations
+
+import io
+from typing import Annotated
+
+from pydantic import ValidationError
+
+from sqliter import SqliterDB
+from sqliter.exceptions import (
+    ForeignKeyConstraintError,
+    RecordInsertionError,
+    RecordNotFoundError,
+    SqliterError,
+)
+from sqliter.model import BaseDBModel
+from sqliter.model.unique import unique
+from sqliter.orm import BaseDBModel as ORMBaseDBModel
+from sqliter.orm import ForeignKey
+from sqliter.tui.demos.base import Demo, DemoCategory, extract_demo_code
+
+
+def _run_record_not_found() -> str:
+    """Handle attempts to access non-existent records.
+
+    RecordNotFoundError is raised when trying to get/update/delete
+    a record that doesn't exist.
+    """
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        name: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(User)
+
+    user = db.insert(User(name="Alice"))
+    output.write(f"Created user with pk={user.pk}\n")
+
+    try:
+        # Try to delete non-existent record (raises RecordNotFoundError)
+        db.delete(User, 9999)
+    except RecordNotFoundError as e:
+        output.write(f"\nCaught error: {type(e).__name__}\n")
+        output.write(f"Message: {e}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_unique_constraint() -> str:
+    """Handle violations of unique field constraints.
+
+    RecordInsertionError is raised when inserting a duplicate value
+    into a field marked as unique().
+    """
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        email: Annotated[str, unique()]
+        name: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(User)
+
+    db.insert(User(email="alice@example.com", name="Alice"))
+    output.write("Created user with email alice@example.com\n")
+
+    try:
+        # Try to insert duplicate email
+        db.insert(User(email="alice@example.com", name="Alice 2"))
+    except RecordInsertionError as e:
+        output.write(f"\nCaught error: {type(e).__name__}\n")
+        output.write(f"Message: {e}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_validation_error() -> str:
+    """Handle Pydantic validation errors.
+
+    ValidationError occurs when data doesn't match the field type
+    or constraints defined in the model.
+    """
+    output = io.StringIO()
+
+    class Product(BaseDBModel):
+        name: str
+        price: float
+        quantity: int
+
+    db = SqliterDB(memory=True)
+    db.create_table(Product)
+
+    product = db.insert(Product(name="Widget", price=19.99, quantity=100))
+    output.write(f"Created product: {product.name}, price: ${product.price}\n")
+
+    # Try to create product with invalid data (wrong types)
+    output.write("\nAttempting to create product with invalid data...\n")
+
+    try:
+        # Wrong types: price should be float, quantity should be int
+        # ValidationError is raised by Pydantic during model instantiation
+        Product(name="Invalid Widget", price="free", quantity="lots")
+    except ValidationError as e:
+        output.write(f"\nCaught error: {type(e).__name__}\n")
+        output.write(f"Message: {e}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_foreign_key_constraint() -> str:
+    """Handle foreign key constraint violations.
+
+    ForeignKeyConstraintError occurs when referencing a non-existent
+    related record or violating referential integrity.
+    """
+    output = io.StringIO()
+
+    class Author(ORMBaseDBModel):
+        name: str
+
+    class Book(ORMBaseDBModel):
+        title: str
+        author: ForeignKey[Author] = ForeignKey(Author, on_delete="RESTRICT")
+
+    db = SqliterDB(memory=True)
+    db.create_table(Author)
+    db.create_table(Book)
+
+    author = db.insert(Author(name="Jane"))
+    db.insert(Book(title="Book 1", author=author))
+    output.write("Created author and linked book\n")
+
+    # Attempt to insert book with non-existent author
+    output.write("\nAttempting to insert book with non-existent author...\n")
+
+    try:
+        # Create book with invalid author_id (doesn't exist in database)
+        invalid_book = Book(title="Orphan Book", author_id=9999)
+        db.insert(invalid_book)
+    except ForeignKeyConstraintError as e:
+        output.write(f"\nCaught error: {type(e).__name__}\n")
+        output.write(f"Message: {e}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_generic_error_handling() -> str:
+    """Catch all SQLiter errors with the base SqliterError class.
+
+    Use SqliterError for generic error handling when you don't need
+    to distinguish between specific error types.
+    """
+    output = io.StringIO()
+
+    class Task(BaseDBModel):
+        title: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(Task)
+
+    task = db.insert(Task(title="My Task"))
+    output.write(f"Created task: {task.title}\n")
+
+    # Try to update a deleted record
+    try:
+        task.title = "Updated"
+        db.delete(Task, task.pk)
+        db.update(task)  # This will fail
+    except SqliterError as e:
+        output.write(f"\nCaught SqliterError: {type(e).__name__}\n")
+        output.write(f"Message: {e}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the Error Handling demo category."""
+    return DemoCategory(
+        id="errors",
+        title="Error Handling",
+        icon="",
+        demos=[
+            Demo(
+                id="error_not_found",
+                title="Record Not Found",
+                description="Handle missing records gracefully",
+                category="errors",
+                code=extract_demo_code(_run_record_not_found),
+                execute=_run_record_not_found,
+            ),
+            Demo(
+                id="error_unique",
+                title="Unique Constraint",
+                description="Handle duplicate value errors",
+                category="errors",
+                code=extract_demo_code(_run_unique_constraint),
+                execute=_run_unique_constraint,
+            ),
+            Demo(
+                id="error_validation",
+                title="Validation Error",
+                description="Handle Pydantic validation errors",
+                category="errors",
+                code=extract_demo_code(_run_validation_error),
+                execute=_run_validation_error,
+            ),
+            Demo(
+                id="error_fk",
+                title="Foreign Key Constraint",
+                description="Handle invalid foreign key references",
+                category="errors",
+                code=extract_demo_code(_run_foreign_key_constraint),
+                execute=_run_foreign_key_constraint,
+            ),
+            Demo(
+                id="error_generic",
+                title="Generic Error Handling",
+                description="Catch-all for SQLiter errors",
+                category="errors",
+                code=extract_demo_code(_run_generic_error_handling),
+                execute=_run_generic_error_handling,
+            ),
+        ],
+    )

sqliter/tui/demos/field_selection.py

@@ -0,0 +1,150 @@
+"""Field Selection 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_select_fields() -> str:
+    """Select specific fields from a query to reduce data transfer.
+
+    Use fields() to fetch only the columns you need, leaving unspecified
+    fields as None.
+    """
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        name: str
+        email: str
+        age: int
+        city: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(User)
+
+    db.insert(User(name="Alice", email="alice@example.com", age=30, city="NYC"))
+    db.insert(User(name="Bob", email="bob@example.com", age=25, city="LA"))
+
+    # Select only name and email
+    users = db.select(User).fields(["name", "email"]).fetch_all()
+    output.write("Selected only name and email fields:\n")
+    for user in users:
+        output.write(f"  - {user.name}, {user.email}\n")
+
+    # Note: age and city are None since they weren't selected
+    output.write("(age and city not selected, set to None)\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_exclude_fields() -> str:
+    """Exclude specific fields from query results.
+
+    Use exclude() to fetch all fields except the ones you specify,
+    useful for hiding large or sensitive fields.
+    """
+    output = io.StringIO()
+
+    class Product(BaseDBModel):
+        name: str
+        price: float
+        description: str
+        stock: int
+
+    db = SqliterDB(memory=True)
+    db.create_table(Product)
+
+    db.insert(
+        Product(
+            name="Laptop",
+            price=999.99,
+            description="Fast laptop",
+            stock=10,
+        )
+    )
+
+    # Exclude description and stock
+    product = db.select(Product).exclude(["description", "stock"]).fetch_one()
+    if product is not None:
+        output.write(f"Product: {product.name}\n")
+        output.write(f"Price: ${product.price}\n")
+        output.write("(description and stock excluded)\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_only_field() -> str:
+    """Select a single field from query results.
+
+    Use only() when you only need one specific field from your query,
+    useful for getting IDs or names.
+    """
+    output = io.StringIO()
+
+    class Task(BaseDBModel):
+        title: str
+        status: str
+        priority: int
+        assigned_to: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(Task)
+
+    db.insert(
+        Task(title="Fix bug", status="todo", priority=1, assigned_to="Alice")
+    )
+    db.insert(
+        Task(title="Add feature", status="done", priority=2, assigned_to="Bob")
+    )
+
+    # Select only the title field
+    tasks = db.select(Task).only("title").fetch_all()
+    output.write("Selected only title field:\n")
+    for task in tasks:
+        output.write(f"  - {task.title}\n")
+
+    output.write("(status, priority, assigned_to not selected)\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the Field Selection demo category."""
+    return DemoCategory(
+        id="field_selection",
+        title="Field Selection",
+        icon="",
+        demos=[
+            Demo(
+                id="field_select",
+                title="Select Fields",
+                description="Choose specific fields to fetch",
+                category="field_selection",
+                code=extract_demo_code(_run_select_fields),
+                execute=_run_select_fields,
+            ),
+            Demo(
+                id="field_exclude",
+                title="Exclude Fields",
+                description="Exclude specific fields from results",
+                category="field_selection",
+                code=extract_demo_code(_run_exclude_fields),
+                execute=_run_exclude_fields,
+            ),
+            Demo(
+                id="field_only",
+                title="Select Single Field",
+                description="Fetch only one specific field",
+                category="field_selection",
+                code=extract_demo_code(_run_only_field),
+                execute=_run_only_field,
+            ),
+        ],
+    )