Browse Source

Fixed #29646 -- Doc'd the validators that each model and form field uses.

Jeff 6 years ago
parent
commit
3fa3de5415
2 changed files with 61 additions and 26 deletions
  1. 30 17
      docs/ref/forms/fields.txt
  2. 31 9
      docs/ref/models/fields.txt

+ 30 - 17
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:

+ 31 - 9
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`.