sqliter-py 0.3.0__py3-none-any.whl → 0.5.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,13 @@
-"""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.
+"""
+
+# A dictionary mapping SQLiter filter operators to their corresponding SQL
+# operators.
 OPERATOR_MAPPING = {
     "__lt": "<",
     "__lte": "<=",
@@ -18,3 +26,12 @@ 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",
+}

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,60 @@ 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: '{}'"

sqliter/helpers.py

@@ -0,0 +1,35 @@
+"""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 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")

sqliter/model/__init__.py

@@ -1,6 +1,7 @@
-"""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.
 """
 
 from .model import BaseDBModel

sqliter/model/model.py

@@ -1,17 +1,34 @@
-"""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 re
-from typing import Any, Optional, TypeVar, Union, get_args, get_origin
+from typing import Any, Optional, TypeVar, Union, cast, get_args, get_origin
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 
 T = TypeVar("T", bound="BaseDBModel")
 
 
 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.")
 
     model_config = ConfigDict(
         extra="ignore",
@@ -21,19 +38,31 @@ class BaseDBModel(BaseModel):
     )
 
     class Meta:
-        """Configure the base model with default options."""
+        """Metadata class for configuring database-specific attributes.
+
+        Attributes:
+            create_pk (bool): Whether to create a primary key field.
+            primary_key (str): The name of the primary key field.
+            table_name (Optional[str]): The name of the database 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
         )
 
     @classmethod
     def model_validate_partial(cls: type[T], obj: dict[str, Any]) -> T:
-        """Validate a partial model object."""
+        """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 +87,17 @@ class BaseDBModel(BaseModel):
                 else:
                     converted_obj[field_name] = field_type(value)
 
-        return cls.model_construct(**converted_obj)
+        return cast(T, 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:
@@ -95,10 +125,10 @@ 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

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