diff options
Diffstat (limited to 'docs/ref/models')
| -rw-r--r-- | docs/ref/models/conditional-expressions.txt | 10 | ||||
| -rw-r--r-- | docs/ref/models/fields.txt | 80 | ||||
| -rw-r--r-- | docs/ref/models/instances.txt | 10 |
3 files changed, 65 insertions, 35 deletions
diff --git a/docs/ref/models/conditional-expressions.txt b/docs/ref/models/conditional-expressions.txt index d14312870f..cfdbd0790a 100644 --- a/docs/ref/models/conditional-expressions.txt +++ b/docs/ref/models/conditional-expressions.txt @@ -22,11 +22,11 @@ We'll be using the following model in the subsequent examples:: REGULAR = "R" GOLD = "G" PLATINUM = "P" - ACCOUNT_TYPE_CHOICES = [ - (REGULAR, "Regular"), - (GOLD, "Gold"), - (PLATINUM, "Platinum"), - ] + ACCOUNT_TYPE_CHOICES = { + REGULAR: "Regular", + GOLD: "Gold", + PLATINUM: "Platinum", + } name = models.CharField(max_length=50) registered_on = models.DateField() account_type = models.CharField( diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index ff67312949..fbc90e5420 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -86,14 +86,26 @@ If a field has ``blank=False``, the field will be required. .. attribute:: Field.choices -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 <validating-objects>` and the -default form widget will be a select box with these choices instead of the -standard text field. +A mapping or iterable in the format described below to use as choices for this +field. If choices are given, they're enforced by +:ref:`model validation <validating-objects>` and the default form widget will +be a select box with these choices instead of the standard text field. -The first element in each tuple is the actual value to be set on the model, -and the second element is the human-readable name. For example:: +If a mapping is given, the key element is the actual value to be set on the +model, and the second element is the human readable name. For example:: + + YEAR_IN_SCHOOL_CHOICES = { + "FR": "Freshman", + "SO": "Sophomore", + "JR": "Junior", + "SR": "Senior", + "GR": "Graduate", + } + +You can also pass a :term:`sequence` consisting itself of iterables of exactly +two items (e.g. ``[(A1, B1), (A2, B2), …]``). The first element in each tuple +is the actual value to be set on the model, and the second element is the +human-readable name. For example:: YEAR_IN_SCHOOL_CHOICES = [ ("FR", "Freshman"), @@ -103,6 +115,10 @@ and the second element is the human-readable name. For example:: ("GR", "Graduate"), ] +.. versionchanged:: 5.0 + + Support for mappings was added. + Generally, it's best to define choices inside a model class, and to define a suitably-named constant for each value:: @@ -115,13 +131,13 @@ define a suitably-named constant for each value:: JUNIOR = "JR" SENIOR = "SR" GRADUATE = "GR" - YEAR_IN_SCHOOL_CHOICES = [ - (FRESHMAN, "Freshman"), - (SOPHOMORE, "Sophomore"), - (JUNIOR, "Junior"), - (SENIOR, "Senior"), - (GRADUATE, "Graduate"), - ] + YEAR_IN_SCHOOL_CHOICES = { + FRESHMAN: "Freshman", + SOPHOMORE: "Sophomore", + JUNIOR: "Junior", + SENIOR: "Senior", + GRADUATE: "Graduate", + } year_in_school = models.CharField( max_length=2, choices=YEAR_IN_SCHOOL_CHOICES, @@ -142,6 +158,25 @@ will work anywhere that the ``Student`` model has been imported). You can also collect your available choices into named groups that can be used for organizational purposes:: + MEDIA_CHOICES = { + "Audio": { + "vinyl": "Vinyl", + "cd": "CD", + }, + "Video": { + "vhs": "VHS Tape", + "dvd": "DVD", + }, + "unknown": "Unknown", + } + +The key of the mapping is the name to apply to the group and the value is the +choices inside that group, consisting of the field value and a human-readable +name for an option. Grouped options may be combined with ungrouped options +within a single mapping (such as the ``"unknown"`` option in this example). + +You can also use a sequence, e.g. a list of 2-tuples:: + MEDIA_CHOICES = [ ( "Audio", @@ -160,17 +195,6 @@ be used for organizational purposes:: ("unknown", "Unknown"), ] -The first element in each tuple is the name to apply to the group. The -second element is an iterable of 2-tuples, with each 2-tuple containing -a value and a human-readable name for an option. Grouped options may be -combined with ungrouped options within a single list (such as the -``'unknown'`` option in this example). - -For each model field that has :attr:`~Field.choices` set, Django will add a -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 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 @@ -180,6 +204,12 @@ meant for static data that doesn't change much, if ever. .. note:: A new migration is created each time the order of ``choices`` changes. +For each model field that has :attr:`~Field.choices` set, Django will normalize +the choices to a list of 2-tuples and add a 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. + .. _field-choices-blank-label: Unless :attr:`blank=False<Field.blank>` is set on the field along with a diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 6bfd521aaa..6ceb0703ab 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -912,11 +912,11 @@ For example:: class Person(models.Model): - SHIRT_SIZES = [ - ("S", "Small"), - ("M", "Medium"), - ("L", "Large"), - ] + SHIRT_SIZES = { + "S": "Small", + "M": "Medium", + "L": "Large", + } name = models.CharField(max_length=60) shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES) |