Fixed #5768 -- Added support for ManyToManyFields and reverse relations in values() and values_list(). Thanks to mrmachine for the patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14655 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 23 insertions, 4 deletions

diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 5659579955..ccea5884ed 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -398,11 +398,8 @@ Example::
     >>> Blog.objects.values('id', 'name')
     [{'id': 1, 'name': 'Beatles Blog'}]
 
-A couple of subtleties that are worth mentioning:
+A few subtleties that are worth mentioning:
 
-    * The ``values()`` method does not return anything for
-      :class:`~django.db.models.ManyToManyField` attributes and will raise an
-      error if you try to pass in this type of field to it.
     * If you have a field called ``foo`` that is a
       :class:`~django.db.models.ForeignKey`, the default ``values()`` call
       will return a dictionary key called ``foo_id``, since this is the name
@@ -453,6 +450,28 @@ 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.
 
+.. versionchanged:: 1.3
+
+The ``values()`` method previously did not return anything for
+:class:`~django.db.models.ManyToManyField` attributes and would raise an error
+if you tried to pass this type of field to it.
+
+This restriction has been lifted, and you can now also refer to fields on
+related models with reverse relations through ``OneToOneField``, ``ForeignKey``
+and ``ManyToManyField`` attributes::
+
+	Blog.objects.values('name', 'entry__headline')
+	[{'name': 'My blog', 'entry__headline': 'An entry'},
+         {'name': 'My blog', 'entry__headline': 'Another entry'}, ...]
+
+.. warning::
+
+   Because :class:`~django.db.models.ManyToManyField` attributes and reverse
+   relations can have multiple related rows, including these can have a
+   multiplier effect on the size of your result set. This will be especially
+   pronounced if you include multiple such fields in your ``values()`` query,
+   in which case all possible combinations will be returned.
+
 ``values_list(*fields)``
 ~~~~~~~~~~~~~~~~~~~~~~~~