diff --git a/AUTHORS b/AUTHORS index 8b702fa2a4..31f95e85cf 100644 --- a/AUTHORS +++ b/AUTHORS @@ -150,6 +150,7 @@ answer newbie questions, and generally made Django that much better: bthomas btoll@bestweb.net C8E + Caio Ariede Calvin Spealman Cameron Curry Cameron Knight (ckknight) diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index a3c14f8b1b..7ca6b2c619 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -80,7 +80,7 @@ If a field has ``blank=False``, the field will be required. .. attribute:: Field.choices -An :term:`iterable` consisting itself of iterables of exactly two items (e.g. +A :term:`sequence` consisting itself of iterables of exactly two items (e.g. ``[(A, B), (A, B) ...]``) to use as choices for this field. If choices are given, they're enforced by :ref:`model validation ` and the default form widget will be a select box with these choices instead of the @@ -155,11 +155,14 @@ method to retrieve the human-readable name for the field's current value. See :meth:`~django.db.models.Model.get_FOO_display` in the database API documentation. -Note that choices can be any iterable object -- not necessarily a list or tuple. -This lets you construct choices dynamically. But if you find yourself hacking -:attr:`~Field.choices` to be dynamic, you're probably better off using a proper -database table with a :class:`ForeignKey`. :attr:`~Field.choices` is meant for -static data that doesn't change much, if ever. +Note that choices can be any sequence object -- not necessarily a list or +tuple. This lets you construct choices dynamically. But if you find yourself +hacking :attr:`~Field.choices` to be dynamic, you're probably better off using +a proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is +meant for static data that doesn't change much, if ever. + +.. note:: + A new migration is created each time the order of ``choices`` changes. Unless :attr:`blank=False` is set on the field along with a :attr:`~Field.default` then a label containing ``"---------"`` will be rendered diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 90edd682ee..4aeb318f7b 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -154,7 +154,7 @@ ones: `, the field will be required. :attr:`~Field.choices` - An :term:`iterable` of 2-tuples to use as choices for this field. If this + A :term:`sequence` of 2-tuples to use as choices for 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. @@ -168,6 +168,9 @@ ones: ('GR', 'Graduate'), ] + .. note:: + A new migration is created each time the order of ``choices`` changes. + The first element in each tuple is the value that will be stored in the database. The second element is displayed by the field's form widget.