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

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),
+        )