queryset-refactor: Added valuelist() method to querysets. Refs #2482.

git-svn-id: http://code.djangoproject.com/svn/django/branches/queryset-refactor@7149 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 28 insertions, 0 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 61bfd31882..74adc10457 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -664,6 +664,34 @@ followed (optionally) by any output-affecting methods (such as ``values()``),
 but it doesn't really matter. This is your chance to really flaunt your
 individualism.
 
+``valueslist(*fields)``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**New in Django development version**
+
+This is similar to ``values()`` except that instead of returning a list of
+dictionaries, it returns a list of tuples. Each tuple contains the value from
+the respective field passed into the ``valueslist()`` call -- so the first
+item is the first field, etc. For example::
+
+    >>> Entry.objects.valueslist('id', 'headling')
+    [(1, u'First entry'), ...]
+
+If you only pass in a single field, you can also pass in the ``flat``
+parameter. If ``True``, this will mean the returned results are single values,
+rather than one-tuples. An example should make the difference clearer::
+
+    >>> Entry.objects.valueslist('id').order_by('id')
+    [(1,), (2,), (3,), ...]
+
+    >>> Entry.objects.valueslist('id', flat=True).order_by('id')
+    [1, 2, 3, ...]
+
+It is an error to pass in ``flat`` when there is more than one field.
+
+If you don't pass any values to ``valueslist()``, it will return all the
+fields in the model, in the order they were declared.
+
 ``dates(field, kind, order='ASC')``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~