sqliter-py 0.12.0__py3-none-any.whl

sqliter/__init__.py

@@ -0,0 +1,9 @@
+"""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
+
+__all__ = ["SqliterDB"]

sqliter/constants.py

@@ -0,0 +1,45 @@
+"""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": "<=",
+    "__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",
+}
+
+# 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

@@ -0,0 +1,198 @@
+"""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
+import traceback
+
+
+class SqliterError(Exception):
+    """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."
+
+    def __init__(self, *args: object) -> None:
+        """Format the message using the provided arguments.
+
+        We also capture (and display) the current exception context and chain
+        any previous exceptions.
+
+        :param args: Arguments to format into the message template
+        """
+        if args:
+            message = self.message_template.format(*args)
+        else:
+            message = (
+                self.message_template.replace("'{}'", "")
+                .replace(":", "")
+                .strip()
+            )
+
+        # Capture the current exception context
+        self.original_exception = sys.exc_info()[1]
+
+        # If there's an active exception, append its information to our message
+        if self.original_exception:
+            original_type = type(self.original_exception).__name__
+            original_module = type(self.original_exception).__module__
+
+            # Get the traceback of the original exception
+            tb = traceback.extract_tb(self.original_exception.__traceback__)
+            if tb:
+                last_frame = tb[-1]
+                file_path = os.path.relpath(last_frame.filename)
+                line_number = last_frame.lineno
+                location = f"{file_path}:{line_number}"
+            else:
+                location = "unknown location"
+
+            message += (
+                f"\n  --> {original_module}.{original_type} "
+                f"from {location}: {self.original_exception}"
+            )
+
+        # Call the parent constructor with our formatted message
+        super().__init__(message)
+
+        # Explicitly chain exceptions if there's an active one
+        if self.original_exception:
+            self.__cause__ = self.original_exception
+
+
+class DatabaseConnectionError(SqliterError):
+    """Exception raised when a database connection cannot be established."""
+
+    message_template = "Failed to connect to the database: '{}'"
+
+
+class InvalidOffsetError(SqliterError):
+    """Exception raised when an invalid offset value is provided."""
+
+    message_template = (
+        "Invalid offset value: '{}'. Offset must be a positive integer."
+    )
+
+
+class InvalidOrderError(SqliterError):
+    """Exception raised when an invalid order specification is provided."""
+
+    message_template = "Invalid order value - {}"
+
+
+class TableCreationError(SqliterError):
+    """Exception raised when a table cannot be created in the database."""
+
+    message_template = "Failed to create the table: '{}'"
+
+
+class RecordInsertionError(SqliterError):
+    """Exception raised when a record cannot be inserted into the database."""
+
+    message_template = "Failed to insert record into table: '{}'"
+
+
+class RecordUpdateError(SqliterError):
+    """Exception raised when a record cannot be updated in the database."""
+
+    message_template = "Failed to update record in table: '{}'"
+
+
+class RecordNotFoundError(SqliterError):
+    """Exception raised when a requested record is not found in the database."""
+
+    message_template = "Failed to find that record in the table (key '{}') "
+
+
+class RecordFetchError(SqliterError):
+    """Exception raised on an error fetching records from the database."""
+
+    message_template = "Failed to fetch record from table: '{}'"
+
+
+class RecordDeletionError(SqliterError):
+    """Exception raised when a record cannot be deleted from the database."""
+
+    message_template = "Failed to delete record from table: '{}'"
+
+
+class InvalidFilterError(SqliterError):
+    """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)
+
+
+class ForeignKeyError(SqliterError):
+    """Base exception for foreign key related errors."""
+
+    message_template = "Foreign key error: {}"
+
+
+class ForeignKeyConstraintError(ForeignKeyError):
+    """Raised when a foreign key constraint is violated.
+
+    This error occurs when attempting to insert/update a record with a
+    foreign key value that doesn't exist in the referenced table, or
+    when attempting to delete a record that is still referenced.
+    """
+
+    message_template = (
+        "Foreign key constraint violation: Cannot {} record - "
+        "referenced record {}"
+    )
+
+
+class InvalidForeignKeyError(ForeignKeyError):
+    """Raised when an invalid foreign key configuration is detected.
+
+    This error occurs when defining a foreign key with invalid parameters,
+    such as using SET NULL without null=True.
+    """
+
+    message_template = "Invalid foreign key configuration: {}"

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

@@ -0,0 +1,46 @@
+"""This module provides the base model class for SQLiter database models.
+
+It exports the BaseDBModel class, which is used to define database
+models in SQLiter applications, and the unique function, which is used to
+define unique constraints on model fields.
+"""
+
+import warnings
+from typing import Any
+
+from typing_extensions import deprecated
+
+from .foreign_key import ForeignKey, ForeignKeyInfo, get_foreign_key_info
+from .model import BaseDBModel, SerializableField
+from .unique import unique
+
+
+@deprecated("Use 'unique' instead. Will be removed in a future version.")
+def Unique(default: Any = ..., **kwargs: Any) -> Any:  # noqa: ANN401, N802
+    """Deprecated: Use 'unique' instead. Will be removed in a future version.
+
+    Args:
+        default: The default value for the field.
+        **kwargs: Additional keyword arguments to pass to Field.
+
+    Returns:
+        A Field with unique metadata attached.
+    """
+    warnings.warn(
+        "Unique is deprecated and will be removed in a future version. "
+        "Use 'unique' instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return unique(default=default, **kwargs)
+
+
+__all__ = [
+    "BaseDBModel",
+    "ForeignKey",
+    "ForeignKeyInfo",
+    "SerializableField",
+    "Unique",
+    "get_foreign_key_info",
+    "unique",
+]

sqliter/model/foreign_key.py

@@ -0,0 +1,153 @@
+"""Foreign key support for SQLiter ORM.
+
+This module provides the ForeignKey factory function and ForeignKeyInfo
+dataclass for defining foreign key relationships between models.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, Optional
+
+from pydantic import Field
+
+from sqliter.exceptions import InvalidForeignKeyError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from pydantic.fields import FieldInfo
+
+    from sqliter.model.model import BaseDBModel
+
+# Type alias for foreign key actions
+FKAction = Literal["CASCADE", "SET NULL", "RESTRICT", "NO ACTION"]
+
+
+@dataclass
+class ForeignKeyInfo:
+    """Metadata about a foreign key relationship.
+
+    Attributes:
+        to_model: The target model class that this foreign key references.
+        on_delete: Action to take when the referenced record is deleted.
+        on_update: Action to take when the referenced record's PK is updated.
+        null: Whether the foreign key field can be NULL.
+        unique: Whether the foreign key field must be unique (one-to-one).
+        related_name: Optional name for the reverse relationship (Phase 2).
+        db_column: Optional custom column name in the database.
+    """
+
+    to_model: type[BaseDBModel]
+    on_delete: FKAction
+    on_update: FKAction
+    null: bool
+    unique: bool
+    related_name: Optional[str]
+    db_column: Optional[str]
+
+
+def ForeignKey(  # noqa: N802, PLR0913
+    to: type[BaseDBModel],
+    *,
+    on_delete: FKAction = "RESTRICT",
+    on_update: FKAction = "RESTRICT",
+    null: bool = False,
+    unique: bool = False,
+    related_name: Optional[str] = None,
+    db_column: Optional[str] = None,
+    default: Any = ...,  # noqa: ANN401
+    **kwargs: Any,  # noqa: ANN401
+) -> Any:  # noqa: ANN401
+    """Create a foreign key field.
+
+    This function creates a Pydantic Field with foreign key metadata stored
+    in json_schema_extra. In Phase 1, this provides FK constraint support.
+    Phase 2 will add descriptor support for `book.author` style access.
+
+    Args:
+        to: The target model class that this foreign key references.
+        on_delete: Action when referenced record is deleted.
+            - CASCADE: Delete this record too.
+            - SET NULL: Set this field to NULL (requires null=True).
+            - RESTRICT: Prevent deletion if references exist (default).
+            - NO ACTION: Similar to RESTRICT in SQLite.
+        on_update: Action when referenced record's PK is updated.
+            - CASCADE: Update this field to the new PK value.
+            - SET NULL: Set this field to NULL (requires null=True).
+            - RESTRICT: Prevent update if references exist (default).
+            - NO ACTION: Similar to RESTRICT in SQLite.
+        null: Whether the foreign key field can be NULL. Default is False.
+        unique: Whether the field must be unique (creates one-to-one
+            relationship). Default is False.
+        related_name: Optional name for the reverse relationship. Reserved
+            for Phase 2 implementation.
+        db_column: Optional custom column name. If not specified, defaults
+            to `{field_name}_id`.
+        default: Default value for the field. If null=True and no default
+            is provided, defaults to None.
+        **kwargs: Additional keyword arguments passed to Pydantic Field.
+
+    Returns:
+        A Pydantic Field with foreign key metadata.
+
+    Raises:
+        InvalidForeignKeyError: If SET NULL action is used without null=True.
+
+    Example:
+        >>> class Book(BaseDBModel):
+        ...     title: str
+        ...     author_id: int = ForeignKey(Author, on_delete="CASCADE")
+    """
+    # Validate SET NULL requires null=True
+    if on_delete == "SET NULL" and not null:
+        msg = "on_delete='SET NULL' requires null=True"
+        raise InvalidForeignKeyError(msg)
+    if on_update == "SET NULL" and not null:
+        msg = "on_update='SET NULL' requires null=True"
+        raise InvalidForeignKeyError(msg)
+
+    # Handle existing json_schema_extra
+    existing_extra = kwargs.pop("json_schema_extra", {})
+    if not isinstance(existing_extra, dict):
+        existing_extra = {}
+
+    # Create ForeignKeyInfo metadata
+    fk_info = ForeignKeyInfo(
+        to_model=to,
+        on_delete=on_delete,
+        on_update=on_update,
+        null=null,
+        unique=unique,
+        related_name=related_name,
+        db_column=db_column,
+    )
+
+    # Store FK metadata in json_schema_extra
+    existing_extra["foreign_key"] = fk_info
+    if unique:
+        existing_extra["unique"] = True
+
+    # Set default value
+    if default is ... and "default_factory" not in kwargs:
+        default = None if null else ...
+
+    return Field(default=default, json_schema_extra=existing_extra, **kwargs)
+
+
+def get_foreign_key_info(field_info: FieldInfo) -> Optional[ForeignKeyInfo]:
+    """Extract ForeignKeyInfo from a field if it's a foreign key.
+
+    Args:
+        field_info: The Pydantic FieldInfo to examine.
+
+    Returns:
+        The ForeignKeyInfo if the field is a foreign key, None otherwise.
+    """
+    if not hasattr(field_info, "json_schema_extra"):
+        return None
+    extra = field_info.json_schema_extra
+    if not isinstance(extra, dict):
+        return None
+    fk_info = extra.get("foreign_key")
+    if isinstance(fk_info, ForeignKeyInfo):
+        return fk_info
+    return None