Fixed #31262 -- Added support for mappings on model fields and ChoiceField's choices.

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(

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

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)