sqliter-py 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

sqliter/constants.py

@@ -0,0 +1,20 @@
+"""Define constants used in the library."""
+
+OPERATOR_MAPPING = {
+    "__lt": "<",
+    "__lte": "<=",
+    "__gt": ">",
+    "__gte": ">=",
+    "__eq": "=",
+    "__ne": "!=",
+    "__in": "IN",
+    "__not_in": "NOT IN",
+    "__isnull": "IS NULL",
+    "__notnull": "IS NOT NULL",
+    "__startswith": "LIKE",
+    "__endswith": "LIKE",
+    "__contains": "LIKE",
+    "__istartswith": "LIKE",
+    "__iendswith": "LIKE",
+    "__icontains": "LIKE",
+}

sqliter/exceptions.py

@@ -72,6 +72,12 @@ class InvalidOffsetError(SqliterError):
     )
 
 
+class InvalidOrderError(SqliterError):
+    """Raised when an invalid order value is used."""
+
+    message_template = "Invalid order value - {}"
+
+
 class TableCreationError(SqliterError):
     """Raised when a table cannot be created in the database."""
 

sqliter/model/model.py

@@ -2,30 +2,96 @@
 
 from __future__ import annotations
 
-from typing import Optional
+import re
+from typing import Any, Optional, TypeVar, Union, get_args, get_origin
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
+
+T = TypeVar("T", bound="BaseDBModel")
 
 
 class BaseDBModel(BaseModel):
     """Custom base model for database models."""
 
+    model_config = ConfigDict(
+        extra="ignore",
+        populate_by_name=True,
+        validate_assignment=False,
+        from_attributes=True,
+    )
+
     class Meta:
         """Configure the base model with default options."""
 
-        create_id: bool = True  # Whether to create an auto-increment ID
-        primary_key: str = "id"  # Default primary key field
+        create_pk: bool = (
+            True  # Whether to create an auto-increment primary key
+        )
+        primary_key: str = "id"  # Default primary key name
         table_name: Optional[str] = (
             None  # Table name, defaults to class name if not set
         )
 
+    @classmethod
+    def model_validate_partial(cls: type[T], obj: dict[str, Any]) -> T:
+        """Validate a partial model object."""
+        converted_obj: dict[str, Any] = {}
+        for field_name, value in obj.items():
+            field = cls.model_fields[field_name]
+            field_type: Optional[type] = field.annotation
+            if (
+                field_type is None or value is None
+            ):  # Direct check for None values here
+                converted_obj[field_name] = None
+            else:
+                origin = get_origin(field_type)
+                if origin is Union:
+                    args = get_args(field_type)
+                    for arg in args:
+                        try:
+                            # Try converting the value to the type
+                            converted_obj[field_name] = arg(value)
+                            break
+                        except (ValueError, TypeError):
+                            pass
+                    else:
+                        converted_obj[field_name] = value
+                else:
+                    converted_obj[field_name] = field_type(value)
+
+        return cls.model_construct(**converted_obj)
+
     @classmethod
     def get_table_name(cls) -> str:
-        """Get the table name from the Meta, or default to the classname."""
+        """Get the table name from the Meta, or generate one.
+
+        Returns:
+            str: The table name, either specified in the Meta class or
+                generated by converting the class name to pluralized snake_case
+                and removing any 'Model' suffix.
+        """
         table_name: str | None = getattr(cls.Meta, "table_name", None)
         if table_name is not None:
             return table_name
-        return cls.__name__.lower()  # Default to class name in lowercase
+
+        # Get class name and remove 'Model' suffix if present
+        class_name = cls.__name__.removesuffix("Model")
+
+        # Convert to snake_case
+        snake_case_name = re.sub(r"(?<!^)(?=[A-Z])", "_", class_name).lower()
+
+        # Pluralize the table name
+        try:
+            import inflect
+
+            p = inflect.engine()
+            return p.plural(snake_case_name)
+        except ImportError:
+            # Fallback to simple pluralization by adding 's'
+            return (
+                snake_case_name
+                if snake_case_name.endswith("s")
+                else snake_case_name + "s"
+            )
 
     @classmethod
     def get_primary_key(cls) -> str:
@@ -33,6 +99,6 @@ class BaseDBModel(BaseModel):
         return getattr(cls.Meta, "primary_key", "id")
 
     @classmethod
-    def should_create_id(cls) -> bool:
+    def should_create_pk(cls) -> bool:
         """Check whether the model should create an auto-increment ID."""
-        return getattr(cls.Meta, "create_id", True)
+        return getattr(cls.Meta, "create_pk", True)

sqliter/query/query.py

@@ -3,45 +3,256 @@
 from __future__ import annotations
 
 import sqlite3
-from typing import TYPE_CHECKING, Any, Optional
+import warnings
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    Optional,
+    Union,
+    overload,
+)
 
-from typing_extensions import Self
+from typing_extensions import LiteralString, Self
 
+from sqliter.constants import OPERATOR_MAPPING
 from sqliter.exceptions import (
     InvalidFilterError,
     InvalidOffsetError,
+    InvalidOrderError,
     RecordFetchError,
 )
 
 if TYPE_CHECKING:  # pragma: no cover
+    from pydantic.fields import FieldInfo
+
     from sqliter import SqliterDB
     from sqliter.model import BaseDBModel
 
+# Define a type alias for the possible value types
+FilterValue = Union[
+    str, int, float, bool, None, list[Union[str, int, float, bool]]
+]
+
 
 class QueryBuilder:
     """Functions to build and execute queries for a given model."""
 
-    def __init__(self, db: SqliterDB, model_class: type[BaseDBModel]) -> None:
-        """Initialize the query builder with the database, model class, etc."""
+    def __init__(
+        self,
+        db: SqliterDB,
+        model_class: type[BaseDBModel],
+        fields: Optional[list[str]] = None,
+    ) -> None:
+        """Initialize the query builder.
+
+        Pass the database, model class, and optional fields.
+
+        Args:
+            db: The SqliterDB instance.
+            model_class: The model class to query.
+            fields: Optional list of field names to select. If None, all fields
+                are selected.
+        """
         self.db = db
         self.model_class = model_class
         self.table_name = model_class.get_table_name()  # Use model_class method
-        self.filters: list[tuple[str, Any]] = []
+        self.filters: list[tuple[str, Any, str]] = []
         self._limit: Optional[int] = None
         self._offset: Optional[int] = None
         self._order_by: Optional[str] = None
+        self._fields: Optional[list[str]] = fields
+
+        if self._fields:
+            self._validate_fields()
+
+    def _validate_fields(self) -> None:
+        """Validate that the specified fields exist in the model."""
+        if self._fields is None:
+            return
+        valid_fields = set(self.model_class.model_fields.keys())
+        invalid_fields = set(self._fields) - valid_fields
+        if invalid_fields:
+            err_message = (
+                f"Invalid fields specified: {', '.join(invalid_fields)}"
+            )
+            raise ValueError(err_message)
 
-    def filter(self, **conditions: str | float | None) -> Self:
+    def filter(self, **conditions: str | float | None) -> QueryBuilder:
         """Add filter conditions to the query."""
         valid_fields = self.model_class.model_fields
 
         for field, value in conditions.items():
-            if field not in valid_fields:
-                raise InvalidFilterError(field)
-            self.filters.append((field, value))
+            field_name, operator = self._parse_field_operator(field)
+            self._validate_field(field_name, valid_fields)
+
+            handler = self._get_operator_handler(operator)
+            handler(field_name, value, operator)
+
+        return self
+
+    def fields(self, fields: Optional[list[str]] = None) -> QueryBuilder:
+        """Select specific fields to return in the query."""
+        if fields:
+            self._fields = fields
+            self._validate_fields()
+        return self
+
+    def exclude(self, fields: Optional[list[str]] = None) -> QueryBuilder:
+        """Exclude specific fields from the query output."""
+        if fields:
+            all_fields = set(self.model_class.model_fields.keys())
+
+            # Check for invalid fields before subtraction
+            invalid_fields = set(fields) - all_fields
+            if invalid_fields:
+                err = (
+                    "Invalid fields specified for exclusion: "
+                    f"{', '.join(invalid_fields)}"
+                )
+                raise ValueError(err)
+
+            # Subtract the fields specified for exclusion
+            self._fields = list(all_fields - set(fields))
+
+            # Explicit check: raise an error if no fields remain
+            if not self._fields:
+                err = "Exclusion results in no fields being selected."
+                raise ValueError(err)
+
+            # Now validate the remaining fields to ensure they are all valid
+            self._validate_fields()
+
+        return self
+
+    def only(self, field: str) -> QueryBuilder:
+        """Return only the specified single field."""
+        all_fields = set(self.model_class.model_fields.keys())
+
+        # Validate that the field exists
+        if field not in all_fields:
+            err = f"Invalid field specified: {field}"
+            raise ValueError(err)
 
+        # Set self._fields to just the single field
+        self._fields = [field]
         return self
 
+    def _get_operator_handler(
+        self, operator: str
+    ) -> Callable[[str, Any, str], None]:
+        handlers = {
+            "__isnull": self._handle_null,
+            "__notnull": self._handle_null,
+            "__in": self._handle_in,
+            "__not_in": self._handle_in,
+            "__startswith": self._handle_like,
+            "__endswith": self._handle_like,
+            "__contains": self._handle_like,
+            "__istartswith": self._handle_like,
+            "__iendswith": self._handle_like,
+            "__icontains": self._handle_like,
+            "__lt": self._handle_comparison,
+            "__lte": self._handle_comparison,
+            "__gt": self._handle_comparison,
+            "__gte": self._handle_comparison,
+            "__ne": self._handle_comparison,
+        }
+        return handlers.get(operator, self._handle_equality)
+
+    def _validate_field(
+        self, field_name: str, valid_fields: dict[str, FieldInfo]
+    ) -> None:
+        if field_name not in valid_fields:
+            raise InvalidFilterError(field_name)
+
+    def _handle_equality(
+        self, field_name: str, value: FilterValue, operator: str
+    ) -> None:
+        if value is None:
+            self.filters.append((f"{field_name} IS NULL", None, "__isnull"))
+        else:
+            self.filters.append((field_name, value, operator))
+
+    def _handle_null(
+        self, field_name: str, _: FilterValue, operator: str
+    ) -> None:
+        condition = (
+            f"{field_name} IS NOT NULL"
+            if operator == "__notnull"
+            else f"{field_name} IS NULL"
+        )
+        self.filters.append((condition, None, operator))
+
+    def _handle_in(
+        self, field_name: str, value: FilterValue, operator: str
+    ) -> None:
+        if not isinstance(value, list):
+            err = f"{field_name} requires a list for '{operator}'"
+            raise TypeError(err)
+        sql_operator = OPERATOR_MAPPING.get(operator, "IN")
+        placeholder_list = ", ".join(["?"] * len(value))
+        self.filters.append(
+            (
+                f"{field_name} {sql_operator} ({placeholder_list})",
+                value,
+                operator,
+            )
+        )
+
+    def _handle_like(
+        self, field_name: str, value: FilterValue, operator: str
+    ) -> None:
+        if not isinstance(value, str):
+            err = f"{field_name} requires a string value for '{operator}'"
+            raise TypeError(err)
+        formatted_value = self._format_string_for_operator(operator, value)
+        if operator in ["__startswith", "__endswith", "__contains"]:
+            self.filters.append(
+                (
+                    f"{field_name} GLOB ?",
+                    [formatted_value],
+                    operator,
+                )
+            )
+        elif operator in ["__istartswith", "__iendswith", "__icontains"]:
+            self.filters.append(
+                (
+                    f"{field_name} LIKE ?",
+                    [formatted_value],
+                    operator,
+                )
+            )
+
+    def _handle_comparison(
+        self, field_name: str, value: FilterValue, operator: str
+    ) -> None:
+        sql_operator = OPERATOR_MAPPING[operator]
+        self.filters.append((f"{field_name} {sql_operator} ?", value, operator))
+
+    # Helper method for parsing field and operator
+    def _parse_field_operator(self, field: str) -> tuple[str, str]:
+        for operator in OPERATOR_MAPPING:
+            if field.endswith(operator):
+                return field[: -len(operator)], operator
+        return field, "__eq"  # Default to equality if no operator is found
+
+    # Helper method for formatting string operators (like startswith)
+    def _format_string_for_operator(self, operator: str, value: str) -> str:
+        # Mapping operators to their corresponding string format
+        format_map = {
+            "__startswith": f"{value}*",
+            "__endswith": f"*{value}",
+            "__contains": f"*{value}*",
+            "__istartswith": f"{value.lower()}%",
+            "__iendswith": f"%{value.lower()}",
+            "__icontains": f"%{value.lower()}%",
+        }
+
+        # Return the formatted string or the original value if no match
+        return format_map.get(operator, value)
+
     def limit(self, limit_value: int) -> Self:
         """Limit the number of results returned by the query."""
         self._limit = limit_value
@@ -49,7 +260,7 @@ class QueryBuilder:
 
     def offset(self, offset_value: int) -> Self:
         """Set an offset value for the query."""
-        if offset_value <= 0:
+        if offset_value < 0:
             raise InvalidOffsetError(offset_value)
         self._offset = offset_value
 
@@ -57,28 +268,83 @@ class QueryBuilder:
             self._limit = -1
         return self
 
-    def order(self, order_by_field: str) -> Self:
-        """Order the results by a specific field and optionally direction."""
-        self._order_by = order_by_field
+    def order(
+        self,
+        order_by_field: str,
+        direction: Optional[str] = None,
+        *,
+        reverse: bool = False,
+    ) -> Self:
+        """Order the query results by the specified field.
+
+        Args:
+            order_by_field (str): The field to order by.
+            direction (Optional[str]): The ordering direction ('ASC' or 'DESC').
+                This is deprecated in favor of 'reverse'.
+            reverse (bool): Whether to reverse the order (True for descending,
+                False for ascending).
+
+        Raises:
+            InvalidOrderError: If the field doesn't exist in the model fields
+                or if both 'direction' and 'reverse' are specified.
+
+        Returns:
+            QueryBuilder: The current query builder instance with updated
+                ordering.
+        """
+        if direction:
+            warnings.warn(
+                "'direction' argument is deprecated and will be removed in a "
+                "future version. Use 'reverse' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        if order_by_field not in self.model_class.model_fields:
+            err = f"'{order_by_field}' does not exist in the model fields."
+            raise InvalidOrderError(err)
+        # Raise an exception if both 'direction' and 'reverse' are specified
+        if direction and reverse:
+            err = (
+                "Cannot specify both 'direction' and 'reverse' as it "
+                "is ambiguous."
+            )
+            raise InvalidOrderError(err)
+
+        # Determine the sorting direction
+        if reverse:
+            sort_order = "DESC"
+        elif direction:
+            sort_order = direction.upper()
+            if sort_order not in {"ASC", "DESC"}:
+                err = f"'{direction}' is not a valid sorting direction."
+                raise InvalidOrderError(err)
+        else:
+            sort_order = "ASC"
+
+        self._order_by = f'"{order_by_field}" {sort_order}'
         return self
 
     def _execute_query(
         self,
         *,
         fetch_one: bool = False,
+        count_only: bool = False,
     ) -> list[tuple[Any, ...]] | Optional[tuple[Any, ...]]:
         """Helper function to execute the query with filters."""
-        fields = ", ".join(self.model_class.model_fields)
+        if count_only:
+            fields = "COUNT(*)"
+        elif self._fields:
+            fields = ", ".join(f'"{field}"' for field in self._fields)
+        else:
+            fields = ", ".join(
+                f'"{field}"' for field in self.model_class.model_fields
+            )
 
-        # Build the WHERE clause with special handling for None (NULL in SQL)
-        where_clause = " AND ".join(
-            [
-                f"{field} IS NULL" if value is None else f"{field} = ?"
-                for field, value in self.filters
-            ]
-        )
+        sql = f'SELECT {fields} FROM "{self.table_name}"'  # noqa: S608 # nosec
 
-        sql = f"SELECT {fields} FROM {self.table_name}"  # noqa: S608
+        # Build the WHERE clause with special handling for None (NULL in SQL)
+        values, where_clause = self._parse_filter()
 
         if self.filters:
             sql += f" WHERE {where_clause}"
@@ -87,13 +353,12 @@ class QueryBuilder:
             sql += f" ORDER BY {self._order_by}"
 
         if self._limit is not None:
-            sql += f" LIMIT {self._limit}"
+            sql += " LIMIT ?"
+            values.append(self._limit)
 
         if self._offset is not None:
-            sql += f" OFFSET {self._offset}"
-
-        # Only include non-None values in the values list
-        values = [value for _, value in self.filters if value is not None]
+            sql += " OFFSET ?"
+            values.append(self._offset)
 
         try:
             with self.db.connect() as conn:
@@ -103,80 +368,93 @@ class QueryBuilder:
         except sqlite3.Error as exc:
             raise RecordFetchError(self.table_name) from exc
 
-    def fetch_all(self) -> list[BaseDBModel]:
-        """Fetch all results matching the filters."""
-        results = self._execute_query()
-
-        if not results:
-            return []
-
-        return [
-            self.model_class(
-                **{
-                    field: row[idx]
-                    for idx, field in enumerate(self.model_class.model_fields)
-                }
+    def _parse_filter(self) -> tuple[list[Any], LiteralString]:
+        """Actually parse the filters."""
+        where_clauses = []
+        values = []
+        for field, value, operator in self.filters:
+            if operator == "__eq":
+                where_clauses.append(f"{field} = ?")
+                values.append(value)
+            else:
+                where_clauses.append(field)
+                if operator not in ["__isnull", "__notnull"]:
+                    if isinstance(value, list):
+                        values.extend(value)
+                    else:
+                        values.append(value)
+
+        where_clause = " AND ".join(where_clauses)
+        return values, where_clause
+
+    def _convert_row_to_model(self, row: tuple[Any, ...]) -> BaseDBModel:
+        """Convert a result row tuple into a Pydantic model."""
+        if self._fields:
+            return self.model_class.model_validate_partial(
+                {field: row[idx] for idx, field in enumerate(self._fields)}
             )
-            for row in results
-        ]
-
-    def fetch_one(self) -> BaseDBModel | None:
-        """Fetch exactly one result."""
-        result = self._execute_query(fetch_one=True)
-        if not result:
-            return None
         return self.model_class(
             **{
-                field: result[idx]
+                field: row[idx]
                 for idx, field in enumerate(self.model_class.model_fields)
             }
         )
 
-    def fetch_first(self) -> BaseDBModel | None:
+    @overload
+    def _fetch_result(
+        self, *, fetch_one: Literal[True]
+    ) -> Optional[BaseDBModel]: ...
+
+    @overload
+    def _fetch_result(
+        self, *, fetch_one: Literal[False]
+    ) -> list[BaseDBModel]: ...
+
+    def _fetch_result(
+        self, *, fetch_one: bool = False
+    ) -> Union[list[BaseDBModel], Optional[BaseDBModel]]:
+        """Fetch one or all results and convert them to Pydantic models."""
+        result = self._execute_query(fetch_one=fetch_one)
+
+        if not result:
+            if fetch_one:
+                return None
+            return []
+
+        if fetch_one:
+            # Ensure we pass a tuple, not a list, to _convert_row_to_model
+            if isinstance(result, list):
+                result = result[
+                    0
+                ]  # Get the first (and only) result if it's wrapped in a list.
+            return self._convert_row_to_model(result)
+
+        return [self._convert_row_to_model(row) for row in result]
+
+    def fetch_all(self) -> list[BaseDBModel]:
+        """Fetch all results matching the filters."""
+        return self._fetch_result(fetch_one=False)
+
+    def fetch_one(self) -> Optional[BaseDBModel]:
+        """Fetch exactly one result."""
+        return self._fetch_result(fetch_one=True)
+
+    def fetch_first(self) -> Optional[BaseDBModel]:
         """Fetch the first result of the query."""
         self._limit = 1
-        result = self._execute_query()
-        if not result:
-            return None
-        return self.model_class(
-            **{
-                field: result[0][idx]
-                for idx, field in enumerate(self.model_class.model_fields)
-            }
-        )
+        return self._fetch_result(fetch_one=True)
 
-    def fetch_last(self) -> BaseDBModel | None:
+    def fetch_last(self) -> Optional[BaseDBModel]:
         """Fetch the last result of the query (based on the insertion order)."""
         self._limit = 1
         self._order_by = "rowid DESC"
-        result = self._execute_query()
-        if not result:
-            return None
-        return self.model_class(
-            **{
-                field: result[0][idx]
-                for idx, field in enumerate(self.model_class.model_fields)
-            }
-        )
+        return self._fetch_result(fetch_one=True)
 
     def count(self) -> int:
         """Return the count of records matching the filters."""
-        where_clause = " AND ".join(
-            [f"{field} = ?" for field, _ in self.filters]
-        )
-        sql = f"SELECT COUNT(*) FROM {self.table_name}"  # noqa: S608
-
-        if self.filters:
-            sql += f" WHERE {where_clause}"
-
-        values = [value for _, value in self.filters]
-
-        with self.db.connect() as conn:
-            cursor = conn.cursor()
-            cursor.execute(sql, values)
-            result = cursor.fetchone()
+        result = self._execute_query(count_only=True)
 
-        return int(result[0]) if result else 0
+        return int(result[0][0]) if result else 0
 
     def exists(self) -> bool:
         """Return True if any record matches the filters."""