sqliter-py 0.2.0__py3-none-any.whl → 0.4.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 '{}' "
 
 
 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,38 +1,144 @@
-"""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
 
-from typing import Optional
+import re
+from typing import Any, Optional, TypeVar, Union, get_args, get_origin
+
+from pydantic import BaseModel, ConfigDict
 
-from pydantic import BaseModel
+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.
+    """
+
+    model_config = ConfigDict(
+        extra="ignore",
+        populate_by_name=True,
+        validate_assignment=False,
+        from_attributes=True,
+    )
 
     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_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 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]
+            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 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:
+            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:
             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:
-        """Get the primary key from the Meta class or default to 'id'."""
+        """Get the primary key field name for the model.
+
+        Returns:
+            The name of the primary key field.
+        """
         return getattr(cls.Meta, "primary_key", "id")
 
     @classmethod
-    def should_create_id(cls) -> bool:
-        """Check whether the model should create an auto-increment ID."""
-        return getattr(cls.Meta, "create_id", True)
+    def should_create_pk(cls) -> bool:
+        """Determine if a primary key should be automatically created.
+
+        Returns:
+            True if a primary key should be created, False otherwise.
+        """
+        return getattr(cls.Meta, "create_pk", 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