From eefc88feefec0c3685bfb102714530b751b4ae90 Mon Sep 17 00:00:00 2001 From: Christopher Adams Date: Sat, 1 Feb 2014 14:23:31 -0500 Subject: Fixed #2445 -- Allowed limit_choices_to attribute to be a callable. ForeignKey or ManyToManyField attribute ``limit_choices_to`` can now be a callable that returns either a ``Q`` object or a dict. Thanks michael at actrix.gen.nz for the original suggestion. --- docs/ref/models/fields.txt | 46 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 35 insertions(+), 11 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index d4f0c1a450..cecfddca5f 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -1078,21 +1078,45 @@ define the details of how the relation works. .. attribute:: ForeignKey.limit_choices_to - A dictionary of lookup arguments and values (see :doc:`/topics/db/queries`) - that limit the available admin or :class:`ModelForm ` - choices for this object. For example:: + Sets a limit to the available choices for this field when this field is + rendered using a ``ModelForm`` or the admin (by default, all objects + in the queryset are available to choose). Either a dictionary, a + :class:`~django.db.models.Q` object, or a callable returning a + dictionary or :class:`~django.db.models.Q` object can be used. + + For example:: staff_member = models.ForeignKey(User, limit_choices_to={'is_staff': True}) causes the corresponding field on the ``ModelForm`` to list only ``Users`` - that have ``is_staff=True``. - - Instead of a dictionary this can also be a :class:`Q object - ` for more :ref:`complex queries - `. However, if ``limit_choices_to`` is a :class:`Q - object ` then it will only have an effect on the - choices available in the admin when the field is not listed in - ``raw_id_fields`` in the ``ModelAdmin`` for the model. + that have ``is_staff=True``. This may be helpful in the Django admin. + + The callable form can be helpful, for instance, when used in conjunction + with the Python ``datetime`` module to limit selections by date range. For + example:: + + limit_choices_to = lambda: {'pub_date__lte': datetime.date.utcnow()} + + If ``limit_choices_to`` is or returns a :class:`Q object + `, which is useful for :ref:`complex queries + `, then it will only have an effect on the choices + available in the admin when the field is not listed in + :attr:`~django.contrib.admin.ModelAdmin.raw_id_fields` in the + ``ModelAdmin`` for the model. + + .. versionchanged:: 1.7 + + Previous versions of Django do not allow passing a callable as a value + for ``limit_choices_to``. + + .. note:: + + If a callable is used for ``limit_choices_to``, it will be invoked + every time a new form is instantiated. It may also be invoked when a + model is validated, for example by management commands or the admin. + The admin constructs querysets to validate its form inputs in various + edge cases multiple times, so there is a possibility your callable may + be invoked several times. .. attribute:: ForeignKey.related_name -- cgit v1.3