[3.1.x] Fixed #28009 -- Doc'd empty_value for CharField subclasses.

smithdc1 · felixxm · commit 793bd24db6da · 2020-09-25T18:31:20.000+02:00
Backport of 91669cc from master
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
@@ -89,7 +89,8 @@ To specify that a field is *not* required, pass ``required=False`` to the
 
 If a ``Field`` has ``required=False`` and you pass ``clean()`` an empty value,
 then ``clean()`` will return a *normalized* empty value rather than raising
-``ValidationError``. For ``CharField``, this will be an empty string. For other
+``ValidationError``. For ``CharField``, this will return
+:attr:`~CharField.empty_value` which defaults to an empty string. For other
 ``Field`` classes, it might be ``None``. (This varies from field to field.)
 
 Widgets of required form fields have the ``required`` HTML attribute. Set the
@@ -582,16 +583,15 @@ For each field, we describe the default widget used if you don't specify
 .. class:: EmailField(**kwargs)
 
     * Default widget: :class:`EmailInput`
-    * Empty value: ``''`` (an empty string)
+    * Empty value: Whatever you've given as ``empty_value``.
     * Normalizes to: A string.
     * 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``.
-    If provided, these arguments ensure that the string is at most or at least the
-    given length.
+    Has three optional arguments ``max_length``, ``min_length``, and
+    ``empty_value`` which work just as they do for :class:`CharField`.
 
 ``FileField``
 -------------
@@ -919,7 +919,7 @@ For each field, we describe the default widget used if you don't specify
 .. class:: RegexField(**kwargs)
 
     * Default widget: :class:`TextInput`
-    * Empty value: ``''`` (an empty string)
+    * Empty value: Whatever you've given as ``empty_value``.
     * Normalizes to: A string.
     * Uses :class:`~django.core.validators.RegexValidator` to validate that
       the given value matches a certain regular expression.
@@ -932,8 +932,8 @@ For each field, we describe the default widget used if you don't specify
         A regular expression specified either as a string or a compiled regular
         expression object.
 
-    Also takes ``max_length``, ``min_length``, and ``strip``, which work just
-    as they do for :class:`CharField`.
+    Also takes ``max_length``, ``min_length``, ``strip``, and ``empty_value``
+    which work just as they do for :class:`CharField`.
 
     .. attribute:: strip
 
@@ -946,7 +946,7 @@ For each field, we describe the default widget used if you don't specify
 .. class:: SlugField(**kwargs)
 
    * Default widget: :class:`TextInput`
-   * Empty value: ``''`` (an empty string)
+   * Empty value: Whatever you've given as :attr:`empty_value`.
    * Normalizes to: A string.
    * Uses :class:`~django.core.validators.validate_slug` or
      :class:`~django.core.validators.validate_unicode_slug` to validate that
@@ -956,13 +956,17 @@ For each field, we describe the default widget used if you don't specify
    This field is intended for use in representing a model
    :class:`~django.db.models.SlugField` in forms.
 
-   Takes an optional parameter:
+   Takes two optional parameters:
 
    .. attribute:: allow_unicode
 
        A boolean instructing the field to accept Unicode letters in addition
        to ASCII letters. Defaults to ``False``.
 
+   .. attribute:: empty_value
+
+       The value to use to represent "empty". Defaults to an empty string.
+
 ``TimeField``
 -------------
 
@@ -994,19 +998,14 @@ For each field, we describe the default widget used if you don't specify
 .. class:: URLField(**kwargs)
 
     * Default widget: :class:`URLInput`
-    * Empty value: ``''`` (an empty string)
+    * Empty value: Whatever you've given as ``empty_value``.
     * Normalizes to: A string.
     * 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:
-
-    .. attribute:: max_length
-    .. attribute:: min_length
-
-        These are the same as ``CharField.max_length`` and
-        ``CharField.min_length``.
+    Has three optional arguments ``max_length``, ``min_length``, and
+    ``empty_value`` which work just as they do for :class:`CharField`.
 
 ``UUIDField``
 -------------
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
@@ -288,8 +288,10 @@ File Storage
 Forms
 ~~~~~
 
-* The new :attr:`CharField.empty_value <django.forms.CharField.empty_value>`
-  attribute allows specifying the Python value to use to represent "empty".
+* The new ``empty_value`` attribute on :class:`~django.forms.CharField`,
+  :class:`~django.forms.EmailField`, :class:`~django.forms.RegexField`,
+  :class:`~django.forms.SlugField`, and :class:`~django.forms.URLField` allows
+  specifying the Python value to use to represent "empty".
 
 * The new :meth:`Form.get_initial_for_field()
   <django.forms.Form.get_initial_for_field>` method returns initial data for a
