Fixed #22268 -- Documented values_list() behavior for multivalued relations.a

Thanks Sai Krishna for the initial patch.
This commit is contained in:
Iacopo Spalletti 2016-04-02 12:39:39 +02:00 committed by Tim Graham
parent 00dbd02f7e
commit 7d485d5d75
1 changed files with 24 additions and 0 deletions

View File

@ -637,6 +637,30 @@ achieve that, use ``values_list()`` followed by a ``get()`` call::
>>> Entry.objects.values_list('headline', flat=True).get(pk=1)
'First entry'
``values()`` and ``values_list()`` are both intended as optimizations for a
specific use case: retrieving a subset of data without the overhead of creating
a model instance. This metaphor falls apart when dealing with many-to-many and
other multivalued relations (such as the one-to-many relation of a reverse
foreign key) because the the "one row, one object" assumption doesn't hold.
For example, notice the behavior when querying across a
:class:`~django.db.models.ManyToManyField`::
>>> Author.objects.values_list('name', 'entry__headline')
[('Noam Chomsky', 'Impressions of Gaza'),
('George Orwell', 'Why Socialists Do Not Believe in Fun'),
('George Orwell', 'In Defence of English Cooking'),
('Don Quixote', None)]
Authors with multiple entries appear multiple times and authors without any
entries have ``None`` for the entry headline.
Similarly, when querying a reverse foreign key, ``None`` appears for entries
not having any author::
>>> Entry.objects.values_list('authors')
[('Noam Chomsky',), ('George Orwell',), (None,)]
``dates()``
~~~~~~~~~~~