INTPYTHON-483 Add EmbeddedModelArrayField

Author: timgraham

django_mongodb_backend/fields/__init__.py

@@ -2,12 +2,14 @@
 from .auto import ObjectIdAutoField
 from .duration import register_duration_field
 from .embedded_model import EmbeddedModelField
+from .embedded_model_array import EmbeddedModelArrayField
 from .json import register_json_field
 from .objectid import ObjectIdField
 
 __all__ = [
     "register_fields",
     "ArrayField",
+    "EmbeddedModelArrayField",
     "EmbeddedModelField",
     "ObjectIdAutoField",
     "ObjectIdField",

django_mongodb_backend/fields/embedded_model_array.py

@@ -0,0 +1,49 @@
+from django.db.models import Field
+
+from .. import forms
+from . import EmbeddedModelField
+from .array import ArrayField
+
+
+class EmbeddedModelArrayField(ArrayField):
+    def __init__(self, embedded_model, **kwargs):
+        if kwargs.get("size") is not None:
+            raise ValueError("EmbeddedModelArrayField does not support size.")
+        super().__init__(EmbeddedModelField(embedded_model), **kwargs)
+        self.embedded_model = embedded_model
+
+    def deconstruct(self):
+        name, path, args, kwargs = super().deconstruct()
+        if path == "django_mongodb_backend.fields.embedded_model_array.EmbeddedModelArrayField":
+            path = "django_mongodb_backend.fields.EmbeddedModelArrayField"
+        kwargs.update(
+            {
+                "embedded_model": self.embedded_model,
+            }
+        )
+        del kwargs["base_field"]
+        return name, path, args, kwargs
+
+    def get_db_prep_value(self, value, connection, prepared=False):
+        if isinstance(value, list | tuple):
+            # Must call get_db_prep_save() rather than get_db_prep_value()
+            # to transform model instances to dicts.
+            return [self.base_field.get_db_prep_save(i, connection) for i in value]
+        if value is not None:
+            raise TypeError(
+                f"Expected list of {self.embedded_model!r} instances, not {type(value)!r}."
+            )
+        return value
+
+    def formfield(self, **kwargs):
+        # Skip ArrayField.formfield() which has unneeded base_field.
+        return Field.formfield(
+            self,
+            **{
+                "form_class": forms.EmbeddedModelArrayField,
+                "model": self.base_field.embedded_model,
+                "max_length": self.max_size,
+                "prefix": self.name,
+                **kwargs,
+            },
+        )

django_mongodb_backend/forms/__init__.py

@@ -1,4 +1,5 @@
 from .fields import (
+    EmbeddedModelArrayField,
     EmbeddedModelField,
     ObjectIdField,
     SimpleArrayField,
@@ -7,6 +8,7 @@
 )
 
 __all__ = [
+    "EmbeddedModelArrayField",
     "EmbeddedModelField",
     "SimpleArrayField",
     "SplitArrayField",

django_mongodb_backend/forms/fields/__init__.py

@@ -1,8 +1,10 @@
 from .array import SimpleArrayField, SplitArrayField, SplitArrayWidget
 from .embedded_model import EmbeddedModelField
+from .embedded_model_array import EmbeddedModelArrayField
 from .objectid import ObjectIdField
 
 __all__ = [
+    "EmbeddedModelArrayField",
     "EmbeddedModelField",
     "SimpleArrayField",
     "SplitArrayField",

django_mongodb_backend/forms/fields/embedded_model_array.py

@@ -0,0 +1,76 @@
+from django import forms
+from django.core.exceptions import ValidationError
+from django.forms import formset_factory, model_to_dict
+from django.forms.models import modelform_factory
+from django.utils.html import format_html, format_html_join
+
+
+def models_to_dicts(models):
+    """
+    Convert initial data (which is a list of model instances or None) to a
+    list of dictionary data suitable for a formset.
+    """
+    return [model_to_dict(model) for model in models or []]
+
+
+class EmbeddedModelArrayField(forms.Field):
+    def __init__(self, model, prefix, max_length=None, *args, **kwargs):
+        self.model = model
+        self.prefix = prefix
+        self.formset = formset_factory(
+            form=modelform_factory(model, fields="__all__"),
+            can_delete=True,
+            max_num=max_length,
+            extra=3,
+            validate_max=True,
+        )
+        kwargs["widget"] = EmbeddedModelArrayWidget()
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value):
+        if not value:
+            return []
+        formset = self.formset(value, prefix=self.prefix)
+        if not formset.is_valid():
+            raise ValidationError(formset.errors + formset.non_form_errors())
+        cleaned_data = []
+        for data in formset.cleaned_data:
+            # The fallback to True skips empty forms.
+            if data.get("DELETE", True):
+                continue
+            data.pop("DELETE")  # The "delete" checkbox isn't part of model data.
+            cleaned_data.append(self.model(**data))
+        return cleaned_data
+
+    def has_changed(self, initial, data):
+        formset = self.formset(data, initial=models_to_dicts(initial), prefix=self.prefix)
+        return formset.has_changed()
+
+    def get_bound_field(self, form, field_name):
+        return EmbeddedModelArrayBoundField(form, self, field_name)
+
+
+class EmbeddedModelArrayBoundField(forms.BoundField):
+    def __init__(self, form, field, name):
+        super().__init__(form, field, name)
+        self.formset = field.formset(
+            self.data if form.is_bound else None,
+            initial=models_to_dicts(self.initial),
+            prefix=self.html_name,
+        )
+
+    def __str__(self):
+        body = format_html_join(
+            "\n", "<tbody>{}</tbody>", ((form.as_table(),) for form in self.formset)
+        )
+        return format_html("<table>\n{}\n</table>\n{}", body, self.formset.management_form)
+
+
+class EmbeddedModelArrayWidget(forms.Widget):
+    """
+    This widget extracts the data for EmbeddedModelArrayFormField's formset.
+    It is never rendered.
+    """
+
+    def value_from_datadict(self, data, files, name):
+        return {key: data[key] for key in data if key.startswith(f"{name}-")}

django_mongodb_backend/operations.py

@@ -111,6 +111,15 @@ def get_db_converters(self, expression):
             converters.append(self.convert_decimalfield_value)
         elif internal_type == "EmbeddedModelField":
             converters.append(self.convert_embeddedmodelfield_value)
+        elif internal_type == "EmbeddedModelArrayField":
+            converters.extend(
+                [
+                    self._get_arrayfield_converter(converter)
+                    for converter in self.get_db_converters(
+                        Expression(output_field=expression.output_field.base_field)
+                    )
+                ]
+            )
         elif internal_type == "JSONField":
             converters.append(self.convert_jsonfield_value)
         elif internal_type == "TimeField":

docs/source/ref/forms.rst

@@ -23,6 +23,31 @@ Some MongoDB-specific fields are available in ``django_mongodb_backend.forms``.
         in this field's subform will have so that the names don't collide with
         fields in the main form.
 
+``EmbeddedModelArrayField``
+---------------------------
+
+.. class:: EmbeddedModelArrayField(model, prefix, max_length=None, **kwargs)
+
+    .. versionadded:: 5.2.0b1
+
+    A field which maps to a model. The field will render as a
+    :class:`~django.forms.ModelFormSet`.
+
+    .. attribute:: model
+
+        This is a required argument that specifies the model class.
+
+    .. attribute:: prefix
+
+        This is a required argument that specifies the prefix that all fields
+        in this field's subform will have so that the names don't collide with
+        fields in the main form.
+
+    .. attribute:: max_length
+
+        This is an optional argument which validates that the array does not
+        exceed the stated length.
+
 ``ObjectIdField``
 -----------------
 

docs/source/ref/models/fields.rst

@@ -35,8 +35,8 @@ Some MongoDB-specific fields are available in ``django_mongodb_backend.fields``.
         :class:`~django.db.models.OneToOneField` and
         :class:`~django.db.models.ManyToManyField`) and file fields (
         :class:`~django.db.models.FileField` and
-        :class:`~django.db.models.ImageField`). :class:`EmbeddedModelField` is
-        also not (yet) supported.
+        :class:`~django.db.models.ImageField`). For
+        :class:`EmbeddedModelField`, use :class:`EmbeddedModelArrayField`.
 
         It is possible to nest array fields - you can specify an instance of
         ``ArrayField`` as the ``base_field``. For example::
@@ -178,7 +178,7 @@ Index transforms
 Index transforms index into the array. Any non-negative integer can be used.
 There are no errors if it exceeds the :attr:`max_size <ArrayField.max_size>` of
 the array. The lookups available after the transform are those from the
-:attr:`base_field <ArrayField.base_field>`. For example:
+:attr:`~ArrayField.base_field`. For example:
 
 .. code-block:: pycon
 
@@ -224,7 +224,7 @@ These indexes use 0-based indexing.
 
 .. class:: EmbeddedModelField(embedded_model, **kwargs)
 
-Stores a model of type ``embedded_model``.
+    Stores a model of type ``embedded_model``.
 
     .. attribute:: embedded_model
 
@@ -268,6 +268,27 @@ See :doc:`/topics/embedded-models` for more details and examples.
     created these models and then added an indexed field to ``Address``,
     the index created in the nested ``Book`` embed is not created.
 
+``EmbeddedModelArrayField``
+---------------------------
+
+.. class:: EmbeddedModelArrayField(embedded_model, max_size=None, **kwargs)
+
+    .. versionadded:: 5.2.0b1
+
+    Stores a list of models of type ``embedded_model``.
+
+    .. attribute:: embedded_model
+
+        This is a required argument, similar to
+        :attr:`EmbeddedModelField.embedded_model`.
+
+    .. attribute:: max_size
+
+        This is an optional argument.
+
+        If passed, the array will have a maximum size as specified, validated
+        by forms and model validation, but not enforced by the database.
+
 ``ObjectIdAutoField``
 ---------------------
 

tests/model_fields_/models.py

@@ -2,7 +2,12 @@
 
 from django.db import models
 
-from django_mongodb_backend.fields import ArrayField, EmbeddedModelField, ObjectIdField
+from django_mongodb_backend.fields import (
+    ArrayField,
+    EmbeddedModelArrayField,
+    EmbeddedModelField,
+    ObjectIdField,
+)
 from django_mongodb_backend.models import EmbeddedModel
 
 
@@ -143,3 +148,20 @@ class Library(models.Model):
 
     def __str__(self):
         return self.name
+
+
+# EmbeddedModelArrayField
+class Review(EmbeddedModel):
+    title = models.CharField(max_length=255)
+    rating = models.DecimalField(max_digits=6, decimal_places=1)
+
+    def __str__(self):
+        return self.title
+
+
+class Movie(models.Model):
+    title = models.CharField(max_length=255)
+    reviews = EmbeddedModelArrayField(Review, null=True)
+
+    def __str__(self):
+        return self.title