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

sqliter/tui/demos/models.py

@@ -0,0 +1,248 @@
+"""Models & Tables demos."""
+
+from __future__ import annotations
+
+import io
+from datetime import datetime, timezone
+from typing import Optional, Union
+
+from sqliter import SqliterDB
+from sqliter.model import BaseDBModel
+from sqliter.tui.demos.base import Demo, DemoCategory, extract_demo_code
+
+
+def _run_basic_model() -> str:
+    """Define a simple model with automatic primary key generation.
+
+    BaseDBModel provides an auto-incrementing 'pk' field and handles
+    all the database table creation.
+    """
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        name: str
+        age: int
+        email: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(User)
+
+    user = db.insert(User(name="Alice", age=30, email="alice@example.com"))
+    output.write(f"Created user: {user.name}\n")
+    output.write(f"Primary key: {user.pk}\n")
+    output.write(f"Age: {user.age}\n")
+    output.write(f"Email: {user.email}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_custom_table_name() -> str:
+    """Override the auto-generated table name.
+
+    Set __tablename__ to use a custom table name instead of the
+    auto-pluralized model class name.
+    """
+    output = io.StringIO()
+
+    class Person(BaseDBModel):
+        """Person model with custom table name."""
+
+        __tablename__ = "people"
+        name: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(Person)
+
+    output.write(f"Table created: {Person.__tablename__}\n")
+    output.write("The model uses 'people' instead of 'persons'\n")
+
+    person = db.insert(Person(name="Bob"))
+    output.write(f"Inserted: {person.name} (pk={person.pk})\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_field_types() -> str:
+    """Use various field types in your models.
+
+    BaseDBModel supports str, int, float, bool, and more with automatic
+    type conversion and validation.
+    """
+    output = io.StringIO()
+
+    class Product(BaseDBModel):
+        name: str
+        price: float
+        in_stock: bool
+        quantity: int
+        created_at: int
+
+    db = SqliterDB(memory=True)
+    db.create_table(Product)
+
+    product = db.insert(
+        Product(
+            name="Widget",
+            price=19.99,
+            in_stock=True,
+            quantity=100,
+            created_at=int(datetime.now(timezone.utc).timestamp()),
+        ),
+    )
+    output.write(f"Product: {product.name}\n")
+    output.write(f"Price: ${product.price}\n")
+    output.write(f"In stock: {product.in_stock}\n")
+    output.write(f"Quantity: {product.quantity}\n")
+    output.write(f"Created: {product.created_at}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_optional_fields() -> str:
+    """Define fields that can be NULL (optional) in the database.
+
+    Use Optional[T] or Union[T, None] for nullable fields, with
+    optional default values.
+    """
+    output = io.StringIO()
+
+    class Article(BaseDBModel):
+        title: str
+        content: Optional[str]
+        author: Optional[str] = "Anonymous"
+
+    db = SqliterDB(memory=True)
+    db.create_table(Article)
+
+    article1 = db.insert(Article(title="First Post", content=None))
+    output.write(f"Article 1: {article1.title}\n")
+    output.write(f"Content: {article1.content}\n")
+    output.write(f"Author: {article1.author}\n")
+
+    article2 = db.insert(
+        Article(title="Second Post", content="Hello world!", author="Bob"),
+    )
+    output.write(f"\nArticle 2: {article2.title}\n")
+    output.write(f"Content: {article2.content}\n")
+    output.write(f"Author: {article2.author}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_default_values() -> str:
+    """Set default values for fields.
+
+    Assign default values in the model definition to use when
+    inserting records without specifying those fields.
+    """
+    output = io.StringIO()
+
+    class Task(BaseDBModel):
+        title: str
+        completed: bool = False
+        priority: int = 1
+
+    db = SqliterDB(memory=True)
+    db.create_table(Task)
+
+    task = db.insert(Task(title="New task"))
+    output.write(f"Task: {task.title}\n")
+    output.write(f"Completed: {task.completed} (default)\n")
+    output.write(f"Priority: {task.priority} (default)\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_complex_types() -> str:
+    """Store complex data types like lists and dicts.
+
+    BaseDBModel automatically serializes lists, dicts, sets, and tuples
+    to BLOBs for SQLite storage, and deserializes them back.
+    """
+    output = io.StringIO()
+
+    class Document(BaseDBModel):
+        title: str
+        tags: list[str]
+        metadata: dict[str, Union[str, int]]
+
+    db = SqliterDB(memory=True)
+    db.create_table(Document)
+
+    doc = db.insert(
+        Document(
+            title="Guide",
+            tags=["python", "database", "tutorial"],
+            metadata={"views": 1000, "rating": 4},
+        ),
+    )
+    output.write(f"Document: {doc.title}\n")
+    output.write(f"Tags: {doc.tags}\n")
+    output.write(f"Metadata: {doc.metadata}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the Models & Tables demo category."""
+    return DemoCategory(
+        id="models",
+        title="Models & Tables",
+        icon="",
+        demos=[
+            Demo(
+                id="model_basic",
+                title="Basic Model",
+                description="Define a simple model with fields",
+                category="models",
+                code=extract_demo_code(_run_basic_model),
+                execute=_run_basic_model,
+            ),
+            Demo(
+                id="model_custom_table",
+                title="Custom Table Name",
+                description="Specify a custom table name",
+                category="models",
+                code=extract_demo_code(_run_custom_table_name),
+                execute=_run_custom_table_name,
+            ),
+            Demo(
+                id="model_field_types",
+                title="Field Types",
+                description="Various field type examples",
+                category="models",
+                code=extract_demo_code(_run_field_types),
+                execute=_run_field_types,
+            ),
+            Demo(
+                id="model_optional",
+                title="Optional Fields",
+                description="Fields with None values and defaults",
+                category="models",
+                code=extract_demo_code(_run_optional_fields),
+                execute=_run_optional_fields,
+            ),
+            Demo(
+                id="model_defaults",
+                title="Default Values",
+                description="Fields with default values",
+                category="models",
+                code=extract_demo_code(_run_default_values),
+                execute=_run_default_values,
+            ),
+            Demo(
+                id="model_complex",
+                title="Complex Types",
+                description="Lists and dicts (stored as BLOBs)",
+                category="models",
+                code=extract_demo_code(_run_complex_types),
+                execute=_run_complex_types,
+            ),
+        ],
+    )

sqliter/tui/demos/ordering.py

@@ -0,0 +1,156 @@
+"""Ordering & Pagination 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_order_asc() -> str:
+    """Sort query results in ascending order.
+
+    Use order(field_name) to sort results from lowest to highest.
+    """
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        name: str
+        age: int
+
+    db = SqliterDB(memory=True)
+    db.create_table(User)
+
+    db.insert(User(name="Charlie", age=35))
+    db.insert(User(name="Alice", age=25))
+    db.insert(User(name="Bob", age=30))
+
+    results = db.select(User).order("age").fetch_all()
+    output.write("Users ordered by age (ascending):\n")
+    for user in results:
+        output.write(f"  - {user.name}: {user.age}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_order_desc() -> str:
+    """Sort query results in descending order.
+
+    Use order(field_name, reverse=True) to sort from highest to lowest.
+    """
+    output = io.StringIO()
+
+    class Product(BaseDBModel):
+        name: str
+        price: float
+
+    db = SqliterDB(memory=True)
+    db.create_table(Product)
+
+    db.insert(Product(name="Item A", price=10.0))
+    db.insert(Product(name="Item B", price=30.0))
+    db.insert(Product(name="Item C", price=20.0))
+
+    results = db.select(Product).order("price", reverse=True).fetch_all()
+    output.write("Products ordered by price (descending):\n")
+    for product in results:
+        output.write(f"  - {product.name}: ${product.price}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_limit() -> str:
+    """Limit the number of results returned.
+
+    Use limit(count) to fetch only the first N records.
+    """
+    output = io.StringIO()
+
+    class Article(BaseDBModel):
+        title: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(Article)
+
+    for i in range(1, 11):
+        db.insert(Article(title=f"Article {i}"))
+
+    results = db.select(Article).limit(3).fetch_all()
+    output.write("Top 3 articles:\n")
+    for article in results:
+        output.write(f"  - {article.title}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_offset() -> str:
+    """Skip a specified number of results.
+
+    Use offset(count) with limit() for pagination, skipping first N records.
+    """
+    output = io.StringIO()
+
+    class Item(BaseDBModel):
+        name: str
+
+    db = SqliterDB(memory=True)
+    db.create_table(Item)
+
+    for i in range(1, 11):
+        db.insert(Item(name=f"Item {i}"))
+
+    results = db.select(Item).limit(5).offset(5).fetch_all()
+    output.write("Items 6-10:\n")
+    for item in results:
+        output.write(f"  - {item.name}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def get_category() -> DemoCategory:
+    """Get the Ordering & Pagination demo category."""
+    return DemoCategory(
+        id="ordering",
+        title="Ordering & Pagination",
+        icon="",
+        demos=[
+            Demo(
+                id="order_asc",
+                title="Order Ascending",
+                description="Sort results in ascending order",
+                category="ordering",
+                code=extract_demo_code(_run_order_asc),
+                execute=_run_order_asc,
+            ),
+            Demo(
+                id="order_desc",
+                title="Order Descending",
+                description="Sort results in descending order",
+                category="ordering",
+                code=extract_demo_code(_run_order_desc),
+                execute=_run_order_desc,
+            ),
+            Demo(
+                id="paginate_limit",
+                title="Limit Results",
+                description="Limit number of results",
+                category="ordering",
+                code=extract_demo_code(_run_limit),
+                execute=_run_limit,
+            ),
+            Demo(
+                id="paginate_offset",
+                title="Offset Results",
+                description="Skip records for pagination",
+                category="ordering",
+                code=extract_demo_code(_run_offset),
+                execute=_run_offset,
+            ),
+        ],
+    )