INTPYTHON-483 Add EmbeddedModelArrayField

Author: timgraham

.pre-commit-config.yaml

@@ -61,7 +61,10 @@ repos:
   rev: v1.1.1
   hooks:
     - id: doc8
-      args: ["--ignore=D001"]  # ignore line length
+      # D000 Invalid class attribute value for "class" directive when using
+      #      * (keyword-only parameters separator).
+      # D001 line length
+      args: ["--ignore=D000,D001"]
       stages: [manual]
 
 - repo: https://github.com/sirosen/check-jsonschema

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,46 @@
+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 "size" in kwargs:
+            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["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 some differeences, including
+        # unneeded "base_field" and "max_length" instead of "max_num".
+        return Field.formfield(
+            self,
+            **{
+                "form_class": forms.EmbeddedModelArrayField,
+                "model": self.base_field.embedded_model,
+                "max_num": 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
+
+
+class EmbeddedModelArrayField(forms.Field):
+    def __init__(self, model, *, prefix, max_num=None, extra_forms=3, **kwargs):
+        self.model = model
+        self.prefix = prefix
+        self.formset = formset_factory(
+            form=modelform_factory(model, fields="__all__"),
+            can_delete=True,
+            max_num=max_num,
+            extra=extra_forms,
+            validate_max=True,
+        )
+        kwargs["widget"] = EmbeddedModelArrayWidget()
+        super().__init__(**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 "delete" checkbox isn't part of model data and must be
+            # removed. The fallback to True skips empty forms.
+            if data.pop("DELETE", True):
+                continue
+            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}-")}
+
+
+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 []]

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,36 @@ 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_num=None, extra_forms=3, **kwargs)
+
+    .. versionadded:: 5.2.0b1
+
+    A field which maps to a list of model instances. The field will render as a
+    :class:`ModelFormSet <django.forms.models.BaseModelFormSet>`.
+
+    .. 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 formset will have so that the names don't collide with
+        fields in the main form.
+
+    .. attribute:: max_num
+
+        This is an optional argument which specifies the maximum number of
+        model instances that can be created.
+
+    .. attribute:: extra_forms
+
+        This argument specifies the number of blank forms that will be
+        rendered by the formset.
+
 ``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::
@@ -268,6 +268,33 @@ These indexes use 0-based indexing.
     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
+
+    Similar to :class:`EmbeddedModelField`, but stores a list of models of type
+    ``embedded_model`` rather than a single instance.
+
+    .. 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.
+
+.. admonition:: Migrations support is limited
+
+    As described above for :class:`EmbeddedModelField`,
+    :djadmin:`makemigrations` does not yet detect changes to embedded models.
+
 ``ObjectIdAutoField``
 ---------------------
 

docs/source/releases/5.2.x.rst

@@ -7,6 +7,12 @@ Django MongoDB Backend 5.2.x
 
 *Unreleased*
 
+New features
+------------
+
+- Added :class:`~.fields.EmbeddedModelArrayField` for storing data as an array
+  of model instances.
+
 Bug fixes
 ---------
 

docs/source/topics/embedded-models.rst

@@ -1,7 +1,8 @@
 Embedded models
 ===============
 
-Use :class:`~django_mongodb_backend.fields.EmbeddedModelField` to structure
+Use :class:`~django_mongodb_backend.fields.EmbeddedModelField` and
+:class:`~django_mongodb_backend.fields.EmbeddedModelArrayField` to structure
 your data using `embedded documents
 <https://www.mongodb.com/docs/manual/data-modeling/#embedded-data>`_.
 

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