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