Fixed #5275 -- Documented QuerySet.iterator(). Thanks, ubernostrum

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6303 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 5ce0aa01e7..08b5391e3c 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)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~