1"""
2Helper functions for creating Form classes from Plain models
3and database field objects.
4"""
5
6from __future__ import annotations
7
8from itertools import chain
9from typing import TYPE_CHECKING, Any, cast
10
11from plain.exceptions import (
12 NON_FIELD_ERRORS,
13 ImproperlyConfigured,
14 ValidationError,
15)
16from plain.forms import fields
17from plain.forms.fields import ChoiceField, Field
18from plain.forms.forms import BaseForm, DeclarativeFieldsMetaclass
19from plain.models.exceptions import FieldError
20
21if TYPE_CHECKING:
22 from plain.models.fields import Field as ModelField
23
24__all__ = (
25 "ModelForm",
26 "BaseModelForm",
27 "model_to_dict",
28 "fields_for_model",
29 "ModelChoiceField",
30 "ModelMultipleChoiceField",
31)
32
33
34def construct_instance(
35 form: BaseModelForm,
36 instance: Any,
37 fields: list[str] | tuple[str, ...] | None = None,
38) -> Any:
39 """
40 Construct and return a model instance from the bound ``form``'s
41 ``cleaned_data``, but do not save the returned instance to the database.
42 """
43 from plain import models
44
45 meta = instance._model_meta
46
47 cleaned_data = form.cleaned_data
48 file_field_list = []
49 for f in meta.fields:
50 if isinstance(f, models.PrimaryKeyField) or f.name not in cleaned_data:
51 continue
52 if fields is not None and f.name not in fields:
53 continue
54 # Leave defaults for fields that aren't in POST data, except for
55 # checkbox inputs because they don't appear in POST data if not checked.
56 if (
57 f.has_default()
58 and form.add_prefix(f.name) not in form.data
59 and form.add_prefix(f.name) not in form.files
60 # and form[f.name].field.widget.value_omitted_from_data(
61 # form.data, form.files, form.add_prefix(f.name)
62 # )
63 and cleaned_data.get(f.name) in form[f.name].field.empty_values
64 ):
65 continue
66
67 f.save_form_data(instance, cleaned_data[f.name])
68
69 for f in file_field_list:
70 f.save_form_data(instance, cleaned_data[f.name])
71
72 return instance
73
74
75# ModelForms #################################################################
76
77
78def model_to_dict(
79 instance: Any, fields: list[str] | tuple[str, ...] | None = None
80) -> dict[str, Any]:
81 """
82 Return a dict containing the data in ``instance`` suitable for passing as
83 a Form's ``initial`` keyword argument.
84
85 ``fields`` is an optional list of field names. If provided, return only the
86 named.
87 """
88 meta = instance._model_meta
89 data = {}
90 for f in chain(meta.concrete_fields, meta.many_to_many):
91 if fields is not None and f.name not in fields:
92 continue
93 data[f.name] = f.value_from_object(instance)
94 return data
95
96
97def fields_for_model(
98 model: type[Any],
99 fields: list[str] | tuple[str, ...] | None = None,
100 formfield_callback: Any = None,
101 error_messages: dict[str, Any] | None = None,
102 field_classes: dict[str, type[Field]] | None = None,
103) -> dict[str, Field | None]:
104 """
105 Return a dictionary containing form fields for the given model.
106
107 ``fields`` is an optional list of field names. If provided, return only the
108 named fields.
109
110 ``formfield_callback`` is a callable that takes a model field and returns
111 a form field.
112
113 ``error_messages`` is a dictionary of model field names mapped to a
114 dictionary of error messages.
115
116 ``field_classes`` is a dictionary of model field names mapped to a form
117 field class.
118 """
119 field_dict = {}
120 ignored = []
121 meta = model._model_meta
122
123 for f in sorted(chain(meta.concrete_fields, meta.many_to_many)):
124 if fields is not None and f.name not in fields:
125 continue
126
127 kwargs = {}
128 if error_messages and f.name in error_messages:
129 kwargs["error_messages"] = error_messages[f.name]
130 if field_classes and f.name in field_classes:
131 kwargs["form_class"] = field_classes[f.name]
132
133 if formfield_callback is None:
134 formfield = modelfield_to_formfield(f, **kwargs)
135 elif not callable(formfield_callback):
136 raise TypeError("formfield_callback must be a function or callable")
137 else:
138 formfield = formfield_callback(f, **kwargs)
139
140 if formfield:
141 field_dict[f.name] = formfield
142 else:
143 ignored.append(f.name)
144 if fields:
145 field_dict = {f: field_dict.get(f) for f in fields if f not in ignored}
146 return field_dict
147
148
149class ModelFormOptions:
150 def __init__(self, options: Any = None) -> None:
151 self.model: type[Any] | None = getattr(options, "model", None)
152 self.fields: list[str] | tuple[str, ...] | None = getattr(
153 options, "fields", None
154 )
155 self.error_messages: dict[str, Any] | None = getattr(
156 options, "error_messages", None
157 )
158 self.field_classes: dict[str, type[Field]] | None = getattr(
159 options, "field_classes", None
160 )
161 self.formfield_callback: Any = getattr(options, "formfield_callback", None)
162
163
164class ModelFormMetaclass(DeclarativeFieldsMetaclass):
165 def __new__(
166 mcs: type[ModelFormMetaclass],
167 name: str,
168 bases: tuple[type, ...],
169 attrs: dict[str, Any],
170 ) -> type[BaseModelForm]:
171 # Metaclass __new__ returns a type, specifically type[BaseModelForm]
172 new_class = cast(type[BaseModelForm], super().__new__(mcs, name, bases, attrs))
173
174 if bases == (BaseModelForm,):
175 return new_class
176
177 opts = new_class._meta = ModelFormOptions(getattr(new_class, "Meta", None))
178
179 # We check if a string was passed to `fields`,
180 # which is likely to be a mistake where the user typed ('foo') instead
181 # of ('foo',)
182 for opt in ["fields"]:
183 value = getattr(opts, opt)
184 if isinstance(value, str):
185 msg = (
186 f"{new_class.__name__}.Meta.{opt} cannot be a string. "
187 f"Did you mean to type: ('{value}',)?"
188 )
189 raise TypeError(msg)
190
191 if opts.model:
192 # If a model is defined, extract form fields from it.
193 if opts.fields is None:
194 raise ImproperlyConfigured(
195 "Creating a ModelForm without the 'fields' attribute "
196 f"is prohibited; form {name} "
197 "needs updating."
198 )
199
200 fields = fields_for_model(
201 opts.model,
202 opts.fields,
203 opts.formfield_callback,
204 opts.error_messages,
205 opts.field_classes,
206 )
207
208 # make sure opts.fields doesn't specify an invalid field
209 none_model_fields = {k for k, v in fields.items() if not v}
210 missing_fields = none_model_fields.difference(new_class.declared_fields)
211 if missing_fields:
212 message = "Unknown field(s) (%s) specified for %s"
213 message %= (", ".join(missing_fields), opts.model.__name__)
214 raise FieldError(message)
215 # Override default model fields with any custom declared ones
216 # (plus, include all the other declared fields).
217 fields.update(new_class.declared_fields)
218 else:
219 fields = new_class.declared_fields
220
221 # After validation and update, all fields should be non-None
222 new_class.base_fields = cast(dict[str, Field], fields)
223
224 return new_class
225
226
227class BaseModelForm(BaseForm):
228 # Set by DeclarativeFieldsMetaclass
229 declared_fields: dict[str, Field]
230 # Set by ModelFormMetaclass
231 _meta: ModelFormOptions
232
233 def __init__(
234 self,
235 *,
236 request: Any,
237 auto_id: str = "id_%s",
238 prefix: str | None = None,
239 initial: dict[str, Any] | None = None,
240 instance: Any = None,
241 ) -> None:
242 opts = self._meta
243 if opts.model is None:
244 raise ValueError("ModelForm has no model class specified.")
245 if instance is None:
246 # if we didn't get an instance, instantiate a new one
247 self.instance = opts.model()
248 object_data = {}
249 else:
250 self.instance = instance
251 object_data = model_to_dict(instance, opts.fields)
252 # if initial was provided, it should override the values from instance
253 if initial is not None:
254 object_data.update(initial)
255 # self._validate_unique will be set to True by BaseModelForm.clean().
256 # It is False by default so overriding self.clean() and failing to call
257 # super will stop validate_unique from being called.
258 self._validate_unique = False
259 super().__init__(
260 request=request,
261 auto_id=auto_id,
262 prefix=prefix,
263 initial=object_data,
264 )
265
266 def _get_validation_exclusions(self) -> set[str]:
267 """
268 For backwards-compatibility, exclude several types of fields from model
269 validation. See tickets #12507, #12521, #12553.
270 """
271 exclude = set()
272 # Build up a list of fields that should be excluded from model field
273 # validation and unique checks.
274 for f in self.instance._model_meta.fields:
275 field = f.name
276 # Exclude fields that aren't on the form. The developer may be
277 # adding these values to the model after form validation.
278 if field not in self.fields:
279 exclude.add(f.name)
280
281 # Don't perform model validation on fields that were defined
282 # manually on the form and excluded via the ModelForm's Meta
283 # class. See #12901.
284 elif self._meta.fields and field not in self._meta.fields:
285 exclude.add(f.name)
286
287 # Exclude fields that failed form validation. There's no need for
288 # the model fields to validate them as well.
289 elif self._errors and field in self._errors:
290 exclude.add(f.name)
291
292 # Exclude empty fields that are not required by the form, if the
293 # underlying model field is required. This keeps the model field
294 # from raising a required error. Note: don't exclude the field from
295 # validation if the model field allows blanks. If it does, the blank
296 # value may be included in a unique check, so cannot be excluded
297 # from validation.
298 else:
299 form_field = self.fields[field]
300 field_value = self.cleaned_data.get(field)
301 if (
302 f.required
303 and not form_field.required
304 and field_value in form_field.empty_values
305 ):
306 exclude.add(f.name)
307 return exclude
308
309 def clean(self) -> dict[str, Any]:
310 self._validate_unique = True
311 return self.cleaned_data
312
313 def _update_errors(self, errors: ValidationError) -> None:
314 # Override any validation error messages defined at the model level
315 # with those defined at the form level.
316 opts = self._meta
317
318 # Allow the model generated by construct_instance() to raise
319 # ValidationError and have them handled in the same way as others.
320 if hasattr(errors, "error_dict"):
321 error_dict = errors.error_dict
322 else:
323 error_dict = {NON_FIELD_ERRORS: errors}
324
325 for field, messages in error_dict.items():
326 if (
327 field == NON_FIELD_ERRORS
328 and opts.error_messages
329 and NON_FIELD_ERRORS in opts.error_messages
330 ):
331 error_messages = opts.error_messages[NON_FIELD_ERRORS]
332 elif field in self.fields:
333 error_messages = self.fields[field].error_messages
334 else:
335 continue
336
337 for message in messages:
338 if (
339 isinstance(message, ValidationError)
340 and message.code in error_messages
341 ):
342 message.message = error_messages[message.code]
343
344 self.add_error(None, errors)
345
346 def _post_clean(self) -> None:
347 opts = self._meta
348
349 exclude = self._get_validation_exclusions()
350
351 try:
352 self.instance = construct_instance(self, self.instance, opts.fields)
353 except ValidationError as e:
354 self._update_errors(e)
355
356 try:
357 self.instance.full_clean(exclude=exclude, validate_unique=False)
358 except ValidationError as e:
359 self._update_errors(e)
360
361 # Validate uniqueness if needed.
362 if self._validate_unique:
363 self.validate_unique()
364
365 def validate_unique(self) -> None:
366 """
367 Call the instance's validate_unique() method and update the form's
368 validation errors if any were raised.
369 """
370 exclude = self._get_validation_exclusions()
371 try:
372 self.instance.validate_unique(exclude=exclude)
373 except ValidationError as e:
374 self._update_errors(e)
375
376 def _save_m2m(self) -> None:
377 """
378 Save the many-to-many fields and generic relations for this form.
379 """
380 cleaned_data = self.cleaned_data
381 fields = self._meta.fields
382 meta = self.instance._model_meta
383
384 for f in meta.many_to_many:
385 if not hasattr(f, "save_form_data"):
386 continue
387 if fields and f.name not in fields:
388 continue
389 if f.name in cleaned_data:
390 f.save_form_data(self.instance, cleaned_data[f.name])
391
392 def save(self, commit: bool = True) -> Any:
393 """
394 Save this form's self.instance object if commit=True. Otherwise, add
395 a save_m2m() method to the form which can be called after the instance
396 is saved manually at a later time. Return the model instance.
397 """
398 if self.errors:
399 raise ValueError(
400 "The {} could not be {} because the data didn't validate.".format(
401 self.instance.model_options.object_name,
402 "created" if self.instance._state.adding else "changed",
403 )
404 )
405 if commit:
406 # If committing, save the instance and the m2m data immediately.
407 self.instance.save(clean_and_validate=False)
408 self._save_m2m()
409 else:
410 # If not committing, add a method to the form to allow deferred
411 # saving of m2m data.
412 self.save_m2m = self._save_m2m
413 return self.instance
414
415
416class ModelForm(BaseModelForm, metaclass=ModelFormMetaclass):
417 pass
418
419
420# Fields #####################################################################
421
422
423class ModelChoiceIteratorValue:
424 def __init__(self, value: Any, instance: Any) -> None:
425 self.value = value
426 self.instance = instance
427
428 def __str__(self) -> str:
429 return str(self.value)
430
431 def __hash__(self) -> int:
432 return hash(self.value)
433
434 def __eq__(self, other: object) -> bool:
435 if isinstance(other, ModelChoiceIteratorValue):
436 other = other.value
437 return self.value == other
438
439
440class ModelChoiceIterator:
441 def __init__(self, field: ModelChoiceField) -> None:
442 self.field = field
443 self.queryset = field.queryset
444
445 def __iter__(self) -> Any:
446 if self.field.empty_label is not None:
447 yield ("", self.field.empty_label)
448 queryset = self.queryset
449 # Can't use iterator() when queryset uses prefetch_related()
450 if not queryset._prefetch_related_lookups:
451 queryset = queryset.iterator()
452 for obj in queryset:
453 yield self.choice(obj)
454
455 def __len__(self) -> int:
456 # count() adds a query but uses less memory since the QuerySet results
457 # won't be cached. In most cases, the choices will only be iterated on,
458 # and __len__() won't be called.
459 return self.queryset.count() + (1 if self.field.empty_label is not None else 0)
460
461 def __bool__(self) -> bool:
462 return self.field.empty_label is not None or self.queryset.exists()
463
464 def choice(self, obj: Any) -> tuple[ModelChoiceIteratorValue, str]:
465 return (
466 ModelChoiceIteratorValue(self.field.prepare_value(obj), obj),
467 str(obj),
468 )
469
470
471class ModelChoiceField(ChoiceField):
472 """A ChoiceField whose choices are a model QuerySet."""
473
474 # This class is a subclass of ChoiceField for purity, but it doesn't
475 # actually use any of ChoiceField's implementation.
476 default_error_messages = {
477 "invalid_choice": "Select a valid choice. That choice is not one of the available choices.",
478 }
479 iterator = ModelChoiceIterator
480
481 def __init__(
482 self,
483 queryset: Any,
484 *,
485 empty_label: str | None = "---------",
486 required: bool = True,
487 initial: Any = None,
488 **kwargs: Any,
489 ) -> None:
490 # Call Field instead of ChoiceField __init__() because we don't need
491 # ChoiceField.__init__().
492 Field.__init__(
493 self,
494 required=required,
495 initial=initial,
496 **kwargs,
497 )
498 if required and initial is not None:
499 self.empty_label = None
500 else:
501 self.empty_label = empty_label
502 self.queryset = queryset
503
504 def __deepcopy__(self, memo: dict[int, Any]) -> ModelChoiceField:
505 result = super(ChoiceField, self).__deepcopy__(memo)
506 # Need to force a new ModelChoiceIterator to be created, bug #11183
507 if self.queryset is not None:
508 result.queryset = self.queryset.all()
509 return result
510
511 def _get_queryset(self) -> Any:
512 return self._queryset
513
514 def _set_queryset(self, queryset: Any) -> None:
515 self._queryset = None if queryset is None else queryset.all()
516
517 queryset = property(_get_queryset, _set_queryset)
518
519 def _get_choices(self) -> ModelChoiceIterator:
520 # If self._choices is set, then somebody must have manually set
521 # the property self.choices. In this case, just return self._choices.
522 if hasattr(self, "_choices"):
523 # After checking hasattr, we know _choices exists and is ModelChoiceIterator
524 return cast(ModelChoiceIterator, self._choices)
525
526 # Otherwise, execute the QuerySet in self.queryset to determine the
527 # choices dynamically. Return a fresh ModelChoiceIterator that has not been
528 # consumed. Note that we're instantiating a new ModelChoiceIterator *each*
529 # time _get_choices() is called (and, thus, each time self.choices is
530 # accessed) so that we can ensure the QuerySet has not been consumed. This
531 # construct might look complicated but it allows for lazy evaluation of
532 # the queryset.
533 return self.iterator(self)
534
535 choices = property(_get_choices, ChoiceField._set_choices)
536
537 def prepare_value(self, value: Any) -> Any:
538 if hasattr(value, "_model_meta"):
539 return value.id
540 return super().prepare_value(value)
541
542 def to_python(self, value: Any) -> Any:
543 if value in self.empty_values:
544 return None
545 try:
546 key = "id"
547 if isinstance(value, self.queryset.model):
548 value = getattr(value, key)
549 value = self.queryset.get(**{key: value})
550 except (ValueError, TypeError, self.queryset.model.DoesNotExist):
551 raise ValidationError(
552 self.error_messages["invalid_choice"],
553 code="invalid_choice",
554 params={"value": value},
555 )
556 return value
557
558 def validate(self, value: Any) -> None:
559 return Field.validate(self, value)
560
561 def has_changed(self, initial: Any, data: Any) -> bool:
562 initial_value = initial if initial is not None else ""
563 data_value = data if data is not None else ""
564 return str(self.prepare_value(initial_value)) != str(data_value)
565
566
567class ModelMultipleChoiceField(ModelChoiceField):
568 """A MultipleChoiceField whose choices are a model QuerySet."""
569
570 default_error_messages = {
571 "invalid_list": "Enter a list of values.",
572 "invalid_choice": "Select a valid choice. %(value)s is not one of the available choices.",
573 "invalid_id_value": "'%(id)s' is not a valid value.",
574 }
575
576 def __init__(self, queryset: Any, **kwargs: Any) -> None:
577 super().__init__(queryset, empty_label=None, **kwargs)
578
579 def to_python(self, value: Any) -> list[Any]:
580 if not value:
581 return []
582 return list(self._check_values(value))
583
584 def clean(self, value: Any) -> Any:
585 value = self.prepare_value(value)
586 if self.required and not value:
587 raise ValidationError(self.error_messages["required"], code="required")
588 elif not self.required and not value:
589 return self.queryset.none()
590 if not isinstance(value, list | tuple):
591 raise ValidationError(
592 self.error_messages["invalid_list"],
593 code="invalid_list",
594 )
595 qs = self._check_values(value)
596 # Since this overrides the inherited ModelChoiceField.clean
597 # we run custom validators here
598 self.run_validators(value)
599 return qs
600
601 def _check_values(self, value: Any) -> Any:
602 """
603 Given a list of possible PK values, return a QuerySet of the
604 corresponding objects. Raise a ValidationError if a given value is
605 invalid (not a valid PK, not in the queryset, etc.)
606 """
607 # deduplicate given values to avoid creating many querysets or
608 # requiring the database backend deduplicate efficiently.
609 try:
610 value = frozenset(value)
611 except TypeError:
612 # list of lists isn't hashable, for example
613 raise ValidationError(
614 self.error_messages["invalid_list"],
615 code="invalid_list",
616 )
617 for id_val in value:
618 try:
619 self.queryset.filter(id=id_val)
620 except (ValueError, TypeError):
621 raise ValidationError(
622 self.error_messages["invalid_id_value"],
623 code="invalid_id_value",
624 params={"id": id_val},
625 )
626 qs = self.queryset.filter(id__in=value)
627 ids = {str(o.id) for o in qs}
628 for val in value:
629 if str(val) not in ids:
630 raise ValidationError(
631 self.error_messages["invalid_choice"],
632 code="invalid_choice",
633 params={"value": val},
634 )
635 return qs
636
637 def prepare_value(self, value: Any) -> Any:
638 if (
639 hasattr(value, "__iter__")
640 and not isinstance(value, str)
641 and not hasattr(value, "_model_meta")
642 ):
643 prepare_value = super().prepare_value
644 return [prepare_value(v) for v in value]
645 return super().prepare_value(value)
646
647 def has_changed(self, initial: Any, data: Any) -> bool:
648 if initial is None:
649 initial = []
650 if data is None:
651 data = []
652 if len(initial) != len(data):
653 return True
654 initial_set = {str(value) for value in self.prepare_value(initial)}
655 data_set = {str(value) for value in data}
656 return data_set != initial_set
657
658 def value_from_form_data(self, data: Any, files: Any, html_name: str) -> Any:
659 return data.getlist(html_name)
660
661
662def modelfield_to_formfield(
663 modelfield: ModelField,
664 form_class: type[Field] | None = None,
665 choices_form_class: type[Field] | None = None,
666 **kwargs: Any,
667) -> Field | None:
668 defaults: dict[str, Any] = {
669 "required": modelfield.required,
670 }
671
672 if modelfield.has_default():
673 defaults["initial"] = modelfield.get_default()
674
675 if modelfield.choices is not None:
676 # Fields with choices get special treatment.
677 include_blank = not modelfield.required or not (
678 modelfield.has_default() or "initial" in kwargs
679 )
680 defaults["choices"] = modelfield.get_choices(include_blank=include_blank)
681 defaults["coerce"] = modelfield.to_python
682 if modelfield.allow_null:
683 defaults["empty_value"] = None
684 if choices_form_class is not None:
685 form_class = choices_form_class
686 else:
687 form_class = fields.TypedChoiceField
688 # Many of the subclass-specific formfield arguments (min_value,
689 # max_value) don't apply for choice fields, so be sure to only pass
690 # the values that TypedChoiceField will understand.
691 for k in list(kwargs):
692 if k not in (
693 "coerce",
694 "empty_value",
695 "choices",
696 "required",
697 "initial",
698 "error_messages",
699 ):
700 del kwargs[k]
701
702 defaults.update(kwargs)
703
704 if form_class is not None:
705 return form_class(**defaults)
706
707 # Avoid a circular import
708 from plain import models
709
710 # Primary key fields aren't rendered by default
711 if isinstance(modelfield, models.PrimaryKeyField):
712 return None
713
714 if isinstance(modelfield, models.BooleanField):
715 form_class = (
716 fields.NullBooleanField if modelfield.allow_null else fields.BooleanField
717 )
718 # In HTML checkboxes, 'required' means "must be checked" which is
719 # different from the choices case ("must select some value").
720 # required=False allows unchecked checkboxes.
721 defaults["required"] = False
722 return form_class(**defaults)
723
724 if isinstance(modelfield, models.DecimalField):
725 return fields.DecimalField(
726 max_digits=modelfield.max_digits,
727 decimal_places=modelfield.decimal_places,
728 **defaults,
729 )
730
731 if issubclass(modelfield.__class__, models.fields.PositiveIntegerRelDbTypeMixin):
732 return fields.IntegerField(min_value=0, **defaults)
733
734 if isinstance(modelfield, models.TextField):
735 # Passing max_length to fields.CharField means that the value's length
736 # will be validated twice. This is considered acceptable since we want
737 # the value in the form field (to pass into widget for example).
738 return fields.CharField(max_length=modelfield.max_length, **defaults)
739
740 if isinstance(modelfield, models.CharField):
741 # Passing max_length to forms.CharField means that the value's length
742 # will be validated twice. This is considered acceptable since we want
743 # the value in the form field (to pass into widget for example).
744 if modelfield.allow_null:
745 defaults["empty_value"] = None
746 return fields.CharField(
747 max_length=modelfield.max_length,
748 **defaults,
749 )
750
751 if isinstance(modelfield, models.JSONField):
752 return fields.JSONField(
753 encoder=modelfield.encoder, decoder=modelfield.decoder, **defaults
754 )
755
756 if isinstance(modelfield, models.ForeignKeyField):
757 return ModelChoiceField(
758 queryset=modelfield.remote_field.model.query,
759 **defaults,
760 )
761
762 # TODO related (OneToOne, m2m)
763
764 # If there's a form field of the exact same name, use it
765 # (models.URLField -> forms.URLField)
766 if hasattr(fields, modelfield.__class__.__name__):
767 form_class = getattr(fields, modelfield.__class__.__name__)
768 return form_class(**defaults)
769
770 # Default to CharField if we didn't find anything else
771 return fields.CharField(**defaults)