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

sqliter/__init__.py

@@ -1,4 +1,8 @@
-"""The 'sqliter' package provides an minimal ORM for  the SQLite library."""
+"""SQLiter: A lightweight ORM-like library for SQLite databases in Python.
+
+This module provides the main SqliterDB class for interacting with
+SQLite databases using Pydantic models.
+"""
 
 from .sqliter import SqliterDB
 

sqliter/constants.py

@@ -1,5 +1,15 @@
-"""Define constants used in the library."""
+"""Constant values and mappings used throughout SQLiter.
 
+This module defines constant dictionaries that map SQLiter-specific
+concepts to their SQLite equivalents. It includes mappings for query
+operators and data types, which are crucial for translating between
+Pydantic models and SQLite database operations.
+"""
+
+import datetime
+
+# A dictionary mapping SQLiter filter operators to their corresponding SQL
+# operators.
 OPERATOR_MAPPING = {
     "__lt": "<",
     "__lte": "<=",
@@ -18,3 +28,18 @@ OPERATOR_MAPPING = {
     "__iendswith": "LIKE",
     "__icontains": "LIKE",
 }
+
+# A dictionary mapping Python types to their corresponding SQLite column types.
+SQLITE_TYPE_MAPPING = {
+    int: "INTEGER",
+    float: "REAL",
+    str: "TEXT",
+    bool: "INTEGER",  # SQLite stores booleans as integers (0 or 1)
+    bytes: "BLOB",
+    datetime.datetime: "INTEGER",  # Store as Unix timestamp
+    datetime.date: "INTEGER",  # Store as Unix timestamp
+    list: "BLOB",
+    dict: "BLOB",
+    set: "BLOB",
+    tuple: "BLOB",
+}

sqliter/exceptions.py

@@ -1,4 +1,11 @@
-"""Define custom exceptions for the sqliter package."""
+"""Custom exception classes for SQLiter error handling.
+
+This module defines a hierarchy of exception classes specific to
+SQLiter operations. These exceptions provide detailed error information
+for various scenarios such as connection issues, invalid queries,
+and CRUD operation failures, enabling more precise error handling
+in applications using SQLiter.
+"""
 
 import os
 import sys
@@ -6,7 +13,15 @@ import traceback
 
 
 class SqliterError(Exception):
-    """Base class for all exceptions raised by the sqliter package."""
+    """Base exception class for all SQLiter-specific errors.
+
+    This class serves as the parent for all custom exceptions in SQLiter,
+    providing a consistent interface and message formatting.
+
+    Attributes:
+        message_template (str): A template string for the error message.
+        original_exception (Exception): The original exception that was caught.
+    """
 
     message_template: str = "An error occurred in the SQLiter package."
 
@@ -59,13 +74,13 @@ class SqliterError(Exception):
 
 
 class DatabaseConnectionError(SqliterError):
-    """Raised when the SQLite database connection fails."""
+    """Exception raised when a database connection cannot be established."""
 
     message_template = "Failed to connect to the database: '{}'"
 
 
 class InvalidOffsetError(SqliterError):
-    """Raised when an invalid offset value (0 or negative) is used."""
+    """Exception raised when an invalid offset value is provided."""
 
     message_template = (
         "Invalid offset value: '{}'. Offset must be a positive integer."
@@ -73,48 +88,81 @@ class InvalidOffsetError(SqliterError):
 
 
 class InvalidOrderError(SqliterError):
-    """Raised when an invalid order value is used."""
+    """Exception raised when an invalid order specification is provided."""
 
     message_template = "Invalid order value - {}"
 
 
 class TableCreationError(SqliterError):
-    """Raised when a table cannot be created in the database."""
+    """Exception raised when a table cannot be created in the database."""
 
     message_template = "Failed to create the table: '{}'"
 
 
 class RecordInsertionError(SqliterError):
-    """Raised when an error occurs during record insertion."""
+    """Exception raised when a record cannot be inserted into the database."""
 
     message_template = "Failed to insert record into table: '{}'"
 
 
 class RecordUpdateError(SqliterError):
-    """Raised when an error occurs during record update."""
+    """Exception raised when a record cannot be updated in the database."""
 
     message_template = "Failed to update record in table: '{}'"
 
 
 class RecordNotFoundError(SqliterError):
-    """Raised when a record with the specified primary key is not found."""
+    """Exception raised when a requested record is not found in the database."""
 
-    message_template = "Failed to find a record for key '{}' "
+    message_template = "Failed to find that record in the table (key '{}') "
 
 
 class RecordFetchError(SqliterError):
-    """Raised when an error occurs during record fetching."""
+    """Exception raised on an error fetching records from the database."""
 
     message_template = "Failed to fetch record from table: '{}'"
 
 
 class RecordDeletionError(SqliterError):
-    """Raised when an error occurs during record deletion."""
+    """Exception raised when a record cannot be deleted from the database."""
 
     message_template = "Failed to delete record from table: '{}'"
 
 
 class InvalidFilterError(SqliterError):
-    """Raised when an invalid filter field is used in a query."""
+    """Exception raised when an invalid filter is applied to a query."""
 
     message_template = "Failed to apply filter: invalid field '{}'"
+
+
+class TableDeletionError(SqliterError):
+    """Raised when a table cannot be deleted from the database."""
+
+    message_template = "Failed to delete the table: '{}'"
+
+
+class SqlExecutionError(SqliterError):
+    """Raised when an SQL execution fails."""
+
+    message_template = "Failed to execute SQL: '{}'"
+
+
+class InvalidIndexError(SqliterError):
+    """Exception raised when an invalid index field is specified.
+
+    This error is triggered if one or more fields specified for an index
+    do not exist in the model's fields.
+
+    Attributes:
+        invalid_fields (list[str]): The list of fields that were invalid.
+        model_class (str): The name of the model where the error occurred.
+    """
+
+    message_template = "Invalid fields for indexing in model '{}': {}"
+
+    def __init__(self, invalid_fields: list[str], model_class: str) -> None:
+        """Tidy up the error message by joining the invalid fields."""
+        # Join invalid fields into a comma-separated string
+        invalid_fields_str = ", ".join(invalid_fields)
+        # Pass the formatted message to the parent class
+        super().__init__(model_class, invalid_fields_str)

sqliter/helpers.py

@@ -0,0 +1,100 @@
+"""Utility functions for SQLiter internal operations.
+
+This module provides helper functions used across the SQLiter library,
+primarily for type inference and mapping between Python and SQLite
+data types. These utilities support the core functionality of model
+to database schema translation.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Union
+
+from sqliter.constants import SQLITE_TYPE_MAPPING
+
+
+def infer_sqlite_type(field_type: Union[type, None]) -> str:
+    """Infer the SQLite column type based on the Python type.
+
+    This function maps Python types to their corresponding SQLite column
+    types. It's used when creating database tables to ensure that the
+    correct SQLite types are used for each field.
+
+    Args:
+        field_type: The Python type of the field, or None.
+
+    Returns:
+        A string representing the corresponding SQLite column type.
+
+    Note:
+        If the input type is None or not recognized, it defaults to 'TEXT'.
+    """
+    # If field_type is None, default to TEXT
+    if field_type is None:
+        return "TEXT"
+
+    # Map the simplified type to an SQLite type
+    return SQLITE_TYPE_MAPPING.get(field_type, "TEXT")
+
+
+def to_unix_timestamp(value: datetime.date | datetime.datetime) -> int:
+    """Convert datetime or date to a Unix timestamp in UTC.
+
+    Args:
+        value: The datetime or date object to convert.
+
+    Returns:
+        An integer Unix timestamp.
+
+    Raises:
+        TypeError: If the value is not a datetime or date object.
+    """
+    if isinstance(value, datetime.datetime):
+        # If no timezone is provided, assume local time and convert to UTC
+        if value.tzinfo is None:
+            value = value.astimezone()  # Convert to user's local timezone
+        # Convert to UTC before storing
+        value = value.astimezone(datetime.timezone.utc)
+        return int(value.timestamp())
+    if isinstance(value, datetime.date):
+        # Convert date to datetime at midnight in UTC
+        dt = datetime.datetime.combine(
+            value, datetime.time(0, 0), tzinfo=datetime.timezone.utc
+        )
+        return int(dt.timestamp())
+
+    err_msg = "Expected datetime or date object."
+    raise TypeError(err_msg)
+
+
+def from_unix_timestamp(
+    value: int, to_type: type, *, localize: bool = True
+) -> datetime.date | datetime.datetime:
+    """Convert a Unix timestamp to datetime or date, optionally to local time.
+
+    Args:
+        value: The Unix timestamp as an integer.
+        to_type: The expected output type, either datetime or date.
+        localize: If True, convert the datetime to the user's local timezone.
+
+    Returns:
+        The corresponding datetime or date object.
+
+    Raises:
+        TypeError: If to_type is not datetime or date.
+    """
+    if to_type is datetime.datetime:
+        # Convert the Unix timestamp to UTC datetime
+        dt = datetime.datetime.fromtimestamp(value, tz=datetime.timezone.utc)
+        # Convert to local time if requested
+        return dt.astimezone() if localize else dt
+    if to_type is datetime.date:
+        # Convert to UTC datetime first
+        dt = datetime.datetime.fromtimestamp(value, tz=datetime.timezone.utc)
+        # Convert to local time if requested, then return the date part
+        dt_local = dt.astimezone() if localize else dt
+        return dt_local.date()  # Extract the date part
+
+    err_msg = "Expected datetime or date type."
+    raise TypeError(err_msg)

sqliter/model/__init__.py

@@ -1,8 +1,11 @@
-"""This module defines the BaseDBModel class.
+"""This module provides the base model class for SQLiter database models.
 
-This should be subclassed by the user to interact with the database.
+It exports the BaseDBModel class, which is used to define database
+models in SQLiter applications, and the Unique class, which is used to
+define unique constraints on model fields.
 """
 
-from .model import BaseDBModel
+from .model import BaseDBModel, SerializableField
+from .unique import Unique
 
-__all__ = ["BaseDBModel"]
+__all__ = ["BaseDBModel", "SerializableField", "Unique"]

sqliter/model/model.py

@@ -1,39 +1,102 @@
-"""Define the Base model class."""
+"""Defines the base model class for SQLiter ORM functionality.
+
+This module provides the BaseDBModel class, which extends Pydantic's
+BaseModel to add SQLiter-specific functionality. It includes methods
+for table name inference, primary key management, and partial model
+validation, forming the foundation for defining database-mapped models
+in SQLiter applications.
+"""
 
 from __future__ import annotations
 
+import datetime
+import pickle
 import re
-from typing import Any, Optional, TypeVar, Union, get_args, get_origin
+from typing import (
+    Any,
+    ClassVar,
+    Optional,
+    Protocol,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+)
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing_extensions import Self
 
-from pydantic import BaseModel, ConfigDict
+from sqliter.helpers import from_unix_timestamp, to_unix_timestamp
 
-T = TypeVar("T", bound="BaseDBModel")
+
+class SerializableField(Protocol):
+    """Protocol for fields that can be serialized or deserialized."""
 
 
 class BaseDBModel(BaseModel):
-    """Custom base model for database models."""
+    """Base model class for SQLiter database models.
+
+    This class extends Pydantic's BaseModel to provide additional functionality
+    for database operations. It includes configuration options and methods
+    specific to SQLiter's ORM-like functionality.
+
+    This should not be used directly, but should be inherited by subclasses
+    representing database models.
+    """
+
+    pk: int = Field(0, description="The mandatory primary key of the table.")
+    created_at: int = Field(
+        default=0,
+        description="Unix timestamp when the record was created.",
+    )
+    updated_at: int = Field(
+        default=0,
+        description="Unix timestamp when the record was last updated.",
+    )
 
     model_config = ConfigDict(
         extra="ignore",
         populate_by_name=True,
-        validate_assignment=False,
+        validate_assignment=True,
         from_attributes=True,
     )
 
     class Meta:
-        """Configure the base model with default options."""
+        """Metadata class for configuring database-specific attributes.
+
+        Attributes:
+            table_name (Optional[str]): The name of the database table. If not
+                specified, the table name will be inferred from the model class
+                name and converted to snake_case.
+            indexes (ClassVar[list[Union[str, tuple[str]]]]): A list of fields
+                or tuples of fields for which regular (non-unique) indexes
+                should be created. Indexes improve query performance on these
+                fields.
+            unique_indexes (ClassVar[list[Union[str, tuple[str]]]]): A list of
+                fields or tuples of fields for which unique indexes should be
+                created. Unique indexes enforce that all values in these fields
+                are distinct across the table.
+        """
 
-        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
         )
+        indexes: ClassVar[list[Union[str, tuple[str]]]] = []
+        unique_indexes: ClassVar[list[Union[str, tuple[str]]]] = []
 
     @classmethod
-    def model_validate_partial(cls: type[T], obj: dict[str, Any]) -> T:
-        """Validate a partial model object."""
+    def model_validate_partial(cls, obj: dict[str, Any]) -> Self:
+        """Validate and create a model instance from partial data.
+
+        This method allows for the creation of a model instance even when
+        not all fields are present in the input data.
+
+        Args:
+            obj: A dictionary of field names and values.
+
+        Returns:
+            An instance of the model class with the provided data.
+        """
         converted_obj: dict[str, Any] = {}
         for field_name, value in obj.items():
             field = cls.model_fields[field_name]
@@ -58,16 +121,17 @@ class BaseDBModel(BaseModel):
                 else:
                     converted_obj[field_name] = field_type(value)
 
-        return cls.model_construct(**converted_obj)
+        return cast("Self", cls.model_construct(**converted_obj))
 
     @classmethod
     def get_table_name(cls) -> str:
-        """Get the table name from the Meta, or generate one.
+        """Get the database table name for the model.
+
+        This method determines the table name based on the Meta configuration
+        or derives it from the class name if not explicitly set.
 
         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.
+            The name of the database table for this model.
         """
         table_name: str | None = getattr(cls.Meta, "table_name", None)
         if table_name is not None:
@@ -81,7 +145,7 @@ class BaseDBModel(BaseModel):
 
         # Pluralize the table name
         try:
-            import inflect
+            import inflect  # noqa: PLC0415
 
             p = inflect.engine()
             return p.plural(snake_case_name)
@@ -95,10 +159,78 @@ class BaseDBModel(BaseModel):
 
     @classmethod
     def get_primary_key(cls) -> str:
-        """Get the primary key from the Meta class or default to 'id'."""
-        return getattr(cls.Meta, "primary_key", "id")
+        """Returns the mandatory primary key, always 'pk'."""
+        return "pk"
 
     @classmethod
     def should_create_pk(cls) -> bool:
-        """Check whether the model should create an auto-increment ID."""
-        return getattr(cls.Meta, "create_pk", True)
+        """Returns True since the primary key is always created."""
+        return True
+
+    @classmethod
+    def serialize_field(cls, value: SerializableField) -> SerializableField:
+        """Serialize datetime or date fields to Unix timestamp.
+
+        Args:
+            field_name: The name of the field.
+            value: The value of the field.
+
+        Returns:
+            An integer Unix timestamp if the field is a datetime or date.
+        """
+        if isinstance(value, (datetime.datetime, datetime.date)):
+            return to_unix_timestamp(value)
+        if isinstance(value, (list, dict, set, tuple)):
+            return pickle.dumps(value)
+        return value  # Return value as-is for other fields
+
+    # Deserialization after fetching from the database
+
+    @classmethod
+    def deserialize_field(
+        cls,
+        field_name: str,
+        value: SerializableField,
+        *,
+        return_local_time: bool,
+    ) -> object:
+        """Deserialize fields from Unix timestamp to datetime or date.
+
+        Args:
+            field_name: The name of the field being deserialized.
+            value: The Unix timestamp value fetched from the database.
+            return_local_time: Flag to control whether the datetime is localized
+                to the user's timezone.
+
+        Returns:
+            A datetime or date object if the field type is datetime or date,
+            otherwise returns the value as-is.
+        """
+        if value is None:
+            return None
+
+        # Get field type if it exists in model_fields
+        field_info = cls.model_fields.get(field_name)
+        if field_info is None:
+            # If field doesn't exist in model, return value as-is
+            return value
+
+        field_type = field_info.annotation
+
+        if (
+            isinstance(field_type, type)
+            and issubclass(field_type, (datetime.datetime, datetime.date))
+            and isinstance(value, int)
+        ):
+            return from_unix_timestamp(
+                value, field_type, localize=return_local_time
+            )
+
+        origin_type = get_origin(field_type) or field_type
+        if origin_type in (list, dict, set, tuple) and isinstance(value, bytes):
+            try:
+                return pickle.loads(value)
+            except pickle.UnpicklingError:
+                return value
+
+        return value

sqliter/model/unique.py

@@ -0,0 +1,19 @@
+"""Define a custom field type for unique constraints in SQLiter."""
+
+from typing import Any
+
+from pydantic.fields import FieldInfo
+
+
+class Unique(FieldInfo):
+    """A custom field type for unique constraints in SQLiter."""
+
+    def __init__(self, default: Any = ..., **kwargs: Any) -> None:  # noqa: ANN401
+        """Initialize a Unique field.
+
+        Args:
+            default: The default value for the field.
+            **kwargs: Additional keyword arguments to pass to FieldInfo.
+        """
+        super().__init__(default=default, **kwargs)
+        self.unique = True

sqliter/query/__init__.py

@@ -1,4 +1,8 @@
-"""Define the 'QueryBuilder' class for building SQL queries."""
+"""This module provides the query building functionality for SQLiter.
+
+It exports the QueryBuilder class, which is used to construct and
+execute database queries in SQLiter.
+"""
 
 from .query import QueryBuilder