queryset-refactor: Merged to [6340]

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

1 files changed, 17 insertions, 0 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index cc235b79ed..61cf2d4ffd 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -951,6 +951,23 @@ Example::
 
 If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.
 
+``iterator()``
+~~~~~~~~~~~~
+
+Evaluates the ``QuerySet`` (by performing the query) and returns an
+`iterator`_ over the results. A ``QuerySet`` typically reads all of
+its results and instantiates all of the corresponding objects the
+first time you access it; ``iterator()`` will instead read results and
+instantiate objects in discrete chunks, yielding them one at a
+time. For a ``QuerySet`` which returns a large number of objects, this
+often results in better performance and a significant reduction in
+memory use.
+
+Note that using ``iterator()`` on a ``QuerySet`` which has already
+been evaluated will force it to evaluate again, repeating the query.
+
+.. _iterator: http://www.python.org/dev/peps/pep-0234/
+
 ``latest(field_name=None)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~