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

sqliter/sqliter.py

@@ -13,7 +13,7 @@ import sqlite3
 import sys
 import time
 from collections import OrderedDict
-from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union, cast
 
 from typing_extensions import Self
 
@@ -32,6 +32,7 @@ from sqliter.exceptions import (
 )
 from sqliter.helpers import infer_sqlite_type
 from sqliter.model.foreign_key import ForeignKeyInfo, get_foreign_key_info
+from sqliter.model.model import BaseDBModel
 from sqliter.query.query import QueryBuilder
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -39,9 +40,7 @@ if TYPE_CHECKING:  # pragma: no cover
 
     from pydantic.fields import FieldInfo
 
-    from sqliter.model.model import BaseDBModel
-
-T = TypeVar("T", bound="BaseDBModel")
+T = TypeVar("T", bound=BaseDBModel)
 
 
 class SqliterDB:
@@ -474,6 +473,25 @@ class SqliterDB:
             "hit_rate": round(hit_rate, 2),
         }
 
+    def clear_cache(self) -> None:
+        """Clear all cached query results.
+
+        This method removes all cached data from memory, freeing up resources
+        and forcing subsequent queries to fetch fresh data from the database.
+
+        Use this when you want to:
+        - Free memory used by the cache
+        - Force fresh queries after external data changes
+
+        Note:
+            Cache statistics (hits/misses) are preserved. To reset statistics,
+            create a new database connection.
+
+        Example:
+            >>> db.clear_cache()
+        """
+        self._cache.clear()
+
     def close(self) -> None:
         """Close the database connection.
 
@@ -782,6 +800,44 @@ class SqliterDB:
             if model_instance.updated_at == 0:
                 model_instance.updated_at = current_timestamp
 
+    def _create_instance_from_data(
+        self,
+        model_class: type[T],
+        data: dict[str, Any],
+        pk: Optional[int] = None,
+    ) -> T:
+        """Create a model instance from deserialized data.
+
+        Handles ORM-specific field exclusions and db_context setup.
+
+        Args:
+            model_class: The model class to instantiate.
+            data: Raw data dictionary from the database.
+            pk: Optional primary key value to set.
+
+        Returns:
+            A new model instance with db_context set if applicable.
+        """
+        # Deserialize each field before creating the model instance
+        deserialized_data: dict[str, Any] = {}
+        for field_name, value in data.items():
+            deserialized_data[field_name] = model_class.deserialize_field(
+                field_name, value, return_local_time=self.return_local_time
+            )
+        # For ORM mode, exclude FK descriptor fields from data
+        for fk_field in getattr(model_class, "fk_descriptors", {}):
+            deserialized_data.pop(fk_field, None)
+
+        if pk is not None:
+            instance = model_class(pk=pk, **deserialized_data)
+        else:
+            instance = model_class(**deserialized_data)
+
+        # Set db_context for ORM lazy loading and reverse relationships
+        if hasattr(instance, "db_context"):
+            instance.db_context = self
+        return instance
+
     def insert(
         self, model_instance: T, *, timestamp_override: bool = False
     ) -> T:
@@ -832,12 +888,15 @@ class SqliterDB:
         """  # noqa: S608
 
         try:
-            with self.connect() as conn:
-                cursor = conn.cursor()
-                cursor.execute(insert_sql, values)
-                self._maybe_commit()
+            conn = self.connect()
+            cursor = conn.cursor()
+            cursor.execute(insert_sql, values)
+            self._maybe_commit()
 
         except sqlite3.IntegrityError as exc:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
             # Check for foreign key constraint violation
             if "FOREIGN KEY constraint failed" in str(exc):
                 fk_operation = "insert"
@@ -847,26 +906,32 @@ class SqliterDB:
                 ) from exc
             raise RecordInsertionError(table_name) from exc
         except sqlite3.Error as exc:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
             raise RecordInsertionError(table_name) from exc
         else:
             self._cache_invalidate_table(table_name)
             data.pop("pk", None)
-            # Deserialize each field before creating the model instance
-            deserialized_data = {}
-            for field_name, value in data.items():
-                deserialized_data[field_name] = model_class.deserialize_field(
-                    field_name, value, return_local_time=self.return_local_time
-                )
-            return model_class(pk=cursor.lastrowid, **deserialized_data)
+            return self._create_instance_from_data(
+                model_class, data, pk=cursor.lastrowid
+            )
 
     def get(
-        self, model_class: type[BaseDBModel], primary_key_value: int
-    ) -> BaseDBModel | None:
+        self,
+        model_class: type[T],
+        primary_key_value: int,
+        *,
+        bypass_cache: bool = False,
+        cache_ttl: Optional[int] = None,
+    ) -> T | None:
         """Retrieve a single record from the database by its primary key.
 
         Args:
             model_class: The Pydantic model class representing the table.
             primary_key_value: The value of the primary key to look up.
+            bypass_cache: If True, skip reading/writing cache for this call.
+            cache_ttl: Optional TTL override for this specific lookup.
 
         Returns:
             An instance of the model class if found, None otherwise.
@@ -874,8 +939,18 @@ class SqliterDB:
         Raises:
             RecordFetchError: If there's an error fetching the record.
         """
+        if cache_ttl is not None and cache_ttl < 0:
+            msg = "cache_ttl must be non-negative"
+            raise ValueError(msg)
+
         table_name = model_class.get_table_name()
         primary_key = model_class.get_primary_key()
+        cache_key = f"pk:{primary_key_value}"
+
+        if not bypass_cache:
+            hit, cached = self._cache_get(table_name, cache_key)
+            if hit:
+                return cast("Optional[T]", cached)
 
         fields = ", ".join(model_class.model_fields)
 
@@ -884,30 +959,29 @@ class SqliterDB:
         """  # noqa: S608
 
         try:
-            with self.connect() as conn:
-                cursor = conn.cursor()
-                cursor.execute(select_sql, (primary_key_value,))
-                result = cursor.fetchone()
+            conn = self.connect()
+            cursor = conn.cursor()
+            cursor.execute(select_sql, (primary_key_value,))
+            result = cursor.fetchone()
 
             if result:
                 result_dict = {
                     field: result[idx]
                     for idx, field in enumerate(model_class.model_fields)
                 }
-                # Deserialize each field before creating the model instance
-                deserialized_data = {}
-                for field_name, value in result_dict.items():
-                    deserialized_data[field_name] = (
-                        model_class.deserialize_field(
-                            field_name,
-                            value,
-                            return_local_time=self.return_local_time,
-                        )
+                instance = self._create_instance_from_data(
+                    model_class, result_dict
+                )
+                if not bypass_cache:
+                    self._cache_set(
+                        table_name, cache_key, instance, ttl=cache_ttl
                     )
-                return model_class(**deserialized_data)
+                return instance
         except sqlite3.Error as exc:
             raise RecordFetchError(table_name) from exc
         else:
+            if not bypass_cache:
+                self._cache_set(table_name, cache_key, None, ttl=cache_ttl)
             return None
 
     def update(self, model_instance: BaseDBModel) -> None:
@@ -930,6 +1004,7 @@ class SqliterDB:
 
         # Get the data and serialize any datetime/date fields
         data = model_instance.model_dump()
+
         for field_name, value in list(data.items()):
             data[field_name] = model_instance.serialize_field(value)
 
@@ -947,22 +1022,30 @@ class SqliterDB:
         """  # noqa: S608
 
         try:
-            with self.connect() as conn:
-                cursor = conn.cursor()
-                cursor.execute(update_sql, (*values, primary_key_value))
+            conn = self.connect()
+            cursor = conn.cursor()
+            cursor.execute(update_sql, (*values, primary_key_value))
 
-                # Check if any rows were updated
-                if cursor.rowcount == 0:
-                    raise RecordNotFoundError(primary_key_value)
+            # Check if any rows were updated
+            if cursor.rowcount == 0:
+                raise RecordNotFoundError(primary_key_value)  # noqa: TRY301
 
-                self._maybe_commit()
-                self._cache_invalidate_table(table_name)
+            self._maybe_commit()
+            self._cache_invalidate_table(table_name)
 
+        except RecordNotFoundError:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
+            raise
         except sqlite3.Error as exc:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
             raise RecordUpdateError(table_name) from exc
 
     def delete(
-        self, model_class: type[BaseDBModel], primary_key_value: str
+        self, model_class: type[BaseDBModel], primary_key_value: Union[int, str]
     ) -> None:
         """Delete a record from the database by its primary key.
 
@@ -983,15 +1066,23 @@ class SqliterDB:
         """  # noqa: S608
 
         try:
-            with self.connect() as conn:
-                cursor = conn.cursor()
-                cursor.execute(delete_sql, (primary_key_value,))
+            conn = self.connect()
+            cursor = conn.cursor()
+            cursor.execute(delete_sql, (primary_key_value,))
 
-                if cursor.rowcount == 0:
-                    raise RecordNotFoundError(primary_key_value)
-                self._maybe_commit()
-                self._cache_invalidate_table(table_name)
+            if cursor.rowcount == 0:
+                raise RecordNotFoundError(primary_key_value)  # noqa: TRY301
+            self._maybe_commit()
+            self._cache_invalidate_table(table_name)
+        except RecordNotFoundError:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
+            raise
         except sqlite3.IntegrityError as exc:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
             # Check for foreign key constraint violation (RESTRICT)
             if "FOREIGN KEY constraint failed" in str(exc):
                 fk_operation = "delete"
@@ -1001,6 +1092,9 @@ class SqliterDB:
                 ) from exc
             raise RecordDeletionError(table_name) from exc
         except sqlite3.Error as exc:
+            # Rollback implicit transaction if not in user-managed transaction
+            if not self._in_transaction and self.conn:
+                self.conn.rollback()
             raise RecordDeletionError(table_name) from exc
 
     def select(

sqliter/tui/__init__.py

@@ -0,0 +1,62 @@
+"""TUI demo application for SQLiter.
+
+This module provides an interactive terminal-based demonstration of SQLiter
+features using the Textual library.
+
+Usage:
+    python -m sqliter.tui
+    # or
+    sqliter-demo
+
+Requires:
+    uv add sqliter-py[demo]
+"""
+
+from __future__ import annotations
+
+from importlib.util import find_spec
+from typing import TYPE_CHECKING
+
+_TEXTUAL_AVAILABLE = find_spec("textual") is not None
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sqliter.tui.app import SQLiterDemoApp
+
+
+def _missing_dependency_error() -> None:
+    """Raise informative error when textual is not installed."""
+    msg = (
+        "The SQLiter TUI demo requires the 'textual' library.\n"
+        "Install it with: uv add sqliter-py[demo]\n"
+    )
+    raise ImportError(msg)
+
+
+def get_app() -> SQLiterDemoApp:
+    """Get the TUI application instance.
+
+    Returns:
+        The SQLiterDemoApp instance.
+
+    Raises:
+        ImportError: If textual is not installed.
+    """
+    if not _TEXTUAL_AVAILABLE:
+        _missing_dependency_error()
+
+    from sqliter.tui.app import SQLiterDemoApp  # noqa: PLC0415
+
+    return SQLiterDemoApp()
+
+
+def run() -> None:
+    """Run the TUI demo application.
+
+    Raises:
+        ImportError: If textual is not installed.
+    """
+    app = get_app()
+    app.run()
+
+
+__all__ = ["get_app", "run"]

sqliter/tui/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running SQLiter TUI as a module."""
+
+from sqliter.tui import run
+
+if __name__ == "__main__":  # pragma: no cover
+    run()

sqliter/tui/app.py

@@ -0,0 +1,179 @@
+"""Main SQLiter TUI demo application."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from typing import TYPE_CHECKING, ClassVar, cast
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import (
+    Container,
+    Horizontal,
+    Vertical,
+    VerticalScroll,
+)
+from textual.css.query import NoMatches
+from textual.screen import ModalScreen
+from textual.widgets import Button, Footer, Header, Markdown, Tree
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sqliter.tui.demos.base import Demo
+
+from sqliter.tui.demos import DemoRegistry
+from sqliter.tui.runner import run_demo
+from sqliter.tui.widgets import (
+    CodeDisplay,
+    DemoList,
+    DemoSelected,
+    OutputDisplay,
+)
+
+
+class HelpScreen(ModalScreen[None]):
+    """Modal help screen."""
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("escape", "dismiss", "Close"),
+        Binding("q", "dismiss", "Close"),
+    ]
+
+    def compose(self) -> ComposeResult:
+        """Compose the help screen."""
+        with VerticalScroll(id="help-scroll"):
+            yield Markdown(
+                """
+# SQLiter Demo - Help
+
+## Navigation
+
+| Key | Action |
+|-----|--------|
+| Up/Down or j/k | Navigate demo list |
+| Left/Right or h/l | Collapse/expand category |
+| Enter | Select demo / Run demo |
+| Tab | Move focus between panels |
+
+## Actions
+
+| Key | Action |
+|-----|--------|
+| F5 | Run selected demo |
+| F8 | Clear output |
+| ? or F1 | Show this help |
+| q | Quit application |
+
+## Mouse
+
+- Click categories to expand/collapse
+- Click demos to select and view code
+- Click buttons to run/clear
+
+Press Escape or q to close this help.
+                """,
+                id="help-content",
+            )
+
+
+class SQLiterDemoApp(App[None]):
+    """Main SQLiter TUI demo application."""
+
+    CSS_PATH = "styles/app.tcss"
+    TITLE = "SQLiter Interactive Demo"
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("q", "quit", "Quit", show=True, priority=True),
+        Binding("f5", "run_demo", "Run", show=True),
+        Binding("f8", "clear_output", "Clear", show=True),
+        Binding("question_mark", "show_help", "Help", show=True),
+        Binding("f1", "show_help", show=False),
+        Binding("j", "tree_cursor_down", show=False),
+        Binding("k", "tree_cursor_up", show=False),
+    ]
+
+    def __init__(self) -> None:
+        """Initialize the application."""
+        super().__init__()
+        self._current_demo: Demo | None = None
+
+    def compose(self) -> ComposeResult:
+        """Compose the application layout."""
+        yield Header()
+        with Container(id="main-container"):
+            yield DemoList(id="demo-list")
+            with Vertical(id="right-panel"):
+                yield CodeDisplay(widget_id="code-display")
+                yield OutputDisplay(widget_id="output-display")
+                with Horizontal(id="button-bar"):
+                    yield Button(
+                        "Run Demo (F5)", id="run-btn", variant="primary"
+                    )
+                    yield Button("Clear Output (F8)", id="clear-btn")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Set initial focus on the demo list."""
+        with suppress(NoMatches):
+            demo_list = self.query_one("#demo-list", DemoList)
+            tree = demo_list.query_one("#demo-tree", Tree)
+            tree.focus()
+
+    def on_demo_selected(self, event: DemoSelected) -> None:
+        """Handle demo selection from the list."""
+        self._current_demo = event.demo
+        code_display = self.query_one("#code-display", CodeDisplay)
+        code_display.set_code(DemoRegistry.get_demo_code(event.demo.id))
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle button presses."""
+        if event.button.id == "run-btn":
+            self.action_run_demo()
+        elif event.button.id == "clear-btn":
+            self.action_clear_output()
+
+    def action_run_demo(self) -> None:
+        """Run the currently selected demo."""
+        if self._current_demo is None:
+            output_display = self.query_one("#output-display", OutputDisplay)
+            output_display.show_output(
+                "Please select a demo first.", success=False
+            )
+            return
+
+        result = run_demo(self._current_demo)
+        output_display = self.query_one("#output-display", OutputDisplay)
+
+        if result.success:
+            output_display.show_output(result.output, success=True)
+        else:
+            output_display.show_error(
+                result.error or "Unknown error",
+                result.traceback,
+            )
+
+    def action_clear_output(self) -> None:
+        """Clear the output display."""
+        output_display = self.query_one("#output-display", OutputDisplay)
+        output_display.clear()
+
+    def action_show_help(self) -> None:
+        """Show the help screen."""
+        self.push_screen(HelpScreen())
+
+    def action_tree_cursor_down(self) -> None:
+        """Move cursor down in the tree (vim-style j key)."""
+        try:
+            demo_list = self.query_one(DemoList)
+            tree = cast("Tree[object]", demo_list.query_one("#demo-tree"))
+            tree.action_cursor_down()
+        except NoMatches:
+            pass  # Tree might not be focused
+
+    def action_tree_cursor_up(self) -> None:
+        """Move cursor up in the tree (vim-style k key)."""
+        try:
+            demo_list = self.query_one(DemoList)
+            tree = cast("Tree[object]", demo_list.query_one("#demo-tree"))
+            tree.action_cursor_up()
+        except NoMatches:
+            pass  # Tree might not be focused

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