From 3fa3de54152a6b7a67de05ff4ff6fb122c9246e2 Mon Sep 17 00:00:00 2001 From: Jeff <3820914+jeffyancey@users.noreply.github.com> Date: Thu, 16 Aug 2018 17:03:28 -0400 Subject: [PATCH] Fixed #29646 -- Doc'd the validators that each model and form field uses. --- docs/ref/forms/fields.txt | 47 ++++++++++++++++++++++++-------------- docs/ref/models/fields.txt | 40 ++++++++++++++++++++++++-------- 2 files changed, 61 insertions(+), 26 deletions(-) diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 65a231d8e28..dcef5381167 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -367,8 +367,9 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`TextInput` * Empty value: Whatever you've given as :attr:`empty_value`. * Normalizes to: A string. - * Validates ``max_length`` or ``min_length``, if they are provided. - Otherwise, all inputs are valid. + * Uses :class:`~django.core.validators.MaxLengthValidator` and + :class:`~django.core.validators.MinLengthValidator` if ``max_length`` and + ``min_length`` are provided. Otherwise, all inputs are valid. * Error message keys: ``required``, ``max_length``, ``min_length`` Has three optional arguments for validation: @@ -528,8 +529,10 @@ For each field, we describe the default widget used if you don't specify ``False``, else :class:`TextInput`. * Empty value: ``None`` * Normalizes to: A Python ``decimal``. - * Validates that the given value is a decimal. Leading and trailing - whitespace is ignored. + * Validates that the given value is a decimal. Uses + :class:`~django.core.validators.MaxValueValidator` and + :class:`~django.core.validators.MinValueValidator` if ``max_value`` and + ``min_value`` are provided. Leading and trailing whitespace is ignored. * Error message keys: ``required``, ``invalid``, ``max_value``, ``min_value``, ``max_digits``, ``max_decimal_places``, ``max_whole_digits`` @@ -581,8 +584,9 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`EmailInput` * Empty value: ``''`` (an empty string) * Normalizes to: A string. - * Validates that the given value is a valid email address, using a - moderately complex regular expression. + * Uses :class:`~django.core.validators.EmailValidator` to validate that + the given value is a valid email address, using a moderately complex + regular expression. * Error message keys: ``required``, ``invalid`` Has two optional arguments for validation, ``max_length`` and ``min_length``. @@ -669,8 +673,11 @@ For each field, we describe the default widget used if you don't specify ``False``, else :class:`TextInput`. * Empty value: ``None`` * Normalizes to: A Python float. - * Validates that the given value is a float. Leading and trailing - whitespace is allowed, as in Python's ``float()`` function. + * Validates that the given value is a float. Uses + :class:`~django.core.validators.MaxValueValidator` and + :class:`~django.core.validators.MinValueValidator` if ``max_value`` and + ``min_value`` are provided. Leading and trailing whitespace is allowed, + as in Python's ``float()`` function. * Error message keys: ``required``, ``invalid``, ``max_value``, ``min_value`` @@ -686,8 +693,9 @@ For each field, we describe the default widget used if you don't specify * Empty value: ``None`` * Normalizes to: An ``UploadedFile`` object that wraps the file content and file name into a single object. - * Validates that file data has been bound to the form, and that the - file is of an image format understood by Pillow. + * Validates that file data has been bound to the form. Also uses + :class:`~django.core.validators.FileExtensionValidator` to validate that + the file extension is supported by Pillow. * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``, ``invalid_image`` @@ -718,8 +726,11 @@ For each field, we describe the default widget used if you don't specify ``False``, else :class:`TextInput`. * Empty value: ``None`` * Normalizes to: A Python integer. - * Validates that the given value is an integer. Leading and trailing - whitespace is allowed, as in Python's ``int()`` function. + * Validates that the given value is an integer. Uses + :class:`~django.core.validators.MaxValueValidator` and + :class:`~django.core.validators.MinValueValidator` if ``max_value`` and + ``min_value`` are provided. Leading and trailing whitespace is allowed, + as in Python's ``int()`` function. * Error message keys: ``required``, ``invalid``, ``max_value``, ``min_value`` @@ -824,8 +835,8 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) * Normalizes to: A string. - * Validates that the given value matches against a certain regular - expression. + * Uses :class:`~django.core.validators.RegexValidator` to validate that + the given value matches a certain regular expression. * Error message keys: ``required``, ``invalid`` Takes one required argument: @@ -851,8 +862,9 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) * Normalizes to: A string. - * Validates that the given value contains only letters, numbers, - underscores, and hyphens. + * Uses :class:`~django.core.validators.validate_slug` or + :class:`~django.core.validators.validate_unicode_slug` to validate that + the given value contains only letters, numbers, underscores, and hyphens. * Error messages: ``required``, ``invalid`` This field is intended for use in representing a model @@ -897,7 +909,8 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`URLInput` * Empty value: ``''`` (an empty string) * Normalizes to: A string. - * Validates that the given value is a valid URL. + * Uses :class:`~django.core.validators.URLValidator` to validate that the + given value is a valid URL. * Error message keys: ``required``, ``invalid`` Takes the following optional arguments: diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 94e299846d8..4abb4dddaa9 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -414,7 +414,7 @@ guaranteed to fit numbers from ``-9223372036854775808`` to ``BinaryField`` --------------- -.. class:: BinaryField(**options) +.. class:: BinaryField(max_length=None, **options) A field to store raw binary data. It only supports ``bytes`` assignment. Be aware that this field has limited functionality. For example, it is not possible @@ -427,6 +427,14 @@ case it can't be included in a :class:`~django.forms.ModelForm`. Older versions don't allow setting ``editable`` to ``True``. +``BinaryField`` has one extra optional argument: + +.. attribute:: BinaryField.max_length + + The maximum length (in characters) of the field. The maximum length is + enforced in Django's validation using + :class:`~django.core.validators.MaxLengthValidator`. + .. admonition:: Abusing ``BinaryField`` Although you might think about storing files in the database, consider that @@ -468,7 +476,8 @@ The default form widget for this field is a :class:`~django.forms.TextInput`. .. attribute:: CharField.max_length The maximum length (in characters) of the field. The max_length is enforced - at the database level and in Django's validation. + at the database level and in Django's validation using + :class:`~django.core.validators.MaxLengthValidator`. .. note:: @@ -551,7 +560,10 @@ The default form widget for this field is a single .. class:: DecimalField(max_digits=None, decimal_places=None, **options) A fixed-precision decimal number, represented in Python by a -:class:`~decimal.Decimal` instance. Has two **required** arguments: +:class:`~decimal.Decimal` instance. It validates the input using +:class:`~django.core.validators.DecimalValidator`. + +Has two **required** arguments: .. attribute:: DecimalField.max_digits @@ -603,8 +615,8 @@ SECOND(6)``. Otherwise a ``bigint`` of microseconds is used. .. class:: EmailField(max_length=254, **options) -A :class:`CharField` that checks that the value is a valid email address. It -uses :class:`~django.core.validators.EmailValidator` to validate the input. +A :class:`CharField` that checks that the value is a valid email address using +:class:`~django.core.validators.EmailValidator`. ``FileField`` ------------- @@ -969,9 +981,15 @@ The default form widget for this field is a .. class:: IntegerField(**options) An integer. Values from ``-2147483648`` to ``2147483647`` are safe in all -databases supported by Django. The default form widget for this field is a -:class:`~django.forms.NumberInput` when :attr:`~django.forms.Field.localize` -is ``False`` or :class:`~django.forms.TextInput` otherwise. +databases supported by Django. + +It uses :class:`~django.core.validators.MinValueValidator` and +:class:`~django.core.validators.MaxValueValidator` to validate the input based +on the values that the default database supports. + +The default form widget for this field is a :class:`~django.forms.NumberInput` +when :attr:`~django.forms.Field.localize` is ``False`` or +:class:`~django.forms.TextInput` otherwise. ``GenericIPAddressField`` ------------------------- @@ -1050,6 +1068,9 @@ It is often useful to automatically prepopulate a SlugField based on the value of some other value. You can do this automatically in the admin using :attr:`~django.contrib.admin.ModelAdmin.prepopulated_fields`. +It uses :class:`~django.core.validators.validate_slug` or +:class:`~django.core.validators.validate_unicode_slug` for validation. + .. attribute:: SlugField.allow_unicode If ``True``, the field accepts Unicode letters in addition to ASCII @@ -1093,7 +1114,8 @@ The admin adds some JavaScript shortcuts. .. class:: URLField(max_length=200, **options) -A :class:`CharField` for a URL. +A :class:`CharField` for a URL, validated by +:class:`~django.core.validators.URLValidator`. The default form widget for this field is a :class:`~django.forms.TextInput`.