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

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

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