From 691f70c47755c7f55fa75ce607d028f81468b745 Mon Sep 17 00:00:00 2001
From: Natalia <124304+nessita@users.noreply.github.com>
Date: Thu, 31 Aug 2023 09:09:30 -0300
Subject: Fixed #24561 -- Added support for callables on model fields' choices.

---
 docs/ref/models/fields.txt | 25 ++++++++++++++++++++++++-
 docs/releases/5.0.txt      | 19 +++++++++++++------
 2 files changed, 37 insertions(+), 7 deletions(-)

(limited to 'docs')

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
 --------------
-- 
cgit v1.3