Fixed #24561 -- Added support for callables on model fields' choices.

2 files changed, 37 insertions, 7 deletions

diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index a41eb7b1d2..7ad9f77741 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -115,9 +115,32 @@ human-readable name. For example::
         ("GR", "Graduate"),
     ]
 
+``choices`` can also be defined as a callable that expects no arguments and
+returns any of the formats described above. For example::
+
+    def get_currencies():
+        return {i: i for i in settings.CURRENCIES}
+
+
+    class Expense(models.Model):
+        amount = models.DecimalField(max_digits=10, decimal_places=2)
+        currency = models.CharField(max_length=3, choices=get_currencies)
+
+Passing a callable for ``choices`` can be particularly handy when, for example,
+the choices are:
+
+* the result of I/O-bound operations (which could potentially be cached), such
+  as querying a table in the same or an external database, or accessing the
+  choices from a static file.
+
+* a list that is mostly stable but could vary from time to time or from
+  project to project. Examples in this category are using third-party apps that
+  provide a well-known inventory of values, such as currencies, countries,
+  languages, time zones, etc.
+
 .. versionchanged:: 5.0
 
-    Support for mappings was added.
+    Support for mappings and callables was added.
 
 Generally, it's best to define choices inside a model class, and to
 define a suitably-named constant for each value::
diff --git a/docs/releases/5.0.txt b/docs/releases/5.0.txt
index 5a82c342c0..186768f070 100644
--- a/docs/releases/5.0.txt
+++ b/docs/releases/5.0.txt
@@ -157,14 +157,14 @@ form::
     ]
 
 
-    class Winners(models.Model):
+    class Winner(models.Model):
         name = models.CharField(...)
         medal = models.CharField(..., choices=Medal.choices)
         sport = models.CharField(..., choices=SPORT_CHOICES)
 
-Django 5.0 supports providing a mapping instead of an iterable, and also no
-longer requires ``.choices`` to be used directly to expand :ref:`enumeration
-types <field-choices-enum-types>`::
+Django 5.0 adds support for accepting a mapping or a callable instead of an
+iterable, and also no longer requires ``.choices`` to be used directly to
+expand :ref:`enumeration types <field-choices-enum-types>`::
 
     from django.db import models
 
@@ -177,13 +177,20 @@ types <field-choices-enum-types>`::
     }
 
 
-    class Winners(models.Model):
+    def get_scores():
+        return [(i, str(i)) for i in range(10)]
+
+
+    class Winner(models.Model):
         name = models.CharField(...)
         medal = models.CharField(..., choices=Medal)  # Using `.choices` not required.
         sport = models.CharField(..., choices=SPORT_CHOICES)
+        score = models.IntegerField(choices=get_scores)  # A callable is allowed.
 
 Under the hood the provided ``choices`` are normalized into a list of 2-tuples
-as the canonical form whenever the ``choices`` value is updated.
+as the canonical form whenever the ``choices`` value is updated. For more
+information, please check the :ref:`model field reference on choices
+<field-choices>`.
 
 Minor features
 --------------