plain.postgres 0.84.0__py3-none-any.whl

plain/postgres/fields/related_descriptors.py

@@ -0,0 +1,290 @@
+"""
+Accessors for related objects.
+
+When a field defines a relation between two models, the forward model provides
+an attribute to access related instances. Reverse accessors must be explicitly
+defined using ReverseForeignKey or ReverseManyToMany descriptors.
+
+Accessors are implemented as descriptors in order to customize access and
+assignment. This module defines the descriptor classes.
+
+Forward accessors follow foreign keys. Reverse accessors trace them back. For
+example, with the following models::
+
+    class Parent(Model):
+        children: ReverseForeignKey[Child] = ReverseForeignKey(to="Child", field="parent")
+
+    class Child(Model):
+        parent: Parent = ForeignKeyField(Parent, on_delete=models.CASCADE)
+
+ ``child.parent`` is a forward foreign key relation. ``parent.children`` is a
+reverse foreign key relation.
+
+1. Related instance on the forward side of a foreign key relation:
+   ``ForwardForeignKeyDescriptor``.
+
+   Uniqueness of foreign key values is irrelevant to accessing the related
+   instance, making the many-to-one and one-to-one cases identical as far as
+   the descriptor is concerned. The constraint is checked upstream (unicity
+   validation in forms) or downstream (unique indexes in the database).
+
+2. Related objects manager for related instances on the forward or reverse
+   sides of a many-to-many relation: ``ForwardManyToManyDescriptor``.
+
+   Many-to-many relations are symmetrical. The syntax of Plain models
+   requires declaring them on one side but that's an implementation detail.
+   They could be declared on the other side without any change in behavior.
+
+Reverse relations must be explicitly defined using ``ReverseForeignKey`` or
+``ReverseManyToMany`` descriptors on the model class.
+"""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Any
+
+from plain.postgres.query import QuerySet
+from plain.utils.functional import LazyObject
+
+from .related_managers import ManyToManyManager
+
+
+class ForwardForeignKeyDescriptor:
+    """
+    Accessor to the related object on the forward side of a foreign key relation.
+
+    In the example::
+
+        class Child(Model):
+            parent: Parent = ForeignKeyField(Parent, on_delete=models.CASCADE)
+
+    ``Child.parent`` is a ``ForwardForeignKeyDescriptor`` instance.
+    """
+
+    def __init__(self, field_with_rel: Any) -> None:
+        self.field = field_with_rel
+
+    @cached_property
+    def RelatedObjectDoesNotExist(self) -> type:
+        # The exception can't be created at initialization time since the
+        # related model might not be resolved yet; `self.field.model` might
+        # still be a string model reference.
+        return type(
+            "RelatedObjectDoesNotExist",
+            (self.field.remote_field.model.DoesNotExist, AttributeError),
+            {
+                "__module__": self.field.model.__module__,
+                "__qualname__": f"{self.field.model.__qualname__}.{self.field.name}.RelatedObjectDoesNotExist",
+            },
+        )
+
+    def is_cached(self, instance: Any) -> bool:
+        return self.field.is_cached(instance)
+
+    def get_queryset(self) -> QuerySet:
+        qs = self.field.remote_field.model._model_meta.base_queryset
+        return qs.all()
+
+    def get_prefetch_queryset(
+        self, instances: list[Any], queryset: QuerySet | None = None
+    ) -> tuple[QuerySet, Any, Any, bool, str, bool]:
+        if queryset is None:
+            queryset = self.get_queryset()
+
+        rel_obj_attr = self.field.get_foreign_related_value
+        instance_attr = self.field.get_local_related_value
+        instances_dict = {instance_attr(inst): inst for inst in instances}
+        related_field = self.field.foreign_related_fields[0]
+        remote_field = self.field.remote_field
+
+        # FIXME: This will need to be revisited when we introduce support for
+        # composite fields. In the meantime we take this practical approach.
+        # Refs #21410.
+        # The check for len(...) == 1 is a special case that allows the query
+        # to be join-less and smaller. Refs #21760.
+        if len(self.field.foreign_related_fields) == 1:
+            query = {
+                f"{related_field.name}__in": {
+                    instance_attr(inst)[0] for inst in instances
+                }
+            }
+        else:
+            query = {f"{self.field.related_query_name()}__in": instances}
+        queryset = queryset.filter(**query)
+
+        # Since we're going to assign directly in the cache,
+        # we must manage the reverse relation cache manually.
+        if not remote_field.multiple:
+            for rel_obj in queryset:
+                instance = instances_dict[rel_obj_attr(rel_obj)]
+                remote_field.set_cached_value(rel_obj, instance)
+        return (
+            queryset,
+            rel_obj_attr,
+            instance_attr,
+            True,
+            self.field.get_cache_name(),
+            False,
+        )
+
+    def get_object(self, instance: Any) -> Any:
+        qs = self.get_queryset()
+        # Assuming the database enforces foreign keys, this won't fail.
+        return qs.get(self.field.get_reverse_related_filter(instance))
+
+    def __get__(
+        self, instance: Any | None, cls: type | None = None
+    ) -> ForwardForeignKeyDescriptor | Any | None:
+        """
+        Get the related instance through the forward relation.
+
+        With the example above, when getting ``child.parent``:
+
+        - ``self`` is the descriptor managing the ``parent`` attribute
+        - ``instance`` is the ``child`` instance
+        - ``cls`` is the ``Child`` class (we don't need it)
+        """
+        if instance is None:
+            return self
+
+        # The related instance is loaded from the database and then cached
+        # by the field on the model instance state. It can also be pre-cached
+        # by the reverse accessor.
+        try:
+            rel_obj = self.field.get_cached_value(instance)
+        except KeyError:
+            has_value = None not in self.field.get_local_related_value(instance)
+            rel_obj = None
+
+            if rel_obj is None and has_value:
+                rel_obj = self.get_object(instance)
+                remote_field = self.field.remote_field
+                # If this is a one-to-one relation, set the reverse accessor
+                # cache on the related object to the current instance to avoid
+                # an extra SQL query if it's accessed later on.
+                if not remote_field.multiple:
+                    remote_field.set_cached_value(rel_obj, instance)
+            self.field.set_cached_value(instance, rel_obj)
+
+        if rel_obj is None and not self.field.allow_null:
+            raise self.RelatedObjectDoesNotExist(
+                f"{self.field.model.__name__} has no {self.field.name}."
+            )
+        else:
+            return rel_obj
+
+    def __set__(self, instance: Any, value: Any) -> None:
+        """
+        Set the related instance through the forward relation.
+
+        With the example above, when setting ``child.parent = parent``:
+
+        - ``self`` is the descriptor managing the ``parent`` attribute
+        - ``instance`` is the ``child`` instance
+        - ``value`` is the ``parent`` instance on the right of the equal sign
+        """
+        # If value is a LazyObject, force its evaluation. For ForeignKeyField fields,
+        # the value should only be None or a model instance, never a boolean or
+        # other type.
+        if isinstance(value, LazyObject):
+            # This forces evaluation: if it's None, value becomes None;
+            # if it's a User instance, value becomes that instance.
+            value = value if value else None
+
+        # An object must be an instance of the related class.
+        if value is not None and not isinstance(value, self.field.remote_field.model):
+            raise ValueError(
+                f'Cannot assign "{value!r}": "{instance.model_options.object_name}.{self.field.name}" must be a "{self.field.remote_field.model.model_options.object_name}" instance.'
+            )
+        remote_field = self.field.remote_field
+        # If we're setting the value of a OneToOneField to None, we need to clear
+        # out the cache on any old related object. Otherwise, deleting the
+        # previously-related object will also cause this object to be deleted,
+        # which is wrong.
+        if value is None:
+            # Look up the previously-related object, which may still be available
+            # since we've not yet cleared out the related field.
+            # Use the cache directly, instead of the accessor; if we haven't
+            # populated the cache, then we don't care - we're only accessing
+            # the object to invalidate the accessor cache, so there's no
+            # need to populate the cache just to expire it again.
+            related = self.field.get_cached_value(instance, default=None)
+
+            # If we've got an old related object, we need to clear out its
+            # cache. This cache also might not exist if the related object
+            # hasn't been accessed yet.
+            if related is not None:
+                remote_field.set_cached_value(related, None)
+
+            for lh_field, rh_field in self.field.related_fields:
+                setattr(instance, lh_field.attname, None)
+
+        # Set the values of the related field.
+        else:
+            for lh_field, rh_field in self.field.related_fields:
+                setattr(instance, lh_field.attname, getattr(value, rh_field.attname))
+
+        # Set the related instance cache used by __get__ to avoid an SQL query
+        # when accessing the attribute we just set.
+        self.field.set_cached_value(instance, value)
+
+        # If this is a one-to-one relation, set the reverse accessor cache on
+        # the related object to the current instance to avoid an extra SQL
+        # query if it's accessed later on.
+        if value is not None and not remote_field.multiple:
+            remote_field.set_cached_value(value, instance)
+
+    def __reduce__(self) -> tuple[Any, tuple[Any, str]]:
+        """
+        Pickling should return the instance attached by self.field on the
+        model, not a new copy of that descriptor. Use getattr() to retrieve
+        the instance directly from the model.
+        """
+        return getattr, (self.field.model, self.field.name)
+
+
+class ForwardManyToManyDescriptor:
+    """
+    Accessor to the related objects manager on the forward side of a
+    many-to-many relation.
+
+    In the example::
+
+        class Pizza(Model):
+            toppings: ManyToManyField[Topping] = ManyToManyField(Topping, through=PizzaTopping)
+
+    ``Pizza.toppings`` is a ``ForwardManyToManyDescriptor`` instance.
+    """
+
+    def __init__(self, rel: Any) -> None:
+        self.rel = rel
+        self.field = rel.field
+
+    def __get__(
+        self, instance: Any | None, cls: type | None = None
+    ) -> ForwardManyToManyDescriptor | Any:
+        """Get the related manager when the descriptor is accessed."""
+        if instance is None:
+            return self
+        return ManyToManyManager(
+            instance=instance,
+            field=self.rel.field,
+            through=self.rel.through,
+            related_model=self.rel.model,
+            is_reverse=False,
+            symmetrical=self.rel.symmetrical,
+        )
+
+    def __set__(self, instance: Any, value: Any) -> None:
+        """Prevent direct assignment to the relation."""
+        raise TypeError(
+            f"Direct assignment to the forward side of a many-to-many set is prohibited. Use {self.field.name}.set() instead.",
+        )
+
+    @property
+    def through(self) -> Any:
+        # through is provided so that you have easy access to the through
+        # model (Book.authors.through) for inlines, etc. This is done as
+        # a property to ensure that the fully resolved value is returned.
+        return self.rel.through

plain/postgres/fields/related_lookups.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from plain.postgres.lookups import (
+    Exact,
+    GreaterThan,
+    GreaterThanOrEqual,
+    In,
+    IsNull,
+    LessThan,
+    LessThanOrEqual,
+    Lookup,
+)
+
+if TYPE_CHECKING:
+    from plain.postgres.connection import DatabaseConnection
+    from plain.postgres.sql.compiler import SQLCompiler
+
+
+class MultiColSource:
+    contains_aggregate = False
+    contains_over_clause = False
+
+    def __init__(self, alias: str, targets: Any, sources: Any, field: Any) -> None:
+        self.targets, self.sources, self.field, self.alias = (
+            targets,
+            sources,
+            field,
+            alias,
+        )
+        self.output_field = self.field
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.alias}, {self.field})"
+
+    def relabeled_clone(self, relabels: dict[str, str]) -> MultiColSource:
+        return self.__class__(
+            relabels.get(self.alias, self.alias), self.targets, self.sources, self.field
+        )
+
+    def get_lookup(self, lookup: str) -> type[Lookup] | None:
+        return self.output_field.get_lookup(lookup)
+
+    def resolve_expression(self, *args: Any, **kwargs: Any) -> MultiColSource:
+        return self
+
+
+def get_normalized_value(value: Any, lhs: Any) -> tuple[Any, ...]:
+    from plain.postgres import Model
+    from plain.postgres.fields.related import RelatedField
+
+    if isinstance(value, Model):
+        if value.id is None:
+            raise ValueError("Model instances passed to related filters must be saved.")
+        value_list = []
+        sources = lhs.output_field.path_infos[-1].target_fields
+        for source in sources:
+            while not isinstance(value, source.model) and isinstance(
+                source, RelatedField
+            ):
+                source = source.remote_field.model._model_meta.get_field(
+                    source.remote_field.field_name
+                )
+            try:
+                value_list.append(getattr(value, source.attname))
+            except AttributeError:
+                # A case like Restaurant.query.filter(place=restaurant_instance),
+                # where place is a OneToOneField and the primary key of Restaurant.
+                return (value.id,)
+        return tuple(value_list)
+    if not isinstance(value, tuple):
+        return (value,)
+    return value
+
+
+class RelatedIn(In):
+    def get_prep_lookup(self) -> list[Any]:
+        if not isinstance(self.lhs, MultiColSource):
+            if self.rhs_is_direct_value():
+                # If we get here, we are dealing with single-column relations.
+                self.rhs = [get_normalized_value(val, self.lhs)[0] for val in self.rhs]
+                # We need to run the related field's get_prep_value(). Consider
+                # case ForeignKeyField to IntegerField given value 'abc'. The
+                # ForeignKeyField itself doesn't have validation for non-integers,
+                # so we must run validation using the target field.
+                if hasattr(self.lhs.output_field, "path_infos"):
+                    # Run the target field's get_prep_value. We can safely
+                    # assume there is only one as we don't get to the direct
+                    # value branch otherwise.
+                    target_field = self.lhs.output_field.path_infos[-1].target_fields[
+                        -1
+                    ]
+                    self.rhs = [target_field.get_prep_value(v) for v in self.rhs]
+            elif not getattr(self.rhs, "has_select_fields", True) and not getattr(
+                self.lhs.field.target_field, "primary_key", False
+            ):
+                if (
+                    getattr(self.lhs.output_field, "primary_key", False)
+                    and self.lhs.output_field.model == self.rhs.model
+                ):
+                    # A case like
+                    # Restaurant.query.filter(place__in=restaurant_qs), where
+                    # place is a OneToOneField and the primary key of
+                    # Restaurant.
+                    target_field = self.lhs.field.name
+                else:
+                    target_field = self.lhs.field.target_field.name
+                self.rhs.set_values([target_field])
+        return super().get_prep_lookup()
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        if isinstance(self.lhs, MultiColSource):
+            # For multicolumn lookups we need to build a multicolumn where clause.
+            # This clause is either a SubqueryConstraint (for values that need
+            # to be compiled to SQL) or an OR-combined list of
+            # (col1 = val1 AND col2 = val2 AND ...) clauses.
+            from plain.postgres.sql.where import (
+                AND,
+                OR,
+                SubqueryConstraint,
+                WhereNode,
+            )
+
+            root_constraint = WhereNode(connector=OR)
+            if self.rhs_is_direct_value():
+                values = [get_normalized_value(value, self.lhs) for value in self.rhs]
+                for value in values:
+                    value_constraint = WhereNode()
+                    for source, target, val in zip(
+                        self.lhs.sources, self.lhs.targets, value
+                    ):
+                        lookup_class = target.get_lookup("exact")
+                        lookup = lookup_class(
+                            target.get_col(self.lhs.alias, source), val
+                        )
+                        value_constraint.add(lookup, AND)
+                    root_constraint.add(value_constraint, OR)
+            else:
+                root_constraint.add(
+                    SubqueryConstraint(
+                        self.lhs.alias,
+                        [target.column for target in self.lhs.targets],
+                        [source.name for source in self.lhs.sources],
+                        self.rhs,
+                    ),
+                    AND,
+                )
+            return root_constraint.as_sql(compiler, connection)
+        return super().as_sql(compiler, connection)
+
+
+class RelatedLookupMixin(Lookup):
+    # Type hints for attributes/methods expected from Lookup base class
+    lhs: Any
+    rhs: Any
+    prepare_rhs: bool
+    lookup_name: str | None
+
+    def get_prep_lookup(self) -> Any:
+        if not isinstance(self.lhs, MultiColSource) and not hasattr(
+            self.rhs, "resolve_expression"
+        ):
+            # If we get here, we are dealing with single-column relations.
+            self.rhs = get_normalized_value(self.rhs, self.lhs)[0]
+            # We need to run the related field's get_prep_value(). Consider case
+            # ForeignKeyField to IntegerField given value 'abc'. The ForeignKeyField itself
+            # doesn't have validation for non-integers, so we must run validation
+            # using the target field.
+            if self.prepare_rhs and hasattr(self.lhs.output_field, "path_infos"):
+                # Get the target field. We can safely assume there is only one
+                # as we don't get to the direct value branch otherwise.
+                target_field = self.lhs.output_field.path_infos[-1].target_fields[-1]
+                self.rhs = target_field.get_prep_value(self.rhs)
+
+        return super().get_prep_lookup()
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        if isinstance(self.lhs, MultiColSource):
+            assert self.rhs_is_direct_value()
+            self.rhs = get_normalized_value(self.rhs, self.lhs)
+            from plain.postgres.sql.where import AND, WhereNode
+
+            root_constraint = WhereNode()
+            for target, source, val in zip(
+                self.lhs.targets, self.lhs.sources, self.rhs
+            ):
+                lookup_class = target.get_lookup(self.lookup_name)
+                root_constraint.add(
+                    lookup_class(target.get_col(self.lhs.alias, source), val), AND
+                )
+            sql, params = root_constraint.as_sql(compiler, connection)
+            return sql, list(params)
+        sql, params = super().as_sql(compiler, connection)
+        return sql, list(params)
+
+
+class RelatedExact(RelatedLookupMixin, Exact):
+    pass
+
+
+class RelatedLessThan(RelatedLookupMixin, LessThan):
+    pass
+
+
+class RelatedGreaterThan(RelatedLookupMixin, GreaterThan):
+    pass
+
+
+class RelatedGreaterThanOrEqual(RelatedLookupMixin, GreaterThanOrEqual):
+    pass
+
+
+class RelatedLessThanOrEqual(RelatedLookupMixin, LessThanOrEqual):
+    pass
+
+
+class RelatedIsNull(RelatedLookupMixin, IsNull):
+    pass