Debian Codegraph @

django/forms/fields.py

raw
1 """
2 Field classes.
3 """
4
5 import copy
6 import datetime
7 import json
8 import math
9 import operator
10 import os
11 import re
12 import uuid
13 import warnings
14 from decimal import Decimal, DecimalException
15 from io import BytesIO
16
17 from django.conf import settings
18 from django.core import validators
19 from django.core.exceptions import ValidationError
20 from django.forms.boundfield import BoundField
21 from django.forms.utils import from_current_timezone, to_current_timezone
22 from django.forms.widgets import (
23 FILE_INPUT_CONTRADICTION,
24 CheckboxInput,
25 ClearableFileInput,
26 DateInput,
27 DateTimeInput,
28 EmailInput,
29 FileInput,
30 HiddenInput,
31 MultipleHiddenInput,
32 NullBooleanSelect,
33 NumberInput,
34 Select,
35 SelectMultiple,
36 SplitDateTimeWidget,
37 SplitHiddenDateTimeWidget,
38 Textarea,
39 TextInput,
40 TimeInput,
41 URLInput,
42 )
43 from django.utils import formats
44 from django.utils.choices import normalize_choices
45 from django.utils.dateparse import parse_datetime, parse_duration
46 from django.utils.deprecation import RemovedInDjango60Warning
47 from django.utils.duration import duration_string
48 from django.utils.ipv6 import MAX_IPV6_ADDRESS_LENGTH, clean_ipv6_address
49 from django.utils.regex_helper import _lazy_re_compile
50 from django.utils.translation import gettext_lazy as _
51 from django.utils.translation import ngettext_lazy
52
53 __all__ = (
54 "Field",
55 "CharField",
56 "IntegerField",
57 "DateField",
58 "TimeField",
59 "DateTimeField",
60 "DurationField",
61 "RegexField",
62 "EmailField",
63 "FileField",
64 "ImageField",
65 "URLField",
66 "BooleanField",
67 "NullBooleanField",
68 "ChoiceField",
69 "MultipleChoiceField",
70 "ComboField",
71 "MultiValueField",
72 "FloatField",
73 "DecimalField",
74 "SplitDateTimeField",
75 "GenericIPAddressField",
76 "FilePathField",
77 "JSONField",
78 "SlugField",
79 "TypedChoiceField",
80 "TypedMultipleChoiceField",
81 "UUIDField",
82 )
83
84
85 class Field:
86 widget = TextInput # Default widget to use when rendering this type of Field.
87 hidden_widget = (
88 HiddenInput # Default widget to use when rendering this as "hidden".
89 )
90 default_validators = [] # Default set of validators
91 # Add an 'invalid' entry to default_error_message if you want a specific
92 # field error message not raised by the field validators.
93 default_error_messages = {
94 "required": _("This field is required."),
95 }
96 empty_values = list(validators.EMPTY_VALUES)
97 bound_field_class = None
98
99 def __init__(
100 self,
101 *,
102 required=True,
103 widget=None,
104 label=None,
105 initial=None,
106 help_text="",
107 error_messages=None,
108 show_hidden_initial=False,
109 validators=(),
110 localize=False,
111 disabled=False,
112 label_suffix=None,
113 template_name=None,
114 bound_field_class=None,
115 ):
116 # required -- Boolean that specifies whether the field is required.
117 # True by default.
118 # widget -- A Widget class, or instance of a Widget class, that should
119 # be used for this Field when displaying it. Each Field has a
120 # default Widget that it'll use if you don't specify this. In
121 # most cases, the default widget is TextInput.
122 # label -- A verbose name for this field, for use in displaying this
123 # field in a form. By default, Django will use a "pretty"
124 # version of the form field name, if the Field is part of a
125 # Form.
126 # initial -- A value to use in this Field's initial display. This value
127 # is *not* used as a fallback if data isn't given.
128 # help_text -- An optional string to use as "help text" for this Field.
129 # error_messages -- An optional dictionary to override the default
130 # messages that the field will raise.
131 # show_hidden_initial -- Boolean that specifies if it is needed to render a
132 # hidden widget with initial value after widget.
133 # validators -- List of additional validators to use
134 # localize -- Boolean that specifies if the field should be localized.
135 # disabled -- Boolean that specifies whether the field is disabled, that
136 # is its widget is shown in the form but not editable.
137 # label_suffix -- Suffix to be added to the label. Overrides
138 # form's label_suffix.
139 # bound_field_class -- BoundField class to use in Field.get_bound_field.
140 self.required, self.label, self.initial = required, label, initial
141 self.show_hidden_initial = show_hidden_initial
142 self.help_text = help_text
143 self.disabled = disabled
144 self.label_suffix = label_suffix
145 self.bound_field_class = bound_field_class or self.bound_field_class
146 widget = widget or self.widget
147 if isinstance(widget, type):
148 widget = widget()
149 else:
150 widget = copy.deepcopy(widget)
151
152 # Trigger the localization machinery if needed.
153 self.localize = localize
154 if self.localize:
155 widget.is_localized = True
156
157 # Let the widget know whether it should display as required.
158 widget.is_required = self.required
159
160 # Hook into self.widget_attrs() for any Field-specific HTML attributes.
161 extra_attrs = self.widget_attrs(widget)
162 if extra_attrs:
163 widget.attrs.update(extra_attrs)
164
165 self.widget = widget
166
167 messages = {}
168 for c in reversed(self.__class__.__mro__):
169 messages.update(getattr(c, "default_error_messages", {}))
170 messages.update(error_messages or {})
171 self.error_messages = messages
172
173 self.validators = [*self.default_validators, *validators]
174 self.template_name = template_name
175
176 super().__init__()
177
178 def prepare_value(self, value):
179 return value
180
181 def to_python(self, value):
182 return value
183
184 def validate(self, value):
185 if value in self.empty_values and self.required:
186 raise ValidationError(self.error_messages["required"], code="required")
187
188 def run_validators(self, value):
189 if value in self.empty_values:
190 return
191 errors = []
192 for v in self.validators:
193 try:
194 v(value)
195 except ValidationError as e:
196 if hasattr(e, "code") and e.code in self.error_messages:
197 e.message = self.error_messages[e.code]
198 errors.extend(e.error_list)
199 if errors:
200 raise ValidationError(errors)
201
202 def clean(self, value):
203 """
204 Validate the given value and return its "cleaned" value as an
205 appropriate Python object. Raise ValidationError for any errors.
206 """
207 value = self.to_python(value)
208 self.validate(value)
209 self.run_validators(value)
210 return value
211
212 def bound_data(self, data, initial):
213 """
214 Return the value that should be shown for this field on render of a
215 bound form, given the submitted POST data for the field and the initial
216 data, if any.
217
218 For most fields, this will simply be data; FileFields need to handle it
219 a bit differently.
220 """
221 if self.disabled:
222 return initial
223 return data
224
225 def widget_attrs(self, widget):
226 """
227 Given a Widget instance (*not* a Widget class), return a dictionary of
228 any HTML attributes that should be added to the Widget, based on this
229 Field.
230 """
231 return {}
232
233 def has_changed(self, initial, data):
234 """Return True if data differs from initial."""
235 # Always return False if the field is disabled since self.bound_data
236 # always uses the initial value in this case.
237 if self.disabled:
238 return False
239 try:
240 data = self.to_python(data)
241 if hasattr(self, "_coerce"):
242 return self._coerce(data) != self._coerce(initial)
243 except ValidationError:
244 return True
245 # For purposes of seeing whether something has changed, None is
246 # the same as an empty string, if the data or initial value we get
247 # is None, replace it with ''.
248 initial_value = initial if initial is not None else ""
249 data_value = data if data is not None else ""
250 return initial_value != data_value
251
252 def get_bound_field(self, form, field_name):
253 """
254 Return a BoundField instance that will be used when accessing the form
255 field in a template.
256 """
257 bound_field_class = (
258 self.bound_field_class or form.bound_field_class or BoundField
259 )
260 return bound_field_class(form, self, field_name)
261
262 def __deepcopy__(self, memo):
263 result = copy.copy(self)
264 memo[id(self)] = result
265 result.widget = copy.deepcopy(self.widget, memo)
266 result.error_messages = self.error_messages.copy()
267 result.validators = self.validators[:]
268 return result
269
270 def _clean_bound_field(self, bf):
271 value = bf.initial if self.disabled else bf.data
272 return self.clean(value)
273
274
275 class CharField(Field):
276 def __init__(
277 self, *, max_length=None, min_length=None, strip=True, empty_value="", **kwargs
278 ):
279 self.max_length = max_length
280 self.min_length = min_length
281 self.strip = strip
282 self.empty_value = empty_value
283 super().__init__(**kwargs)
284 if min_length is not None:
285 self.validators.append(validators.MinLengthValidator(int(min_length)))
286 if max_length is not None:
287 self.validators.append(validators.MaxLengthValidator(int(max_length)))
288 self.validators.append(validators.ProhibitNullCharactersValidator())
289
290 def to_python(self, value):
291 """Return a string."""
292 if value not in self.empty_values:
293 value = str(value)
294 if self.strip:
295 value = value.strip()
296 if value in self.empty_values:
297 return self.empty_value
298 return value
299
300 def widget_attrs(self, widget):
301 attrs = super().widget_attrs(widget)
302 if self.max_length is not None and not widget.is_hidden:
303 # The HTML attribute is maxlength, not max_length.
304 attrs["maxlength"] = str(self.max_length)
305 if self.min_length is not None and not widget.is_hidden:
306 # The HTML attribute is minlength, not min_length.
307 attrs["minlength"] = str(self.min_length)
308 return attrs
309
310
311 class IntegerField(Field):
312 widget = NumberInput
313 default_error_messages = {
314 "invalid": _("Enter a whole number."),
315 }
316 re_decimal = _lazy_re_compile(r"\.0*\s*$")
317
318 def __init__(self, *, max_value=None, min_value=None, step_size=None, **kwargs):
319 self.max_value, self.min_value, self.step_size = max_value, min_value, step_size
320 if kwargs.get("localize") and self.widget == NumberInput:
321 # Localized number input is not well supported on most browsers
322 kwargs.setdefault("widget", super().widget)
323 super().__init__(**kwargs)
324
325 if max_value is not None:
326 self.validators.append(validators.MaxValueValidator(max_value))
327 if min_value is not None:
328 self.validators.append(validators.MinValueValidator(min_value))
329 if step_size is not None:
330 self.validators.append(
331 validators.StepValueValidator(step_size, offset=min_value)
332 )
333
334 def to_python(self, value):
335 """
336 Validate that int() can be called on the input. Return the result
337 of int() or None for empty values.
338 """
339 value = super().to_python(value)
340 if value in self.empty_values:
341 return None
342 if self.localize:
343 value = formats.sanitize_separators(value)
344 # Strip trailing decimal and zeros.
345 try:
346 value = int(self.re_decimal.sub("", str(value)))
347 except (ValueError, TypeError):
348 raise ValidationError(self.error_messages["invalid"], code="invalid")
349 return value
350
351 def widget_attrs(self, widget):
352 attrs = super().widget_attrs(widget)
353 if isinstance(widget, NumberInput):
354 if self.min_value is not None:
355 attrs["min"] = self.min_value
356 if self.max_value is not None:
357 attrs["max"] = self.max_value
358 if self.step_size is not None:
359 attrs["step"] = self.step_size
360 return attrs
361
362
363 class FloatField(IntegerField):
364 default_error_messages = {
365 "invalid": _("Enter a number."),
366 }
367
368 def to_python(self, value):
369 """
370 Validate that float() can be called on the input. Return the result
371 of float() or None for empty values.
372 """
373 value = super(IntegerField, self).to_python(value)
374 if value in self.empty_values:
375 return None
376 if self.localize:
377 value = formats.sanitize_separators(value)
378 try:
379 value = float(value)
380 except (ValueError, TypeError):
381 raise ValidationError(self.error_messages["invalid"], code="invalid")
382 return value
383
384 def validate(self, value):
385 super().validate(value)
386 if value in self.empty_values:
387 return
388 if not math.isfinite(value):
389 raise ValidationError(self.error_messages["invalid"], code="invalid")
390
391 def widget_attrs(self, widget):
392 attrs = super().widget_attrs(widget)
393 if isinstance(widget, NumberInput) and "step" not in widget.attrs:
394 if self.step_size is not None:
395 step = str(self.step_size)
396 else:
397 step = "any"
398 attrs.setdefault("step", step)
399 return attrs
400
401
402 class DecimalField(IntegerField):
403 default_error_messages = {
404 "invalid": _("Enter a number."),
405 }
406
407 def __init__(
408 self,
409 *,
410 max_value=None,
411 min_value=None,
412 max_digits=None,
413 decimal_places=None,
414 **kwargs,
415 ):
416 self.max_digits, self.decimal_places = max_digits, decimal_places
417 super().__init__(max_value=max_value, min_value=min_value, **kwargs)
418 self.validators.append(validators.DecimalValidator(max_digits, decimal_places))
419
420 def to_python(self, value):
421 """
422 Validate that the input is a decimal number. Return a Decimal
423 instance or None for empty values. Ensure that there are no more
424 than max_digits in the number and no more than decimal_places digits
425 after the decimal point.
426 """
427 if value in self.empty_values:
428 return None
429 if self.localize:
430 value = formats.sanitize_separators(value)
431 try:
432 value = Decimal(str(value))
433 except DecimalException:
434 raise ValidationError(self.error_messages["invalid"], code="invalid")
435 return value
436
437 def validate(self, value):
438 super().validate(value)
439 if value in self.empty_values:
440 return
441 if not value.is_finite():
442 raise ValidationError(
443 self.error_messages["invalid"],
444 code="invalid",
445 params={"value": value},
446 )
447
448 def widget_attrs(self, widget):
449 attrs = super().widget_attrs(widget)
450 if isinstance(widget, NumberInput) and "step" not in widget.attrs:
451 if self.decimal_places is not None:
452 # Use exponential notation for small values since they might
453 # be parsed as 0 otherwise. ref #20765
454 step = str(Decimal(1).scaleb(-self.decimal_places)).lower()
455 else:
456 step = "any"
457 attrs.setdefault("step", step)
458 return attrs
459
460
461 class BaseTemporalField(Field):
462 def __init__(self, *, input_formats=None, **kwargs):
463 super().__init__(**kwargs)
464 if input_formats is not None:
465 self.input_formats = input_formats
466
467 def to_python(self, value):
468 value = value.strip()
469 # Try to strptime against each input format.
470 for format in self.input_formats:
471 try:
472 return self.strptime(value, format)
473 except (ValueError, TypeError):
474 continue
475 raise ValidationError(self.error_messages["invalid"], code="invalid")
476
477 def strptime(self, value, format):
478 raise NotImplementedError("Subclasses must define this method.")
479
480
481 class DateField(BaseTemporalField):
482 widget = DateInput
483 input_formats = formats.get_format_lazy("DATE_INPUT_FORMATS")
484 default_error_messages = {
485 "invalid": _("Enter a valid date."),
486 }
487
488 def to_python(self, value):
489 """
490 Validate that the input can be converted to a date. Return a Python
491 datetime.date object.
492 """
493 if value in self.empty_values:
494 return None
495 if isinstance(value, datetime.datetime):
496 return value.date()
497 if isinstance(value, datetime.date):
498 return value
499 return super().to_python(value)
500
501 def strptime(self, value, format):
502 return datetime.datetime.strptime(value, format).date()
503
504
505 class TimeField(BaseTemporalField):
506 widget = TimeInput
507 input_formats = formats.get_format_lazy("TIME_INPUT_FORMATS")
508 default_error_messages = {"invalid": _("Enter a valid time.")}
509
510 def to_python(self, value):
511 """
512 Validate that the input can be converted to a time. Return a Python
513 datetime.time object.
514 """
515 if value in self.empty_values:
516 return None
517 if isinstance(value, datetime.time):
518 return value
519 return super().to_python(value)
520
521 def strptime(self, value, format):
522 return datetime.datetime.strptime(value, format).time()
523
524
525 class DateTimeFormatsIterator:
526 def __iter__(self):
527 yield from formats.get_format("DATETIME_INPUT_FORMATS")
528 yield from formats.get_format("DATE_INPUT_FORMATS")
529
530
531 class DateTimeField(BaseTemporalField):
532 widget = DateTimeInput
533 input_formats = DateTimeFormatsIterator()
534 default_error_messages = {
535 "invalid": _("Enter a valid date/time."),
536 }
537
538 def prepare_value(self, value):
539 if isinstance(value, datetime.datetime):
540 value = to_current_timezone(value)
541 return value
542
543 def to_python(self, value):
544 """
545 Validate that the input can be converted to a datetime. Return a
546 Python datetime.datetime object.
547 """
548 if value in self.empty_values:
549 return None
550 if isinstance(value, datetime.datetime):
551 return from_current_timezone(value)
552 if isinstance(value, datetime.date):
553 result = datetime.datetime(value.year, value.month, value.day)
554 return from_current_timezone(result)
555 try:
556 result = parse_datetime(value.strip())
557 except ValueError:
558 raise ValidationError(self.error_messages["invalid"], code="invalid")
559 if not result:
560 result = super().to_python(value)
561 return from_current_timezone(result)
562
563 def strptime(self, value, format):
564 return datetime.datetime.strptime(value, format)
565
566
567 class DurationField(Field):
568 default_error_messages = {
569 "invalid": _("Enter a valid duration."),
570 "overflow": _("The number of days must be between {min_days} and {max_days}."),
571 }
572
573 def prepare_value(self, value):
574 if isinstance(value, datetime.timedelta):
575 return duration_string(value)
576 return value
577
578 def to_python(self, value):
579 if value in self.empty_values:
580 return None
581 if isinstance(value, datetime.timedelta):
582 return value
583 try:
584 value = parse_duration(str(value))
585 except OverflowError:
586 raise ValidationError(
587 self.error_messages["overflow"].format(
588 min_days=datetime.timedelta.min.days,
589 max_days=datetime.timedelta.max.days,
590 ),
591 code="overflow",
592 )
593 if value is None:
594 raise ValidationError(self.error_messages["invalid"], code="invalid")
595 return value
596
597
598 class RegexField(CharField):
599 def __init__(self, regex, **kwargs):
600 """
601 regex can be either a string or a compiled regular expression object.
602 """
603 kwargs.setdefault("strip", False)
604 super().__init__(**kwargs)
605 self._set_regex(regex)
606
607 def _get_regex(self):
608 return self._regex
609
610 def _set_regex(self, regex):
611 if isinstance(regex, str):
612 regex = re.compile(regex)
613 self._regex = regex
614 if (
615 hasattr(self, "_regex_validator")
616 and self._regex_validator in self.validators
617 ):
618 self.validators.remove(self._regex_validator)
619 self._regex_validator = validators.RegexValidator(regex=regex)
620 self.validators.append(self._regex_validator)
621
622 regex = property(_get_regex, _set_regex)
623
624
625 class EmailField(CharField):
626 widget = EmailInput
627 default_validators = [validators.validate_email]
628
629 def __init__(self, **kwargs):
630 # The default maximum length of an email is 320 characters per RFC 3696
631 # section 3.
632 kwargs.setdefault("max_length", 320)
633 super().__init__(strip=True, **kwargs)
634
635
636 class FileField(Field):
637 widget = ClearableFileInput
638 default_error_messages = {
639 "invalid": _("No file was submitted. Check the encoding type on the form."),
640 "missing": _("No file was submitted."),
641 "empty": _("The submitted file is empty."),
642 "max_length": ngettext_lazy(
643 "Ensure this filename has at most %(max)d character (it has %(length)d).",
644 "Ensure this filename has at most %(max)d characters (it has %(length)d).",
645 "max",
646 ),
647 "contradiction": _(
648 "Please either submit a file or check the clear checkbox, not both."
649 ),
650 }
651
652 def __init__(self, *, max_length=None, allow_empty_file=False, **kwargs):
653 self.max_length = max_length
654 self.allow_empty_file = allow_empty_file
655 super().__init__(**kwargs)
656
657 def to_python(self, data):
658 if data in self.empty_values:
659 return None
660
661 # UploadedFile objects should have name and size attributes.
662 try:
663 file_name = data.name
664 file_size = data.size
665 except AttributeError:
666 raise ValidationError(self.error_messages["invalid"], code="invalid")
667
668 if self.max_length is not None and len(file_name) > self.max_length:
669 params = {"max": self.max_length, "length": len(file_name)}
670 raise ValidationError(
671 self.error_messages["max_length"], code="max_length", params=params
672 )
673 if not file_name:
674 raise ValidationError(self.error_messages["invalid"], code="invalid")
675 if not self.allow_empty_file and not file_size:
676 raise ValidationError(self.error_messages["empty"], code="empty")
677
678 return data
679
680 def clean(self, data, initial=None):
681 # If the widget got contradictory inputs, we raise a validation error
682 if data is FILE_INPUT_CONTRADICTION:
683 raise ValidationError(
684 self.error_messages["contradiction"], code="contradiction"
685 )
686 # False means the field value should be cleared; further validation is
687 # not needed.
688 if data is False:
689 if not self.required:
690 return False
691 # If the field is required, clearing is not possible (the widget
692 # shouldn't return False data in that case anyway). False is not
693 # in self.empty_value; if a False value makes it this far
694 # it should be validated from here on out as None (so it will be
695 # caught by the required check).
696 data = None
697 if not data and initial:
698 return initial
699 return super().clean(data)
700
701 def bound_data(self, _, initial):
702 return initial
703
704 def has_changed(self, initial, data):
705 return not self.disabled and data is not None
706
707 def _clean_bound_field(self, bf):
708 value = bf.initial if self.disabled else bf.data
709 return self.clean(value, bf.initial)
710
711
712 class ImageField(FileField):
713 default_validators = [validators.validate_image_file_extension]
714 default_error_messages = {
715 "invalid_image": _(
716 "Upload a valid image. The file you uploaded was either not an "
717 "image or a corrupted image."
718 ),
719 }
720
721 def to_python(self, data):
722 """
723 Check that the file-upload field data contains a valid image (GIF, JPG,
724 PNG, etc. -- whatever Pillow supports).
725 """
726 f = super().to_python(data)
727 if f is None:
728 return None
729
730 from PIL import Image
731
732 # We need to get a file object for Pillow. We might have a path or we might
733 # have to read the data into memory.
734 if hasattr(data, "temporary_file_path"):
735 file = data.temporary_file_path()
736 else:
737 if hasattr(data, "read"):
738 file = BytesIO(data.read())
739 else:
740 file = BytesIO(data["content"])
741
742 try:
743 # load() could spot a truncated JPEG, but it loads the entire
744 # image in memory, which is a DoS vector. See #3848 and #18520.
745 image = Image.open(file)
746 # verify() must be called immediately after the constructor.
747 image.verify()
748
749 # Annotating so subclasses can reuse it for their own validation
750 f.image = image
751 # Pillow doesn't detect the MIME type of all formats. In those
752 # cases, content_type will be None.
753 f.content_type = Image.MIME.get(image.format)
754 except Exception as exc:
755 # Pillow doesn't recognize it as an image.
756 raise ValidationError(
757 self.error_messages["invalid_image"],
758 code="invalid_image",
759 ) from exc
760 if hasattr(f, "seek") and callable(f.seek):
761 f.seek(0)
762 return f
763
764 def widget_attrs(self, widget):
765 attrs = super().widget_attrs(widget)
766 if isinstance(widget, FileInput) and "accept" not in widget.attrs:
767 attrs.setdefault("accept", "image/*")
768 return attrs
769
770
771 class URLField(CharField):
772 widget = URLInput
773 default_error_messages = {
774 "invalid": _("Enter a valid URL."),
775 }
776 default_validators = [validators.URLValidator()]
777
778 def __init__(self, *, assume_scheme=None, **kwargs):
779 if assume_scheme is None:
780 if settings.FORMS_URLFIELD_ASSUME_HTTPS:
781 assume_scheme = "https"
782 else:
783 warnings.warn(
784 "The default scheme will be changed from 'http' to 'https' in "
785 "Django 6.0. Pass the forms.URLField.assume_scheme argument to "
786 "silence this warning, or set the FORMS_URLFIELD_ASSUME_HTTPS "
787 "transitional setting to True to opt into using 'https' as the new "
788 "default scheme.",
789 RemovedInDjango60Warning,
790 stacklevel=2,
791 )
792 assume_scheme = "http"
793 # RemovedInDjango60Warning: When the deprecation ends, replace with:
794 # self.assume_scheme = assume_scheme or "https"
795 self.assume_scheme = assume_scheme
796 super().__init__(strip=True, **kwargs)
797
798 def to_python(self, value):
799 value = super().to_python(value)
800 if value:
801 # Detect scheme via partition to avoid calling urlsplit() on
802 # potentially large or slow-to-normalize inputs.
803 scheme, sep, _ = value.partition(":")
804 if (
805 not sep
806 or not scheme
807 or not scheme[0].isascii()
808 or not scheme[0].isalpha()
809 or "/" in scheme
810 ):
811 # No valid scheme found -- prepend the assumed scheme. Handle
812 # scheme-relative URLs ("//example.com") separately.
813 if value.startswith("//"):
814 value = self.assume_scheme + ":" + value
815 else:
816 value = self.assume_scheme + "://" + value
817 return value
818
819
820 class BooleanField(Field):
821 widget = CheckboxInput
822
823 def to_python(self, value):
824 """Return a Python boolean object."""
825 # Explicitly check for the string 'False', which is what a hidden field
826 # will submit for False. Also check for '0', since this is what
827 # RadioSelect will provide. Because bool("True") == bool('1') == True,
828 # we don't need to handle that explicitly.
829 if isinstance(value, str) and value.lower() in ("false", "0"):
830 value = False
831 else:
832 value = bool(value)
833 return super().to_python(value)
834
835 def validate(self, value):
836 if not value and self.required:
837 raise ValidationError(self.error_messages["required"], code="required")
838
839 def has_changed(self, initial, data):
840 if self.disabled:
841 return False
842 # Sometimes data or initial may be a string equivalent of a boolean
843 # so we should run it through to_python first to get a boolean value
844 return self.to_python(initial) != self.to_python(data)
845
846
847 class NullBooleanField(BooleanField):
848 """
849 A field whose valid values are None, True, and False. Clean invalid values
850 to None.
851 """
852
853 widget = NullBooleanSelect
854
855 def to_python(self, value):
856 """
857 Explicitly check for the string 'True' and 'False', which is what a
858 hidden field will submit for True and False, for 'true' and 'false',
859 which are likely to be returned by JavaScript serializations of forms,
860 and for '1' and '0', which is what a RadioField will submit. Unlike
861 the Booleanfield, this field must check for True because it doesn't
862 use the bool() function.
863 """
864 if value in (True, "True", "true", "1"):
865 return True
866 elif value in (False, "False", "false", "0"):
867 return False
868 else:
869 return None
870
871 def validate(self, value):
872 pass
873
874
875 class ChoiceField(Field):
876 widget = Select
877 default_error_messages = {
878 "invalid_choice": _(
879 "Select a valid choice. %(value)s is not one of the available choices."
880 ),
881 }
882
883 def __init__(self, *, choices=(), **kwargs):
884 super().__init__(**kwargs)
885 self.choices = choices
886
887 def __deepcopy__(self, memo):
888 result = super().__deepcopy__(memo)
889 result._choices = copy.deepcopy(self._choices, memo)
890 return result
891
892 @property
893 def choices(self):
894 return self._choices
895
896 @choices.setter
897 def choices(self, value):
898 # Setting choices on the field also sets the choices on the widget.
899 # Note that the property setter for the widget will re-normalize.
900 self._choices = self.widget.choices = normalize_choices(value)
901
902 def to_python(self, value):
903 """Return a string."""
904 if value in self.empty_values:
905 return ""
906 return str(value)
907
908 def validate(self, value):
909 """Validate that the input is in self.choices."""
910 super().validate(value)
911 if value and not self.valid_value(value):
912 raise ValidationError(
913 self.error_messages["invalid_choice"],
914 code="invalid_choice",
915 params={"value": value},
916 )
917
918 def valid_value(self, value):
919 """Check to see if the provided value is a valid choice."""
920 text_value = str(value)
921 for k, v in self.choices:
922 if isinstance(v, (list, tuple)):
923 # This is an optgroup, so look inside the group for options
924 for k2, v2 in v:
925 if value == k2 or text_value == str(k2):
926 return True
927 else:
928 if value == k or text_value == str(k):
929 return True
930 return False
931
932
933 class TypedChoiceField(ChoiceField):
934 def __init__(self, *, coerce=lambda val: val, empty_value="", **kwargs):
935 self.coerce = coerce
936 self.empty_value = empty_value
937 super().__init__(**kwargs)
938
939 def _coerce(self, value):
940 """
941 Validate that the value can be coerced to the right type (if not empty).
942 """
943 if value == self.empty_value or value in self.empty_values:
944 return self.empty_value
945 try:
946 value = self.coerce(value)
947 except (ValueError, TypeError, ValidationError):
948 raise ValidationError(
949 self.error_messages["invalid_choice"],
950 code="invalid_choice",
951 params={"value": value},
952 )
953 return value
954
955 def clean(self, value):
956 value = super().clean(value)
957 return self._coerce(value)
958
959
960 class MultipleChoiceField(ChoiceField):
961 hidden_widget = MultipleHiddenInput
962 widget = SelectMultiple
963 default_error_messages = {
964 "invalid_choice": _(
965 "Select a valid choice. %(value)s is not one of the available choices."
966 ),
967 "invalid_list": _("Enter a list of values."),
968 }
969
970 def to_python(self, value):
971 if not value:
972 return []
973 elif not isinstance(value, (list, tuple)):
974 raise ValidationError(
975 self.error_messages["invalid_list"], code="invalid_list"
976 )
977 return [str(val) for val in value]
978
979 def validate(self, value):
980 """Validate that the input is a list or tuple."""
981 if self.required and not value:
982 raise ValidationError(self.error_messages["required"], code="required")
983 # Validate that each value in the value list is in self.choices.
984 for val in value:
985 if not self.valid_value(val):
986 raise ValidationError(
987 self.error_messages["invalid_choice"],
988 code="invalid_choice",
989 params={"value": val},
990 )
991
992 def has_changed(self, initial, data):
993 if self.disabled:
994 return False
995 if initial is None:
996 initial = []
997 if data is None:
998 data = []
999 if len(initial) != len(data):
1000 return True
1001 initial_set = {str(value) for value in initial}
1002 data_set = {str(value) for value in data}
1003 return data_set != initial_set
1004
1005
1006 class TypedMultipleChoiceField(MultipleChoiceField):
1007 def __init__(self, *, coerce=lambda val: val, **kwargs):
1008 self.coerce = coerce
1009 self.empty_value = kwargs.pop("empty_value", [])
1010 super().__init__(**kwargs)
1011
1012 def _coerce(self, value):
1013 """
1014 Validate that the values are in self.choices and can be coerced to the
1015 right type.
1016 """
1017 if value == self.empty_value or value in self.empty_values:
1018 return self.empty_value
1019 new_value = []
1020 for choice in value:
1021 try:
1022 new_value.append(self.coerce(choice))
1023 except (ValueError, TypeError, ValidationError):
1024 raise ValidationError(
1025 self.error_messages["invalid_choice"],
1026 code="invalid_choice",
1027 params={"value": choice},
1028 )
1029 return new_value
1030
1031 def clean(self, value):
1032 value = super().clean(value)
1033 return self._coerce(value)
1034
1035 def validate(self, value):
1036 if value != self.empty_value:
1037 super().validate(value)
1038 elif self.required:
1039 raise ValidationError(self.error_messages["required"], code="required")
1040
1041
1042 class ComboField(Field):
1043 """
1044 A Field whose clean() method calls multiple Field clean() methods.
1045 """
1046
1047 def __init__(self, fields, **kwargs):
1048 super().__init__(**kwargs)
1049 # Set 'required' to False on the individual fields, because the
1050 # required validation will be handled by ComboField, not by those
1051 # individual fields.
1052 for f in fields:
1053 f.required = False
1054 self.fields = fields
1055
1056 def clean(self, value):
1057 """
1058 Validate the given value against all of self.fields, which is a
1059 list of Field instances.
1060 """
1061 super().clean(value)
1062 for field in self.fields:
1063 value = field.clean(value)
1064 return value
1065
1066
1067 class MultiValueField(Field):
1068 """
1069 Aggregate the logic of multiple Fields.
1070
1071 Its clean() method takes a "decompressed" list of values, which are then
1072 cleaned into a single value according to self.fields. Each value in
1073 this list is cleaned by the corresponding field -- the first value is
1074 cleaned by the first field, the second value is cleaned by the second
1075 field, etc. Once all fields are cleaned, the list of clean values is
1076 "compressed" into a single value.
1077
1078 Subclasses should not have to implement clean(). Instead, they must
1079 implement compress(), which takes a list of valid values and returns a
1080 "compressed" version of those values -- a single value.
1081
1082 You'll probably want to use this with MultiWidget.
1083 """
1084
1085 default_error_messages = {
1086 "invalid": _("Enter a list of values."),
1087 "incomplete": _("Enter a complete value."),
1088 }
1089
1090 def __init__(self, fields, *, require_all_fields=True, **kwargs):
1091 self.require_all_fields = require_all_fields
1092 super().__init__(**kwargs)
1093 for f in fields:
1094 f.error_messages.setdefault("incomplete", self.error_messages["incomplete"])
1095 if self.disabled:
1096 f.disabled = True
1097 if self.require_all_fields:
1098 # Set 'required' to False on the individual fields, because the
1099 # required validation will be handled by MultiValueField, not
1100 # by those individual fields.
1101 f.required = False
1102 self.fields = fields
1103
1104 def __deepcopy__(self, memo):
1105 result = super().__deepcopy__(memo)
1106 result.fields = tuple(x.__deepcopy__(memo) for x in self.fields)
1107 return result
1108
1109 def validate(self, value):
1110 pass
1111
1112 def clean(self, value):
1113 """
1114 Validate every value in the given list. A value is validated against
1115 the corresponding Field in self.fields.
1116
1117 For example, if this MultiValueField was instantiated with
1118 fields=(DateField(), TimeField()), clean() would call
1119 DateField.clean(value[0]) and TimeField.clean(value[1]).
1120 """
1121 clean_data = []
1122 errors = []
1123 if self.disabled and not isinstance(value, list):
1124 value = self.widget.decompress(value)
1125 if not value or isinstance(value, (list, tuple)):
1126 if not value or not [v for v in value if v not in self.empty_values]:
1127 if self.required:
1128 raise ValidationError(
1129 self.error_messages["required"], code="required"
1130 )
1131 else:
1132 return self.compress([])
1133 else:
1134 raise ValidationError(self.error_messages["invalid"], code="invalid")
1135 for i, field in enumerate(self.fields):
1136 try:
1137 field_value = value[i]
1138 except IndexError:
1139 field_value = None
1140 if field_value in self.empty_values:
1141 if self.require_all_fields:
1142 # Raise a 'required' error if the MultiValueField is
1143 # required and any field is empty.
1144 if self.required:
1145 raise ValidationError(
1146 self.error_messages["required"], code="required"
1147 )
1148 elif field.required:
1149 # Otherwise, add an 'incomplete' error to the list of
1150 # collected errors and skip field cleaning, if a required
1151 # field is empty.
1152 if field.error_messages["incomplete"] not in errors:
1153 errors.append(field.error_messages["incomplete"])
1154 continue
1155 try:
1156 clean_data.append(field.clean(field_value))
1157 except ValidationError as e:
1158 # Collect all validation errors in a single list, which we'll
1159 # raise at the end of clean(), rather than raising a single
1160 # exception for the first error we encounter. Skip duplicates.
1161 errors.extend(m for m in e.error_list if m not in errors)
1162 if errors:
1163 raise ValidationError(errors)
1164
1165 out = self.compress(clean_data)
1166 self.validate(out)
1167 self.run_validators(out)
1168 return out
1169
1170 def compress(self, data_list):
1171 """
1172 Return a single value for the given list of values. The values can be
1173 assumed to be valid.
1174
1175 For example, if this MultiValueField was instantiated with
1176 fields=(DateField(), TimeField()), this might return a datetime
1177 object created by combining the date and time in data_list.
1178 """
1179 raise NotImplementedError("Subclasses must implement this method.")
1180
1181 def has_changed(self, initial, data):
1182 if self.disabled:
1183 return False
1184 if initial is None:
1185 initial = ["" for x in range(0, len(data))]
1186 else:
1187 if not isinstance(initial, list):
1188 initial = self.widget.decompress(initial)
1189 for field, initial, data in zip(self.fields, initial, data):
1190 try:
1191 initial = field.to_python(initial)
1192 except ValidationError:
1193 return True
1194 if field.has_changed(initial, data):
1195 return True
1196 return False
1197
1198
1199 class FilePathField(ChoiceField):
1200 def __init__(
1201 self,
1202 path,
1203 *,
1204 match=None,
1205 recursive=False,
1206 allow_files=True,
1207 allow_folders=False,
1208 **kwargs,
1209 ):
1210 self.path, self.match, self.recursive = path, match, recursive
1211 self.allow_files, self.allow_folders = allow_files, allow_folders
1212 super().__init__(choices=(), **kwargs)
1213
1214 if self.required:
1215 self.choices = []
1216 else:
1217 self.choices = [("", "---------")]
1218
1219 if self.match is not None:
1220 self.match_re = re.compile(self.match)
1221
1222 if recursive:
1223 for root, dirs, files in sorted(os.walk(self.path)):
1224 if self.allow_files:
1225 for f in sorted(files):
1226 if self.match is None or self.match_re.search(f):
1227 f = os.path.join(root, f)
1228 self.choices.append((f, f.replace(path, "", 1)))
1229 if self.allow_folders:
1230 for f in sorted(dirs):
1231 if f == "__pycache__":
1232 continue
1233 if self.match is None or self.match_re.search(f):
1234 f = os.path.join(root, f)
1235 self.choices.append((f, f.replace(path, "", 1)))
1236 else:
1237 choices = []
1238 with os.scandir(self.path) as entries:
1239 for f in entries:
1240 if f.name == "__pycache__":
1241 continue
1242 if (
1243 (self.allow_files and f.is_file())
1244 or (self.allow_folders and f.is_dir())
1245 ) and (self.match is None or self.match_re.search(f.name)):
1246 choices.append((f.path, f.name))
1247 choices.sort(key=operator.itemgetter(1))
1248 self.choices.extend(choices)
1249
1250 self.widget.choices = self.choices
1251
1252
1253 class SplitDateTimeField(MultiValueField):
1254 widget = SplitDateTimeWidget
1255 hidden_widget = SplitHiddenDateTimeWidget
1256 default_error_messages = {
1257 "invalid_date": _("Enter a valid date."),
1258 "invalid_time": _("Enter a valid time."),
1259 }
1260
1261 def __init__(self, *, input_date_formats=None, input_time_formats=None, **kwargs):
1262 errors = self.default_error_messages.copy()
1263 if "error_messages" in kwargs:
1264 errors.update(kwargs["error_messages"])
1265 localize = kwargs.get("localize", False)
1266 fields = (
1267 DateField(
1268 input_formats=input_date_formats,
1269 error_messages={"invalid": errors["invalid_date"]},
1270 localize=localize,
1271 ),
1272 TimeField(
1273 input_formats=input_time_formats,
1274 error_messages={"invalid": errors["invalid_time"]},
1275 localize=localize,
1276 ),
1277 )
1278 super().__init__(fields, **kwargs)
1279
1280 def compress(self, data_list):
1281 if data_list:
1282 # Raise a validation error if time or date is empty
1283 # (possible if SplitDateTimeField has required=False).
1284 if data_list[0] in self.empty_values:
1285 raise ValidationError(
1286 self.error_messages["invalid_date"], code="invalid_date"
1287 )
1288 if data_list[1] in self.empty_values:
1289 raise ValidationError(
1290 self.error_messages["invalid_time"], code="invalid_time"
1291 )
1292 result = datetime.datetime.combine(*data_list)
1293 return from_current_timezone(result)
1294 return None
1295
1296
1297 class GenericIPAddressField(CharField):
1298 def __init__(self, *, protocol="both", unpack_ipv4=False, **kwargs):
1299 self.unpack_ipv4 = unpack_ipv4
1300 self.default_validators = validators.ip_address_validators(
1301 protocol, unpack_ipv4
1302 )
1303 kwargs.setdefault("max_length", MAX_IPV6_ADDRESS_LENGTH)
1304 super().__init__(**kwargs)
1305
1306 def to_python(self, value):
1307 if value in self.empty_values:
1308 return ""
1309 value = value.strip()
1310 if value and ":" in value:
1311 return clean_ipv6_address(
1312 value, self.unpack_ipv4, max_length=self.max_length
1313 )
1314 return value
1315
1316
1317 class SlugField(CharField):
1318 default_validators = [validators.validate_slug]
1319
1320 def __init__(self, *, allow_unicode=False, **kwargs):
1321 self.allow_unicode = allow_unicode
1322 if self.allow_unicode:
1323 self.default_validators = [validators.validate_unicode_slug]
1324 super().__init__(**kwargs)
1325
1326
1327 class UUIDField(CharField):
1328 default_error_messages = {
1329 "invalid": _("Enter a valid UUID."),
1330 }
1331
1332 def prepare_value(self, value):
1333 if isinstance(value, uuid.UUID):
1334 return str(value)
1335 return value
1336
1337 def to_python(self, value):
1338 value = super().to_python(value)
1339 if value in self.empty_values:
1340 return None
1341 if not isinstance(value, uuid.UUID):
1342 try:
1343 value = uuid.UUID(value)
1344 except ValueError:
1345 raise ValidationError(self.error_messages["invalid"], code="invalid")
1346 return value
1347
1348
1349 class InvalidJSONInput(str):
1350 pass
1351
1352
1353 class JSONString(str):
1354 pass
1355
1356
1357 class JSONField(CharField):
1358 default_error_messages = {
1359 "invalid": _("Enter a valid JSON."),
1360 }
1361 widget = Textarea
1362
1363 def __init__(self, encoder=None, decoder=None, **kwargs):
1364 self.encoder = encoder
1365 self.decoder = decoder
1366 super().__init__(**kwargs)
1367
1368 def to_python(self, value):
1369 if self.disabled:
1370 return value
1371 if value in self.empty_values:
1372 return None
1373 elif isinstance(value, (list, dict, int, float, JSONString)):
1374 return value
1375 try:
1376 converted = json.loads(value, cls=self.decoder)
1377 except json.JSONDecodeError:
1378 raise ValidationError(
1379 self.error_messages["invalid"],
1380 code="invalid",
1381 params={"value": value},
1382 )
1383 if isinstance(converted, str):
1384 return JSONString(converted)
1385 else:
1386 return converted
1387
1388 def bound_data(self, data, initial):
1389 if self.disabled:
1390 return initial
1391 if data is None:
1392 return None
1393 try:
1394 return json.loads(data, cls=self.decoder)
1395 except json.JSONDecodeError:
1396 return InvalidJSONInput(data)
1397
1398 def prepare_value(self, value):
1399 if isinstance(value, InvalidJSONInput):
1400 return value
1401 return json.dumps(value, ensure_ascii=False, cls=self.encoder)
1402
1403 def has_changed(self, initial, data):
1404 if super().has_changed(initial, data):
1405 return True
1406 # For purposes of seeing whether something has changed, True isn't the
1407 # same as 1 and the order of keys doesn't matter.
1408 return json.dumps(initial, sort_keys=True, cls=self.encoder) != json.dumps(
1409 self.to_python(data), sort_keys=True, cls=self.encoder
1410 )