Skip to content

Commit

Permalink
[3.1.x] Fixed #28009 -- Doc'd empty_value for CharField subclasses.
Browse files Browse the repository at this point in the history
Backport of 91669cc from master
  • Loading branch information
smithdc1 authored and felixxm committed Sep 25, 2020
1 parent ab8eccf commit 793bd24
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 20 deletions.
35 changes: 17 additions & 18 deletions docs/ref/forms/fields.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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``
-------------
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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``
-------------

Expand Down Expand Up @@ -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``
-------------
Expand Down
6 changes: 4 additions & 2 deletions docs/releases/1.11.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 793bd24

Please sign in to comment.