plain.postgres 0.84.0__py3-none-any.whl

plain/postgres/fields/reverse_descriptors.py

@@ -0,0 +1,229 @@
+"""
+Reverse relation descriptors for explicit reverse relation declarations.
+
+This module contains descriptors for the reverse side of ForeignKeyField and
+ManyToManyField relations, allowing explicit declaration of reverse accessors
+without relying on automatic related_name generation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from plain.postgres import Model
+    from plain.postgres.fields.related_managers import BaseRelatedManager
+    from plain.postgres.query import QuerySet
+
+T = TypeVar("T", bound="Model")
+# Default to QuerySet[Any] so users can omit the second type parameter
+QS = TypeVar("QS", bound="QuerySet[Any]", default="QuerySet[Any]")
+
+
+class BaseReverseDescriptor(Generic[T, QS]):
+    """
+    Base class for reverse relation descriptors.
+
+    Provides common functionality for ReverseForeignKey and ReverseManyToMany
+    descriptors, including field resolution, validation, and the descriptor protocol.
+    """
+
+    def __init__(self, to: str | type[T], field: str):
+        self.to = to
+        self.field_name = field
+        self.name: str | None = None
+        self.model: type[Model] | None = None
+        self._resolved_model: type[T] | None = None
+        self._resolved_field: Any = None
+
+    def contribute_to_class(self, cls: type[Model], name: str) -> None:
+        """
+        Register this reverse relation with the model class.
+
+        Called by the model metaclass when the model is created.
+        """
+        self.name = name
+        self.model = cls
+
+        # Set the descriptor on the class
+        setattr(cls, name, self)
+
+        # Register this as a related object for prefetch support
+        # We'll do this lazily when the target model is resolved
+        from plain.postgres.fields.related import lazy_related_operation
+
+        def resolve_related_field(
+            parent_model: type[Model], related_model: type[T]
+        ) -> None:
+            """Resolve the target model and field, then register."""
+            self._resolved_model = related_model
+            try:
+                self._resolved_field = related_model._model_meta.get_field(
+                    self.field_name
+                )
+            except Exception as e:
+                raise ValueError(
+                    f"Field '{self.field_name}' not found on model "
+                    f"'{related_model.__name__}' for {self._get_descriptor_type()} '{self.name}' "
+                    f"on '{cls.__name__}'. Error: {e}"
+                )
+
+            # Validate that the field is the correct type
+            self._validate_field_type(related_model)
+
+        # Use lazy operation to handle circular dependencies
+        lazy_related_operation(resolve_related_field, cls, self.to)
+
+    def __get__(
+        self, instance: Model | None, owner: type[Model]
+    ) -> BaseReverseDescriptor[T, QS] | BaseRelatedManager[T, QS]:
+        """
+        Get the related manager when accessed on an instance.
+
+        When accessed on the class, returns the descriptor.
+        When accessed on an instance, returns a manager.
+        """
+        if instance is None:
+            return self
+
+        # Ensure the related model and field are resolved
+        if self._resolved_field is None or self.model is None:
+            model_name = self.model.__name__ if self.model else "Unknown"
+            raise ValueError(
+                f"{self._get_descriptor_type()} '{self.name}' on '{model_name}' "
+                f"has not been resolved yet. The target model may not be registered."
+            )
+
+        # _resolved_model is set alongside _resolved_field in resolve_related_field
+        assert self._resolved_model is not None, "Model should be resolved with field"
+
+        # Return a manager bound to this instance
+        return self._create_manager(instance)
+
+    def __set__(self, instance: Model, value: Any) -> None:
+        """Prevent direct assignment to reverse relations."""
+        raise TypeError(
+            f"Direct assignment to the reverse side of a {self._get_field_type()} "
+            f"('{self.name}') is prohibited. Use {self.name}.set() instead."
+        )
+
+    def _get_descriptor_type(self) -> str:
+        """Return the name of this descriptor type for error messages."""
+        raise NotImplementedError("Subclasses must implement _get_descriptor_type()")
+
+    def _get_field_type(self) -> str:
+        """Return the name of the forward field type for error messages."""
+        raise NotImplementedError("Subclasses must implement _get_field_type()")
+
+    def _validate_field_type(self, related_model: type[Model]) -> None:
+        """Validate that the resolved field is the correct type."""
+        raise NotImplementedError("Subclasses must implement _validate_field_type()")
+
+    def _create_manager(self, instance: Model) -> Any:
+        """Create and return the appropriate manager for this instance."""
+        raise NotImplementedError("Subclasses must implement _create_manager()")
+
+
+class ReverseForeignKey(BaseReverseDescriptor[T, QS]):
+    """
+    Descriptor for the reverse side of a ForeignKeyField relation.
+
+    Provides access to the related instances on the "one" side of a one-to-many
+    relationship.
+
+    Example:
+        class Parent(Model):
+            # Basic usage (uses default QuerySet[Child])
+            children: ReverseForeignKey[Child, QuerySet[Child]] = ReverseForeignKey(to="Child", field="parent")
+
+            # With custom QuerySet
+            children: ReverseForeignKey[Child, ChildQuerySet] = ReverseForeignKey(to="Child", field="parent")
+
+        class Child(Model):
+            parent: Parent = ForeignKeyField(Parent, on_delete=models.CASCADE)
+
+    Args:
+        to: The related model (string name or model class)
+        field: The field name on the related model that points back to this model
+    """
+
+    def _get_descriptor_type(self) -> str:
+        return "ReverseForeignKey"
+
+    def _get_field_type(self) -> str:
+        return "ForeignKey"
+
+    def _validate_field_type(self, related_model: type[Model]) -> None:
+        """Validate that the field is a ForeignKey."""
+        from plain.postgres.fields.related import ForeignKeyField
+
+        if not isinstance(self._resolved_field, ForeignKeyField):
+            raise ValueError(
+                f"Field '{self.field_name}' on '{related_model.__name__}' is not a "
+                f"ForeignKey. ReverseForeignKey requires a ForeignKeyField field."
+            )
+
+    def _create_manager(self, instance: Model) -> Any:
+        """Create a ReverseForeignKeyManager for this instance."""
+        from plain.postgres.fields.related_managers import ReverseForeignKeyManager
+
+        assert self._resolved_model is not None
+        return ReverseForeignKeyManager(
+            instance=instance,
+            field=self._resolved_field,
+            related_model=self._resolved_model,
+        )
+
+
+class ReverseManyToMany(BaseReverseDescriptor[T, QS]):
+    """
+    Descriptor for the reverse side of a ManyToManyField relation.
+
+    Provides access to the related instances on the reverse side of a many-to-many
+    relationship.
+
+    Example:
+        class Feature(Model):
+            # Basic usage (uses default QuerySet[Car])
+            cars: ReverseManyToMany[Car, QuerySet[Car]] = ReverseManyToMany(to="Car", field="features")
+
+            # With custom QuerySet
+            cars: ReverseManyToMany[Car, CarQuerySet] = ReverseManyToMany(to="Car", field="features")
+
+        class Car(Model):
+            features: ManyToManyField[Feature] = ManyToManyField(Feature, through=CarFeature)
+
+    Args:
+        to: The related model (string name or model class)
+        field: The field name on the related model that points to this model
+    """
+
+    def _get_descriptor_type(self) -> str:
+        return "ReverseManyToMany"
+
+    def _get_field_type(self) -> str:
+        return "ManyToManyField"
+
+    def _validate_field_type(self, related_model: type[Model]) -> None:
+        """Validate that the field is a ManyToManyField."""
+        from plain.postgres.fields.related import ManyToManyField
+
+        if not isinstance(self._resolved_field, ManyToManyField):
+            raise ValueError(
+                f"Field '{self.field_name}' on '{related_model.__name__}' is not a "
+                f"ManyToManyField. ReverseManyToMany requires a ManyToManyField."
+            )
+
+    def _create_manager(self, instance: Model) -> Any:
+        """Create a ManyToManyManager for this instance."""
+        from plain.postgres.fields.related_managers import ManyToManyManager
+
+        assert self._resolved_model is not None
+        return ManyToManyManager(
+            instance=instance,
+            field=self._resolved_field,
+            through=self._resolved_field.remote_field.through,
+            related_model=self._resolved_model,
+            is_reverse=True,
+            symmetrical=False,
+        )

plain/postgres/fields/reverse_related.py

@@ -0,0 +1,328 @@
+"""
+"Rel objects" for related fields.
+
+"Rel objects" (for lack of a better name) carry information about the relation
+modeled by a related field and provide some utility functions. They're stored
+in the ``remote_field`` attribute of the field.
+
+They also act as reverse fields for the purposes of the Meta API because
+they're the closest concept currently available.
+"""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import TYPE_CHECKING, Any
+
+from plain.postgres.exceptions import FieldError
+from plain.utils.hashable import make_hashable
+
+from . import BLANK_CHOICE_DASH
+from .mixins import FieldCacheMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from plain.postgres.base import Model
+    from plain.postgres.deletion import Collector
+    from plain.postgres.fields import Field
+    from plain.postgres.fields.related import (
+        ForeignKeyField,
+        ManyToManyField,
+        RelatedField,
+    )
+    from plain.postgres.lookups import Lookup
+    from plain.postgres.query_utils import PathInfo, Q
+
+    # Type alias for on_delete callbacks
+    OnDeleteCallback = Callable[[Collector, Any, Any], None]
+
+
+class ForeignObjectRel(FieldCacheMixin):
+    """
+    Used by ForeignKeyField to store information about the relation.
+
+    ``_model_meta.get_fields()`` returns this class to provide access to the field
+    flags for the reverse relation.
+    """
+
+    # Field flags
+    auto_created = True
+    concrete = False
+
+    # Reverse relations are always nullable (Plain can't enforce that a
+    # foreign key on the related model points to this model).
+    allow_null = True
+    empty_strings_allowed = False
+
+    # Type annotations for instance attributes
+    model: type[Model]
+    field: RelatedField
+    on_delete: OnDeleteCallback | None
+    limit_choices_to: dict[str, Any] | Q
+
+    def __init__(
+        self,
+        field: RelatedField,
+        to: str | type[Model],
+        related_query_name: str | None = None,
+        limit_choices_to: dict[str, Any] | Q | None = None,
+        on_delete: OnDeleteCallback | None = None,
+    ):
+        self.field = field  # type: ignore[misc]
+        # Initially may be a string, gets resolved to type[Model] by lazy_related_operation
+        # (see related.py:250 where field.remote_field.model is overwritten)
+        self.model = to  # type: ignore[assignment]
+        self.related_query_name = related_query_name
+        self.limit_choices_to = {} if limit_choices_to is None else limit_choices_to
+        self.on_delete = on_delete
+
+        self.symmetrical = False
+        self.multiple = True
+
+    # Some of the following cached_properties can't be initialized in
+    # __init__ as the field doesn't have its model yet. Calling these methods
+    # before field.contribute_to_class() has been called will result in
+    # AttributeError
+    @cached_property
+    def name(self) -> str:
+        return self.field.related_query_name()
+
+    @property
+    def remote_field(self) -> RelatedField:
+        return self.field
+
+    @property
+    def target_field(self) -> Field:
+        """
+        When filtering against this relation, return the field on the remote
+        model against which the filtering should happen.
+        """
+        target_fields = self.path_infos[-1].target_fields
+        if len(target_fields) > 1:
+            raise FieldError("Can't use target_field for multicolumn relations.")
+        return target_fields[0]
+
+    @cached_property
+    def related_model(self) -> type[Model]:
+        if not self.field.model:
+            raise AttributeError(
+                "This property can't be accessed before self.field.contribute_to_class "
+                "has been called."
+            )
+        return self.field.model
+
+    def get_lookup(self, lookup_name: str) -> type[Lookup] | None:
+        return self.field.get_lookup(lookup_name)
+
+    def get_internal_type(self) -> str:
+        return self.field.get_internal_type()
+
+    @property
+    def db_type(self) -> str | None:
+        return self.field.db_type
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__}: {self.related_model.model_options.package_label}.{self.related_model.model_options.model_name}>"
+
+    @property
+    def identity(self) -> tuple[Any, ...]:
+        return (
+            self.field,
+            self.model,
+            self.related_query_name,
+            make_hashable(self.limit_choices_to),
+            self.on_delete,
+            self.symmetrical,
+            self.multiple,
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, self.__class__):
+            return NotImplemented
+        return self.identity == other.identity
+
+    def __hash__(self) -> int:
+        return hash(self.identity)
+
+    def __getstate__(self) -> dict[str, Any]:
+        state = self.__dict__.copy()
+        # Delete the path_infos cached property because it can be recalculated
+        # at first invocation after deserialization. The attribute must be
+        # removed because subclasses like ForeignKeyRel may have a PathInfo
+        # which contains an intermediate M2M table that's been dynamically
+        # created and doesn't exist in the .models module.
+        # This is a reverse relation, so there is no reverse_path_infos to
+        # delete.
+        state.pop("path_infos", None)
+        return state
+
+    def get_choices(
+        self,
+        include_blank: bool = True,
+        blank_choice: list[tuple[str, str]] = BLANK_CHOICE_DASH,
+        limit_choices_to: Any = None,
+        ordering: tuple[str, ...] = (),
+    ) -> list[tuple[Any, str]]:
+        """
+        Return choices with a default blank choices included, for use
+        as <select> choices for this field.
+
+        Analog of plain.postgres.fields.Field.get_choices(), provided
+        initially for utilization by RelatedFieldListFilter.
+        """
+        limit_choices_to = limit_choices_to or self.limit_choices_to
+        qs = self.related_model.query.complex_filter(limit_choices_to)
+        if ordering:
+            qs = qs.order_by(*ordering)
+        return (blank_choice if include_blank else []) + [(x.id, str(x)) for x in qs]
+
+    def get_joining_columns(self) -> tuple[tuple[str, str], ...]:
+        return self.field.get_reverse_joining_columns()
+
+    def set_field_name(self) -> None:
+        """
+        Set the related field's name, this is not available until later stages
+        of app loading, so set_field_name is called from
+        set_attributes_from_rel()
+        """
+        # By default foreign object doesn't relate to any remote field (for
+        # example custom multicolumn joins currently have no remote field).
+        self.field_name = None
+
+    def get_path_info(self, filtered_relation: Any = None) -> list[PathInfo]:
+        if filtered_relation:
+            return self.field.get_reverse_path_info(filtered_relation)
+        else:
+            return self.field.reverse_path_infos
+
+    @cached_property
+    def path_infos(self) -> list[PathInfo]:
+        return self.get_path_info()
+
+    def get_cache_name(self) -> str:
+        """
+        Return the name of the cache key to use for storing an instance of the
+        forward model on the reverse model.
+
+        Uses the related_query_name for caching, which provides a stable name
+        for prefetch_related operations.
+        """
+        return self.field.related_query_name()
+
+
+class ForeignKeyRel(ForeignObjectRel):
+    """
+    Used by the ForeignKeyField field to store information about the relation.
+
+    ``_model_meta.get_fields()`` returns this class to provide access to the
+    reverse relation. Use ``isinstance(rel, ForeignKeyRel)`` to identify
+    one-to-many reverse relations.
+    """
+
+    # Type annotations for instance attributes
+    field: ForeignKeyField
+
+    def __init__(
+        self,
+        field: ForeignKeyField,
+        to: str | type[Model],
+        related_query_name: str | None = None,
+        limit_choices_to: dict[str, Any] | Q | None = None,
+        on_delete: OnDeleteCallback | None = None,
+    ):
+        super().__init__(
+            field,
+            to,
+            related_query_name=related_query_name,
+            limit_choices_to=limit_choices_to,
+            on_delete=on_delete,
+        )
+
+        self.field_name = "id"
+
+    def __getstate__(self) -> dict[str, Any]:
+        state = super().__getstate__()
+        state.pop("related_model", None)
+        return state
+
+    @property
+    def identity(self) -> tuple[Any, ...]:
+        return super().identity + (self.field_name,)
+
+    def get_related_field(self) -> Field:
+        """
+        Return the Field in the 'to' object to which this relationship is tied.
+        """
+        return self.model._model_meta.get_forward_field("id")
+
+    def set_field_name(self) -> None:
+        pass
+
+
+class ManyToManyRel(ForeignObjectRel):
+    """
+    Used by ManyToManyField to store information about the relation.
+
+    ``_model_meta.get_fields()`` returns this class to provide access to the field
+    flags for the reverse relation.
+    """
+
+    # Type annotations for instance attributes
+    field: ManyToManyField
+    through: type[Model]
+    through_fields: tuple[str, str] | None
+
+    def __init__(
+        self,
+        field: ManyToManyField,
+        to: str | type[Model],
+        *,
+        through: str | type[Model],
+        through_fields: tuple[str, str] | None = None,
+        related_query_name: str | None = None,
+        limit_choices_to: dict[str, Any] | Q | None = None,
+        symmetrical: bool = True,
+    ):
+        super().__init__(
+            field,
+            to,
+            related_query_name=related_query_name,
+            limit_choices_to=limit_choices_to,
+        )
+
+        # Initially may be a string, gets resolved to type[Model] by lazy_related_operation
+        # (see related.py:1143 where field.remote_field.through is overwritten)
+        self.through = through  # type: ignore[assignment]
+        self.through_fields = through_fields
+
+        self.symmetrical = symmetrical
+        self.db_constraint = True
+
+    @property
+    def identity(self) -> tuple[Any, ...]:
+        return super().identity + (
+            self.through,
+            make_hashable(self.through_fields),
+            self.db_constraint,
+        )
+
+    def get_related_field(self) -> Field:
+        """
+        Return the field in the 'to' object to which this relationship is tied.
+        Provided for symmetry with ForeignKeyRel.
+        """
+        from plain.postgres.fields.related import ForeignKeyField
+
+        meta = self.through._model_meta
+        if self.through_fields:
+            field = meta.get_forward_field(self.through_fields[0])
+        else:
+            for field in meta.fields:
+                rel = getattr(field, "remote_field", None)
+                if rel and rel.model == self.model:
+                    break
+
+        if not isinstance(field, ForeignKeyField):
+            raise ValueError(f"Expected ForeignKeyField, got {type(field)}")
+        return field.foreign_related_fields[0]

plain/postgres/fields/timezones.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import zoneinfo
+from functools import cache
+from typing import TYPE_CHECKING, Any
+
+from plain import exceptions
+
+from . import Field
+
+if TYPE_CHECKING:
+    from plain.postgres.base import Model
+
+
+@cache
+def _get_canonical_timezones() -> frozenset[str]:
+    """
+    Get canonical IANA timezone names, excluding deprecated legacy aliases.
+
+    Filters out legacy timezone names like US/Central, Canada/Eastern, etc.
+    that are backward compatibility aliases. These legacy names can cause
+    issues with databases like PostgreSQL that only recognize canonical names.
+    """
+    all_zones = zoneinfo.available_timezones()
+
+    # Known legacy prefixes (deprecated in favor of Area/Location format)
+    legacy_prefixes = ("US/", "Canada/", "Brazil/", "Chile/", "Mexico/")
+
+    # Obsolete timezone abbreviations
+    obsolete_zones = {
+        "EST",
+        "MST",
+        "HST",
+        "EST5EDT",
+        "CST6CDT",
+        "MST7MDT",
+        "PST8PDT",
+    }
+
+    # Filter to only canonical timezone names
+    return frozenset(
+        tz
+        for tz in all_zones
+        if not tz.startswith(legacy_prefixes) and tz not in obsolete_zones
+    )
+
+
+class TimeZoneField(Field[zoneinfo.ZoneInfo]):
+    """
+    A model field that stores timezone names as strings but provides ZoneInfo objects.
+
+    Similar to DateField which stores dates but provides datetime.date objects,
+    this field stores timezone strings (e.g., "America/Chicago") but provides
+    zoneinfo.ZoneInfo objects when accessed.
+    """
+
+    description = "A timezone (stored as string, accessed as ZoneInfo)"
+
+    # Mapping of legacy timezone names to canonical IANA names
+    # Based on IANA timezone database backward compatibility file
+    LEGACY_TO_CANONICAL = {
+        "US/Alaska": "America/Anchorage",
+        "US/Aleutian": "America/Adak",
+        "US/Arizona": "America/Phoenix",
+        "US/Central": "America/Chicago",
+        "US/East-Indiana": "America/Indiana/Indianapolis",
+        "US/Eastern": "America/New_York",
+        "US/Hawaii": "Pacific/Honolulu",
+        "US/Indiana-Starke": "America/Indiana/Knox",
+        "US/Michigan": "America/Detroit",
+        "US/Mountain": "America/Denver",
+        "US/Pacific": "America/Los_Angeles",
+        "US/Samoa": "Pacific/Pago_Pago",
+    }
+
+    def __init__(self, **kwargs: Any):
+        if "choices" in kwargs:
+            raise TypeError("TimeZoneField does not accept custom choices.")
+        kwargs.setdefault("max_length", 100)
+        kwargs["choices"] = self._get_timezone_choices()
+        super().__init__(**kwargs)
+
+    def deconstruct(self) -> tuple[str | None, str, list[Any], dict[str, Any]]:
+        name, path, args, kwargs = super().deconstruct()
+        # Don't serialize choices - they're computed dynamically from system tzdata
+        kwargs.pop("choices", None)
+        return name, path, args, kwargs
+
+    def _get_timezone_choices(self) -> list[tuple[str, str]]:
+        """Get timezone choices for form widgets."""
+        zones = [(tz, tz) for tz in _get_canonical_timezones()]
+        zones.sort(key=lambda x: x[1])
+        return [("", "---------")] + zones
+
+    def get_internal_type(self) -> str:
+        return "CharField"
+
+    def to_python(self, value: Any) -> zoneinfo.ZoneInfo | None:
+        """Convert input to ZoneInfo object."""
+        if value is None or value == "":
+            return None
+        if isinstance(value, zoneinfo.ZoneInfo):
+            return value
+        try:
+            return zoneinfo.ZoneInfo(value)
+        except zoneinfo.ZoneInfoNotFoundError:
+            raise exceptions.ValidationError(
+                f"'{value}' is not a valid timezone.",
+                code="invalid",
+                params={"value": value},
+            )
+
+    def from_db_value(
+        self, value: Any, expression: Any, connection: Any
+    ) -> zoneinfo.ZoneInfo | None:
+        """Convert database value to ZoneInfo object."""
+        if value is None or value == "":
+            return None
+        # Normalize legacy timezone names
+        value = self.LEGACY_TO_CANONICAL.get(value, value)
+        return zoneinfo.ZoneInfo(value)
+
+    def get_prep_value(self, value: Any) -> str | None:
+        """Convert ZoneInfo to string for database storage."""
+        if value is None:
+            return None
+        if isinstance(value, zoneinfo.ZoneInfo):
+            value = str(value)
+        # Normalize legacy timezone names before saving
+        return self.LEGACY_TO_CANONICAL.get(value, value)
+
+    def value_to_string(self, obj: Model) -> str:
+        """Serialize value for fixtures/migrations."""
+        value = self.value_from_object(obj)
+        prep_value = self.get_prep_value(value)
+        return prep_value if prep_value is not None else ""
+
+    def validate(self, value: Any, model_instance: Model) -> None:
+        """Validate value against choices using string comparison."""
+        # Convert ZoneInfo to string for choice validation since choices are strings
+        if isinstance(value, zoneinfo.ZoneInfo):
+            value = str(value)
+        return super().validate(value, model_instance)