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

sqliter/orm/model.py

@@ -0,0 +1,243 @@
+"""ORM model with lazy loading and reverse relationships."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Optional
+
+from pydantic import Field
+
+from sqliter.model.model import BaseDBModel as _BaseDBModel
+from sqliter.orm.fields import ForeignKey, HasPK, LazyLoader
+from sqliter.orm.registry import ModelRegistry
+
+__all__ = ["BaseDBModel"]
+
+
+class BaseDBModel(_BaseDBModel):
+    """Extends BaseDBModel with ORM features.
+
+    Adds:
+    - Lazy loading of foreign key relationships
+    - Automatic reverse relationship setup
+    - db_context for query execution
+    """
+
+    # Store FK descriptors per class (not inherited)
+    fk_descriptors: ClassVar[dict[str, ForeignKey[Any]]] = {}
+
+    # Database context for lazy loading and reverse queries
+    # Using Any since SqliterDB would cause circular import issues with Pydantic
+    db_context: Optional[Any] = Field(default=None, exclude=True)
+
+    def __init__(self, **kwargs: Any) -> None:  # noqa: ANN401
+        """Initialize model, converting FK fields to _id fields."""
+        # Convert FK field values to _id fields before validation
+        for fk_field in self.fk_descriptors:
+            if fk_field in kwargs:
+                value = kwargs[fk_field]
+                if isinstance(value, HasPK):
+                    # Duck typing via Protocol: extract pk from model
+                    kwargs[f"{fk_field}_id"] = value.pk
+                    del kwargs[fk_field]
+                elif isinstance(value, int):
+                    # Already an ID, just move to _id field
+                    kwargs[f"{fk_field}_id"] = value
+                    del kwargs[fk_field]
+                elif value is None:
+                    # Keep None for nullable FKs
+                    kwargs[f"{fk_field}_id"] = None
+                    del kwargs[fk_field]
+
+        super().__init__(**kwargs)
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:  # noqa: ANN401
+        """Dump model, excluding FK descriptor fields.
+
+        FK descriptor fields (like 'author') are excluded from serialization.
+        Only the _id fields (like 'author_id') are included.
+        """
+        data = super().model_dump(**kwargs)
+        # Remove FK descriptor fields from the dump
+        for fk_field in self.fk_descriptors:
+            data.pop(fk_field, None)
+        return data
+
+    def __getattribute__(self, name: str) -> object:
+        """Intercept FK field access to provide lazy loading."""
+        # Check if this is a FK field
+        if name in object.__getattribute__(self, "fk_descriptors"):
+            # Get FK ID
+            fk_id = object.__getattribute__(self, f"{name}_id")
+
+            # Null FK returns None directly (standard ORM behavior)
+            if fk_id is None:
+                return None
+
+            # Check instance cache for identity (same object on repeated access)
+            instance_dict = object.__getattribute__(self, "__dict__")
+            cache = instance_dict.setdefault("_fk_cache", {})
+            db_context = object.__getattribute__(self, "db_context")
+
+            # Check if we need to create or refresh the cached loader
+            cached_loader = cache.get(name)
+            needs_refresh = cached_loader is None or (
+                cached_loader.db_context is None and db_context is not None
+            )
+
+            if needs_refresh:
+                # Get the descriptor and create LazyLoader
+                fk_descs = object.__getattribute__(self, "fk_descriptors")
+                descriptor = fk_descs[name]
+                cache[name] = LazyLoader(
+                    instance=self,
+                    to_model=descriptor.to_model,
+                    fk_id=fk_id,
+                    db_context=db_context,
+                )
+            return cache[name]
+        # For non-FK fields, use normal attribute access
+        return object.__getattribute__(self, name)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        """Intercept FK field assignment to convert to _id field."""
+        # Check if this is a FK field assignment
+        fk_descs = getattr(self, "fk_descriptors", {})
+        if name in fk_descs:
+            # Convert FK assignment to _id field assignment
+            # This bypasses Pydantic's validation for the FK field (which is
+            # not in model_fields) and uses the _id field instead
+            id_field_name = f"{name}_id"
+            if value is None:
+                setattr(self, id_field_name, None)
+            elif isinstance(value, int):
+                setattr(self, id_field_name, value)
+            elif isinstance(value, HasPK):
+                setattr(self, id_field_name, value.pk)
+            else:
+                msg = (
+                    f"FK value must be BaseModel, int, or None, "
+                    f"got {type(value)}"
+                )
+                raise TypeError(msg)
+            return
+
+        # If setting an _id field, clear corresponding FK cache
+        if name.endswith("_id"):
+            fk_name = name[:-3]  # Remove "_id" suffix
+            if fk_name in fk_descs:
+                cache = self.__dict__.get("_fk_cache")
+                if cache and fk_name in cache:
+                    del cache[fk_name]
+        super().__setattr__(name, value)
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:  # noqa: ANN401
+        """Set up ORM field annotations before Pydantic processes the class.
+
+        This runs BEFORE Pydantic populates model_fields, so we add the _id
+        field annotations here so Pydantic creates proper FieldInfo for them.
+        """
+        # Call parent __init_subclass__ FIRST
+        super().__init_subclass__(**kwargs)
+
+        # Collect FK descriptors from class dict
+        if "fk_descriptors" not in cls.__dict__:
+            cls.fk_descriptors = {}
+
+        # Find all ForeignKeys in the class and add _id field annotations
+        # Make a copy of items to avoid modifying dict during iteration
+        class_items = list(cls.__dict__.items())
+        for name, value in class_items:
+            if isinstance(value, ForeignKey):
+                cls.fk_descriptors[name] = value
+                # Add _id field annotation so Pydantic creates a field for it
+                id_field_name = f"{name}_id"
+                if id_field_name not in cls.__annotations__:
+                    if value.fk_info.null:
+                        cls.__annotations__[id_field_name] = Optional[int]
+                        # Nullable FKs default to None so they can be omitted
+                        setattr(cls, id_field_name, None)
+                    else:
+                        cls.__annotations__[id_field_name] = int
+
+                # Remove FK field annotation so Pydantic doesn't treat it as
+                # a field to be copied to instance __dict__ (which breaks
+                # the descriptor protocol)
+                if name in cls.__annotations__:
+                    del cls.__annotations__[name]
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:  # noqa: ANN401
+        """Set up ORM FK metadata after Pydantic has created model_fields.
+
+        This runs AFTER Pydantic populates model_fields, so we can add FK
+        metadata to the _id fields that Pydantic created.
+        """
+        # Call parent __pydantic_init_subclass__ FIRST
+        super().__pydantic_init_subclass__(**kwargs)
+
+        # Process FK descriptors - add FK metadata, register relationships
+        cls._setup_orm_fields()
+
+        # Register model in global registry
+        ModelRegistry.register_model(cls)
+
+    @classmethod
+    def _setup_orm_fields(cls) -> None:
+        """Add FK metadata to _id fields and register FK relationships.
+
+        Called during class creation (after Pydantic setup) to:
+        1. Add FK metadata to _id fields for constraint generation
+        2. Register FK relationships in ModelRegistry
+        3. Remove descriptor from model_fields so Pydantic doesn't validate it
+        """
+        # Get FK descriptors for this class
+        fk_descriptors_copy = cls.fk_descriptors.copy()
+
+        for field_name in fk_descriptors_copy:
+            descriptor = cls.fk_descriptors[field_name]
+
+            # Create _id field name
+            id_field_name = f"{field_name}_id"
+
+            # Get ForeignKeyInfo from descriptor
+            fk_info = descriptor.fk_info
+
+            # The _id field should exist (created by Pydantic from annotation)
+            # We need to add FK metadata for constraint generation
+            if id_field_name in cls.model_fields:
+                existing_field = cls.model_fields[id_field_name]
+
+                # Create ForeignKeyInfo with proper db_column
+                fk_info_for_field = type(fk_info)(
+                    to_model=fk_info.to_model,
+                    on_delete=fk_info.on_delete,
+                    on_update=fk_info.on_update,
+                    null=fk_info.null,
+                    unique=fk_info.unique,
+                    related_name=fk_info.related_name,
+                    db_column=fk_info.db_column or id_field_name,
+                )
+
+                # Add FK metadata to existing field's json_schema_extra
+                # The ForeignKeyInfo is stored for _build_field_definitions()
+                if existing_field.json_schema_extra is None:
+                    existing_field.json_schema_extra = {}
+                if isinstance(existing_field.json_schema_extra, dict):
+                    # ForeignKeyInfo stored for _build_field_definitions
+                    existing_field.json_schema_extra["foreign_key"] = (
+                        fk_info_for_field  # type: ignore[assignment]
+                    )
+
+            # Register FK relationship
+            ModelRegistry.register_foreign_key(
+                from_model=cls,
+                to_model=fk_info.to_model,
+                fk_field=field_name,
+                on_delete=fk_info.on_delete,
+                related_name=descriptor.related_name,
+            )
+
+            # Remove descriptor from model_fields so Pydantic doesn't
+            # validate it
+            if field_name in cls.model_fields:
+                del cls.model_fields[field_name]

sqliter/orm/query.py

@@ -0,0 +1,221 @@
+"""Query builders for reverse relationships."""
+
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Optional,
+    Protocol,
+    overload,
+    runtime_checkable,
+)
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sqliter.model.model import BaseDBModel
+    from sqliter.sqliter import SqliterDB
+
+
+@runtime_checkable
+class HasPKAndContext(Protocol):
+    """Protocol for model instances with pk and db_context."""
+
+    pk: Optional[int]
+    db_context: Optional[SqliterDB]
+
+
+class ReverseQuery:
+    """Query builder for reverse relationships.
+
+    Delegates to QueryBuilder for actual SQL execution.
+    """
+
+    def __init__(
+        self,
+        instance: HasPKAndContext,
+        to_model: type[BaseDBModel],
+        fk_field: str,
+        db_context: Optional[SqliterDB],
+    ) -> None:
+        """Initialize reverse query.
+
+        Args:
+            instance: The model instance (e.g., Author)
+            to_model: The related model class (e.g., Book)
+            fk_field: The FK field name (e.g., "author")
+            db_context: Database connection for queries
+        """
+        self.instance = instance
+        self.to_model = to_model
+        self.fk_field = fk_field
+        self._db = db_context
+        self._filters: dict[str, Any] = {}
+        self._limit: Optional[int] = None
+        self._offset: Optional[int] = None
+
+    @property
+    def fk_value(self) -> Optional[int]:
+        """Get the FK ID value from the instance."""
+        return self.instance.pk
+
+    def filter(self, **kwargs: Any) -> ReverseQuery:  # noqa: ANN401
+        """Store filters for later execution.
+
+        Args:
+            **kwargs: Filter criteria
+
+        Returns:
+            Self for chaining
+        """
+        self._filters.update(kwargs)
+        return self
+
+    def limit(self, count: int) -> ReverseQuery:
+        """Set limit on query results.
+
+        Args:
+            count: Maximum number of results
+
+        Returns:
+            Self for chaining
+        """
+        self._limit = count
+        return self
+
+    def offset(self, count: int) -> ReverseQuery:
+        """Set offset on query results.
+
+        Args:
+            count: Number of results to skip
+
+        Returns:
+            Self for chaining
+        """
+        self._offset = count
+        return self
+
+    def fetch_all(self) -> list[BaseDBModel]:
+        """Execute query using stored db_context.
+
+        Returns:
+            List of related model instances
+        """
+        fk_id = self.fk_value
+        if fk_id is None or self._db is None:
+            return []
+
+        # Build query with FK filter and additional filters
+        query = self._db.select(self.to_model).filter(
+            **{f"{self.fk_field}_id": fk_id}
+        )
+
+        # Apply additional filters
+        if self._filters:
+            query = query.filter(**self._filters)
+
+        # Apply limit and offset
+        if self._limit is not None:
+            query = query.limit(self._limit)
+        if self._offset is not None:
+            query = query.offset(self._offset)
+
+        return query.fetch_all()
+
+    def fetch_one(self) -> Optional[BaseDBModel]:
+        """Execute query and return single result.
+
+        Returns:
+            Related model instance or None
+        """
+        results = self.limit(1).fetch_all()
+        return results[0] if results else None
+
+    def count(self) -> int:
+        """Count related objects.
+
+        Returns:
+            Number of related objects
+        """
+        fk_id = self.fk_value
+        if fk_id is None or self._db is None:
+            return 0
+
+        # Build query with FK filter and additional filters
+        query = self._db.select(self.to_model).filter(
+            **{f"{self.fk_field}_id": fk_id}
+        )
+
+        # Apply additional filters
+        if self._filters:
+            query = query.filter(**self._filters)
+
+        return query.count()
+
+    def exists(self) -> bool:
+        """Check if any related objects exist.
+
+        Returns:
+            True if at least one related object exists
+        """
+        return self.count() > 0
+
+
+class ReverseRelationship:
+    """Descriptor that returns ReverseQuery when accessed.
+
+    Added automatically to models during class creation by ForeignKeyDescriptor.
+    """
+
+    def __init__(
+        self, from_model: type[BaseDBModel], fk_field: str, related_name: str
+    ) -> None:
+        """Initialize reverse relationship descriptor.
+
+        Args:
+            from_model: The model with the FK field (e.g., Book)
+            fk_field: The FK field name (e.g., "author")
+            related_name: The name of this reverse relationship (e.g., "books")
+        """
+        self.from_model = from_model
+        self.fk_field = fk_field
+        self.related_name = related_name
+
+    @overload
+    def __get__(
+        self, instance: None, owner: type[object]
+    ) -> ReverseRelationship: ...
+
+    @overload
+    def __get__(
+        self, instance: HasPKAndContext, owner: type[object]
+    ) -> ReverseQuery: ...
+
+    def __get__(
+        self, instance: Optional[HasPKAndContext], owner: type[object]
+    ) -> ReverseRelationship | ReverseQuery:
+        """Return ReverseQuery when accessed on instance.
+
+        Args:
+            instance: Model instance (e.g., Author)
+            owner: Model class
+
+        Returns:
+            ReverseQuery for fetching related objects
+        """
+        if instance is None:
+            return self
+
+        return ReverseQuery(
+            instance=instance,
+            to_model=self.from_model,
+            fk_field=self.fk_field,
+            db_context=instance.db_context,
+        )
+
+    def __set__(self, instance: object, value: object) -> None:
+        """Prevent setting reverse relationships."""
+        msg = (
+            f"Cannot set reverse relationship '{self.related_name}'. "
+            f"Use the ForeignKey field on {self.from_model.__name__} instead."
+        )
+        raise AttributeError(msg)

sqliter/orm/registry.py

@@ -0,0 +1,169 @@
+"""Model registry for ORM functionality.
+
+Central registry for:
+- Model classes by table name
+- Foreign key relationships
+- Pending reverse relationships
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Optional
+
+
+class ModelRegistry:
+    """Registry for ORM models and FK relationships.
+
+    Uses automatic setup via descriptor __set_name__ hook - no manual setup
+    required.
+    """
+
+    _models: ClassVar[dict[str, type]] = {}
+    _foreign_keys: ClassVar[dict[str, list[dict[str, Any]]]] = {}
+    _pending_reverses: ClassVar[dict[str, list[dict[str, Any]]]] = {}
+
+    @classmethod
+    def register_model(cls, model_class: type[Any]) -> None:
+        """Register a model class in the global registry.
+
+        Args:
+            model_class: The model class to register
+        """
+        table_name = model_class.get_table_name()
+        cls._models[table_name] = model_class
+
+        # Process any pending reverse relationships for this model
+        if table_name in cls._pending_reverses:
+            for pending in cls._pending_reverses[table_name]:
+                cls._add_reverse_relationship_now(**pending)
+            del cls._pending_reverses[table_name]
+
+    @classmethod
+    def register_foreign_key(
+        cls,
+        from_model: type[Any],
+        to_model: type[Any],
+        fk_field: str,
+        on_delete: str,
+        related_name: Optional[str] = None,
+    ) -> None:
+        """Register a FK relationship.
+
+        Args:
+            from_model: The model with the FK field
+            to_model: The model being referenced
+            fk_field: Name of the FK field
+            on_delete: Action when related object is deleted
+            related_name: Name for reverse relationship
+        """
+        from_table = from_model.get_table_name()
+
+        if from_table not in cls._foreign_keys:
+            cls._foreign_keys[from_table] = []
+
+        cls._foreign_keys[from_table].append(
+            {
+                "to_model": to_model,
+                "fk_field": fk_field,
+                "on_delete": on_delete,
+                "related_name": related_name,
+            }
+        )
+
+    @classmethod
+    def get_model(cls, table_name: str) -> Optional[type[Any]]:
+        """Get model by table name.
+
+        Args:
+            table_name: The table name to look up
+
+        Returns:
+            The model class or None if not found
+        """
+        return cls._models.get(table_name)
+
+    @classmethod
+    def get_foreign_keys(cls, table_name: str) -> list[dict[str, Any]]:
+        """Get FK relationships for a model.
+
+        Args:
+            table_name: The table name to look up
+
+        Returns:
+            List of FK relationship dictionaries
+        """
+        return cls._foreign_keys.get(table_name, [])
+
+    @classmethod
+    def add_reverse_relationship(
+        cls,
+        from_model: type[Any],
+        to_model: type[Any],
+        fk_field: str,
+        related_name: str,
+    ) -> None:
+        """Automatically add reverse relationship descriptor during class.
+
+        Called by ForeignKeyDescriptor.__set_name__ during class creation.
+        If to_model doesn't exist yet, stores as pending and adds when
+        to_model is registered.
+
+        Args:
+            from_model: The model with the FK field (e.g., Book)
+            to_model: The model being referenced (e.g., Author)
+            fk_field: Name of the FK field (e.g., "author")
+            related_name: Name for reverse relationship (e.g., "books")
+        """
+        to_table = to_model.get_table_name()
+
+        # Check if to_model has been registered yet
+        if to_table in cls._models:
+            # Model exists, add reverse relationship now
+            cls._add_reverse_relationship_now(
+                from_model, to_model, fk_field, related_name
+            )
+        else:
+            # Model doesn't exist yet, store as pending
+            if to_table not in cls._pending_reverses:
+                cls._pending_reverses[to_table] = []
+            cls._pending_reverses[to_table].append(
+                {
+                    "from_model": from_model,
+                    "to_model": to_model,
+                    "fk_field": fk_field,
+                    "related_name": related_name,
+                }
+            )
+
+    @classmethod
+    def _add_reverse_relationship_now(
+        cls,
+        from_model: type[Any],
+        to_model: type[Any],
+        fk_field: str,
+        related_name: str,
+    ) -> None:
+        """Add reverse relationship descriptor to model.
+
+        Args:
+            from_model: The model with the FK field (e.g., Book)
+            to_model: The model being referenced (e.g., Author)
+            fk_field: Name of the FK field (e.g., "author")
+            related_name: Name for reverse relationship (e.g., "books")
+        """
+        from sqliter.orm.query import ReverseRelationship  # noqa: PLC0415
+
+        # Guard against overwriting existing attributes
+        if hasattr(to_model, related_name):
+            msg = (
+                f"Reverse relationship '{related_name}' already exists on "
+                f"{to_model.__name__}"
+            )
+            raise AttributeError(msg)
+
+        # Add reverse relationship descriptor to to_model
+        setattr(
+            to_model,
+            related_name,
+            ReverseRelationship(from_model, fk_field, related_name),
+        )