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

sqliter/constants.py

@@ -21,9 +21,10 @@ OPERATOR_MAPPING = {
     "__not_in": "NOT IN",
     "__isnull": "IS NULL",
     "__notnull": "IS NOT NULL",
-    "__startswith": "LIKE",
-    "__endswith": "LIKE",
-    "__contains": "LIKE",
+    "__like": "LIKE",
+    "__startswith": "GLOB",
+    "__endswith": "GLOB",
+    "__contains": "GLOB",
     "__istartswith": "LIKE",
     "__iendswith": "LIKE",
     "__icontains": "LIKE",

sqliter/exceptions.py

@@ -166,3 +166,46 @@ class InvalidIndexError(SqliterError):
         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: {}"
+
+
+class InvalidRelationshipError(SqliterError):
+    """Raised when an invalid relationship path is specified.
+
+    This error occurs when using select_related() or relationship filter
+    traversal with a non-existent relationship field or invalid path.
+    """
+
+    message_template = (
+        "Invalid relationship path '{}': field '{}' is not a valid "
+        "foreign key relationship on model {}"
+    )

sqliter/model/__init__.py

@@ -1,11 +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 class, which is used to
+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
+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", "SerializableField", "Unique"]
+__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

sqliter/model/model.py

@@ -123,6 +123,32 @@ class BaseDBModel(BaseModel):
 
         return cast("Self", cls.model_construct(**converted_obj))
 
+    @staticmethod
+    def _validate_table_name(table_name: str) -> str:
+        """Validate that a table name contains only safe characters.
+
+        Table names must contain only alphanumeric characters and underscores,
+        and must start with a letter or underscore. This prevents SQL injection
+        through malicious table names.
+
+        Args:
+            table_name: The table name to validate.
+
+        Returns:
+            The validated table name.
+
+        Raises:
+            ValueError: If the table name contains invalid characters.
+        """
+        if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", table_name):
+            msg = (
+                f"Invalid table name '{table_name}'. "
+                "Table names must start with a letter or underscore and "
+                "contain only letters, numbers, and underscores."
+            )
+            raise ValueError(msg)
+        return table_name
+
     @classmethod
     def get_table_name(cls) -> str:
         """Get the database table name for the model.
@@ -130,12 +156,22 @@ class BaseDBModel(BaseModel):
         This method determines the table name based on the Meta configuration
         or derives it from the class name if not explicitly set.
 
+        When deriving the table name automatically, the class name is converted
+        to snake_case and pluralized. If the `inflect` library is installed,
+        it provides grammatically correct pluralization (e.g., "person" becomes
+        "people", "category" becomes "categories"). Otherwise, a simple "s"
+        suffix is added if the name doesn't already end in "s".
+
         Returns:
             The name of the database table for this model.
+
+        Raises:
+            ValueError: If the table name contains invalid characters.
         """
         table_name: str | None = getattr(cls.Meta, "table_name", None)
         if table_name is not None:
-            return table_name
+            # Validate custom table names
+            return cls._validate_table_name(table_name)
 
         # Get class name and remove 'Model' suffix if present
         class_name = cls.__name__.removesuffix("Model")
@@ -148,15 +184,18 @@ class BaseDBModel(BaseModel):
             import inflect  # noqa: PLC0415
 
             p = inflect.engine()
-            return p.plural(snake_case_name)
+            table_name = p.plural(snake_case_name)
         except ImportError:
             # Fallback to simple pluralization by adding 's'
-            return (
+            table_name = (
                 snake_case_name
                 if snake_case_name.endswith("s")
                 else snake_case_name + "s"
             )
 
+        # Validate auto-generated table names (should always pass)
+        return cls._validate_table_name(table_name)
+
     @classmethod
     def get_primary_key(cls) -> str:
         """Returns the mandatory primary key, always 'pk'."""

sqliter/model/unique.py

@@ -2,18 +2,27 @@
 
 from typing import Any
 
-from pydantic.fields import FieldInfo
+from pydantic import Field
 
 
-class Unique(FieldInfo):
-    """A custom field type for unique constraints in SQLiter."""
+def unique(default: Any = ..., **kwargs: Any) -> Any:  # noqa: ANN401
+    """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 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
+    Returns:
+        A Field with unique metadata attached.
+    """
+    # Extract any existing json_schema_extra from kwargs
+    existing_extra = kwargs.pop("json_schema_extra", {})
+
+    # Ensure it's a dict
+    if not isinstance(existing_extra, dict):
+        existing_extra = {}
+
+    # Add our unique marker to json_schema_extra
+    existing_extra["unique"] = True
+
+    return Field(default=default, json_schema_extra=existing_extra, **kwargs)

sqliter/orm/__init__.py

@@ -0,0 +1,16 @@
+"""ORM submodule for SQLiter.
+
+This module provides ORM functionality including lazy loading and reverse
+relationships. It extends the BaseDBModel from sqliter.model without breaking
+changes to the existing code.
+
+Users can choose between modes via import:
+    - Legacy mode: from sqliter.model import BaseDBModel
+    - ORM mode: from sqliter.orm import BaseDBModel
+"""
+
+from sqliter.orm.foreign_key import ForeignKey
+from sqliter.orm.model import BaseDBModel
+from sqliter.orm.registry import ModelRegistry
+
+__all__ = ["BaseDBModel", "ForeignKey", "ModelRegistry"]