[1.4.x] Fixed #18637 - Updated some documentation for aspects of models that...

Note that this is different than :attr:`~Field.null`. :attr:`~Field.null` is

purely database-related, whereas :attr:`~Field.blank` is validation-related. If

a field has ``blank=True``, validation on Django's admin site will allow entry

of an empty value. If a field has ``blank=False``, the field will be required.

a field has ``blank=True``, form validation will allow entry of an empty value.

If a field has ``blank=False``, the field will be required.

.. _field-choices:

.. attribute:: Field.choices

An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this

field.

field. If this is given, the default form widget will be a select box with

these choices instead of the standard text field.

If this is given, Django's admin will use a select box instead of the standard

text field and will limit choices to the choices given.

A choices list looks like this::

The first element in each tuple is the actual value to be stored, and the

second element is the human-readable name. For example::

    YEAR_IN_SCHOOL_CHOICES = (

        ('FR', 'Freshman'),

.. attribute:: Field.editable

If ``False``, the field will not be editable in the admin or via forms

automatically generated from the model class. Default is ``True``.

If ``False``, the field will not be displayed in the admin or any other

:class:`~django.forms.ModelForm`. Default is ``True``.

``error_messages``

------------------

.. attribute:: Field.help_text

Extra "help" text to be displayed under the field on the object's admin form.

It's useful for documentation even if your object doesn't have an admin form.

Extra "help" text to be displayed with the form widget. It's useful for

documentation even if your field isn't used on a form.

Note that this value is *not* HTML-escaped when it's displayed in the admin

interface. This lets you include HTML in :attr:`~Field.help_text` if you so

Note that this value is *not* HTML-escaped in automatically-generated

forms. This lets you include HTML in :attr:`~Field.help_text` if you so

desire. For example::

    help_text="Please use the following format: <em>YYYY-MM-DD</em>."

If ``True``, this field must be unique throughout the table.

This is enforced at the database level and at the Django admin-form level. If

This is enforced at the database level and by model validation. If

you try to save a model with a duplicate value in a :attr:`~Field.unique`

field, a :exc:`django.db.IntegrityError` will be raised by the model's

:meth:`~django.db.models.Model.save` method.

``unique_for_date="pub_date"``, then Django wouldn't allow the entry of two

records with the same ``title`` and ``pub_date``.

This is enforced at the Django admin-form level but not at the database level.

This is enforced by model validation but not at the database level.

``unique_for_month``

--------------------

A 64 bit integer, much like an :class:`IntegerField` except that it is

guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The

admin represents this as an ``<input type="text">`` (a single-line input).

default form widget for this field is a :class:`~django.forms.TextInput`.

``BooleanField``

A true/false field.

The admin represents this as a checkbox.

The default form widget for this field is a

:class:`~django.forms.CheckboxInput`.

If you need to accept :attr:`~Field.null` values then use

:class:`NullBooleanField` instead.

For large amounts of text, use :class:`~django.db.models.TextField`.

The admin represents this as an ``<input type="text">`` (a single-line input).

The default form widget for this field is a :class:`~django.forms.TextInput`.

:class:`CharField` has one extra required argument:

    for creation of timestamps. Note that the current date is *always* used;

    it's not just a default value that you can override.

The admin represents this as an ``<input type="text">`` with a JavaScript

calendar, and a shortcut for "Today". Includes an additional ``invalid_date``

error message key.

The default form widget for this field is a

:class:`~django.forms.TextInput`. The admin adds a JavaScript calendar,

and a shortcut for "Today". Includes an additional ``invalid_date`` error

message key.

.. note::

    As currently implemented, setting ``auto_now`` or ``auto_now_add`` to

A date and time, represented in Python by a ``datetime.datetime`` instance.

Takes the same extra arguments as :class:`DateField`.

The admin represents this as two ``<input type="text">`` fields, with

JavaScript shortcuts.

The default form widget for this field is a single

:class:`~django.forms.TextInput`. The admin uses two separate

:class:`~django.forms.TextInput` widgets with JavaScript shortcuts.

``DecimalField``

----------------

    models.DecimalField(..., max_digits=19, decimal_places=10)

The admin represents this as an ``<input type="text">`` (a single-line input).

The default form widget for this field is a :class:`~django.forms.TextInput`.

.. note::

    Optional. A storage object, which handles the storage and retrieval of your

    files. See :doc:`/topics/files` for details on how to provide this object.

The admin represents this field as an ``<input type="file">`` (a file-upload

widget).

The default form widget for this field is a

:class:`~django.forms.widgets.FileInput`.

Using a :class:`FileField` or an :class:`ImageField` (see below) in a model

takes a few steps:

A floating-point number represented in Python by a ``float`` instance.

The admin represents this as an ``<input type="text">`` (a single-line input).

The default form widget for this field is a :class:`~django.forms.TextInput`.

.. _floatfield_vs_decimalfield:

.. class:: IntegerField([**options])

An integer. The admin represents this as an ``<input type="text">`` (a

single-line input).

An integer. The default form widget for this field is a

:class:`~django.forms.TextInput`.

``IPAddressField``

------------------

.. class:: IPAddressField([**options])

An IP address, in string format (e.g. "192.0.2.30"). The admin represents this

as an ``<input type="text">`` (a single-line input).

An IP address, in string format (e.g. "192.0.2.30"). The default form widget

for this field is a :class:`~django.forms.TextInput`.

``GenericIPAddressField``

-------------------------

.. versionadded:: 1.4

An IPv4 or IPv6 address, in string format (e.g. ``192.0.2.30`` or

``2a02:42fe::4``). The admin represents this as an ``<input type="text">``

(a single-line input).

``2a02:42fe::4``). The default form widget for this field is a

:class:`~django.forms.TextInput`.

The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2,

including using the IPv4 format suggested in paragraph 3 of that section, like

.. class:: NullBooleanField([**options])

Like a :class:`BooleanField`, but allows ``NULL`` as one of the options. Use

this instead of a :class:`BooleanField` with ``null=True``. The admin represents

this as a ``<select>`` box with "Unknown", "Yes" and "No" choices.

this instead of a :class:`BooleanField` with ``null=True``. The default form

widget for this field is a :class:`~django.forms.NullBooleanSelect`.

``PositiveIntegerField``

------------------------

.. class:: TextField([**options])

A large text field. The admin represents this as a ``<textarea>`` (a multi-line

input).

A large text field. The default form widget for this field is a

:class:`~django.forms.Textarea`.

.. admonition:: MySQL users

A time, represented in Python by a ``datetime.time`` instance. Accepts the same

auto-population options as :class:`DateField`.

The admin represents this as an ``<input type="text">`` with some JavaScript

shortcuts.

The default form widget for this field is a :class:`~django.forms.TextInput`.

The admin adds some JavaScript shortcuts.

``URLField``

------------

    validating a URL being served by the same server will hang. This should not

    be a problem for multithreaded servers.

The admin represents this as an ``<input type="text">`` (a single-line input).

The default form widget for this field is a :class:`~django.forms.TextInput`.

Like all :class:`CharField` subclasses, :class:`URLField` takes the optional

:attr:`~CharField.max_length`argument. If you don't specify

.. attribute:: ForeignKey.limit_choices_to

    A dictionary of lookup arguments and values (see :doc:`/topics/db/queries`)

    that limit the available admin choices for this object. Use this with

    functions from the Python ``datetime`` module to limit choices of objects by

    date. For example::

    that limit the available admin or ModelForm choices for this object. Use

    this with functions from the Python ``datetime`` module to limit choices of

    objects by date. For example::

        limit_choices_to = {'pub_date__lte': datetime.now}

* The database column type (e.g. ``INTEGER``, ``VARCHAR``).

* The :doc:`widget </ref/forms/widgets>` to use in Django's admin interface,

  if you care to use it (e.g. ``<input type="text">``, ``<select>``).

* The default :doc:`widget </ref/forms/widgets>` to use when rendering a form

  field (e.g. ``<input type="text">``, ``<select>``).

* The minimal validation requirements, used in Django's admin and in

  automatically-generated forms.

    Note that this is different than :attr:`~Field.null`.

    :attr:`~Field.null` is purely database-related, whereas

    :attr:`~Field.blank` is validation-related. If a field has

    :attr:`blank=True <Field.blank>`, validation on Django's admin site will

    :attr:`blank=True <Field.blank>`, form validation will

    allow entry of an empty value. If a field has :attr:`blank=False

    <Field.blank>`, the field will be required.

:attr:`~Field.choices`

    An iterable (e.g., a list or tuple) of 2-tuples to use as choices for

    this field. If this is given, Django's admin will use a select box

    this field. If this is given, the default form widget will be a select box

    instead of the standard text field and will limit choices to the choices

    given.

        )

    The first element in each tuple is the value that will be stored in the

    database, the second element will be displayed by the admin interface,

    database, the second element will be displayed by the default form widget

    or in a ModelChoiceField. Given an instance of a model object, the

    display value for a choices field can be accessed using the

    ``get_FOO_display`` method. For example::

    created.

:attr:`~Field.help_text`

    Extra "help" text to be displayed under the field on the object's admin

    form. It's useful for documentation even if your object doesn't have an

    admin form.

    Extra "help" text to be displayed with the form widget. It's useful for

    documentation even if your field isn't used on a form.

:attr:`~Field.primary_key`

    If ``True``, this field is the primary key for the model.

:class:`~django.db.models.ManyToManyField`, but you should only put it in one

of the models -- not both.

Generally, :class:`~django.db.models.ManyToManyField` instances should go in the

object that's going to be edited in the admin interface, if you're using

Django's admin. In the above example, ``toppings`` is in ``Pizza`` (rather than

``Topping`` having a ``pizzas`` :class:`~django.db.models.ManyToManyField` )

because it's more natural to think about a pizza having toppings than a

topping being on multiple pizzas. The way it's set up above, the ``Pizza`` admin

form would let users select the toppings.

Generally, :class:`~django.db.models.ManyToManyField` instances should go in

the object that's going to be edited on a form. In the above example,

``toppings`` is in ``Pizza`` (rather than ``Topping`` having a ``pizzas``

:class:`~django.db.models.ManyToManyField` ) because it's more natural to think

about a pizza having toppings than a topping being on multiple pizzas. The way

it's set up above, the ``Pizza`` form would let users select the toppings.

.. seealso::