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 differences, including
+        # unneeded "base_field", and "max_length" instead of "max_num".
+        return Field.formfield(
+            self,
+            **{
+                "form_class": forms.EmbeddedModelArrayField,
+                "model": self.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,80 @@
+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_override or 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):
+        # Nested embedded model form fields need a double prefix.
+        # HACK: Setting self.prefix_override makes it available in clean()
+        # which doesn't have access to the form.
+        self.prefix_override = f"{form.prefix}-{self.prefix}" if form.prefix else None
+        return EmbeddedModelArrayBoundField(form, self, field_name, self.prefix_override)
+
+
+class EmbeddedModelArrayBoundField(forms.BoundField):
+    def __init__(self, form, field, name, prefix_override):
+        super().__init__(form, field, name)
+        self.formset = field.formset(
+            self.data if form.is_bound else None,
+            initial=models_to_dicts(self.initial),
+            prefix=prefix_override if prefix_override else 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):
+    """
+    Extract the data for EmbeddedModelArrayFormField's formset.
+    This widget is never rendered.
+    """
+
+    def value_from_datadict(self, data, files, name):
+        return {field: value for field, value in data.items() if field.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/make.bat

@@ -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/forms.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::
@@ -256,7 +256,8 @@ These indexes use 0-based indexing.
             class Book(models.Model):
                 author = EmbeddedModelField(Author)
 
-    See :doc:`/topics/embedded-models` for more details and examples.
+    See :ref:`the embedded model topic guide <embedded-model-field-example>`
+    for more details and examples.
 
 .. admonition:: Migrations support is limited
 
@@ -268,6 +269,36 @@ 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 that works just like
+        :attr:`EmbeddedModelField.embedded_model`.
+
+    .. attribute:: max_size
+
+        This is an optional argument.
+
+        If passed, the list will have a maximum size as specified, validated
+        by forms and model validation, but not enforced by the database.
+
+    See :ref:`the embedded model topic guide
+    <embedded-model-array-field-example>` for more details and examples.
+
+.. admonition:: Migrations support is limited
+
+    As described above for :class:`EmbeddedModelField`,
+    :djadmin:`makemigrations` does not yet detect changes to embedded models.
+
 ``ObjectIdAutoField``
 ---------------------