Correction to QuerySet.iterator() documentation

[Erin Kelly]

A revision to the documentation for the QuerySet.iterator() method that better reflects how it behaves differently from normal evaluation.

[Tim Graham]

looks like a nice clarification to me

[Adrian Holovaty]

I'm not sure this documentation change is correct/appropriate. The point of iterator() is to do the query in chunks (as explained in the current document), not to avoid caching (as explained in the patch).

[Erin Kelly]

Reopening because I think Adrian's determination is incorrect. If I'm missing something, let me know and I'll drop it.

It's true that iterator() fetches the query result in chunks, but normal evaluation using __iter__() also fetches the query result in chunks. Also, any function applied to the result of __iter__() that causes everything to be fetched will do the same when applied to the result of iterator().

In fact, __iter__() invokes iterator() behind the scenes to do the heavy lifting. The only thing it does differently is that it makes use of and fills the QuerySet's _result_cache over the course of iteration. So if iterator() is merely meant to fetch the query result in chunks, why is it even included in the public API when __iter__() already accomplishes this?

[Luke Plant]

Looking at the current code, I'm with ikelly on this one, I happened to be looking at this just now. The only thing that changes if you switch to iterator() is that your results will not be cached.

[Luke Plant]

(In [12229]) Created a 'DB optimization' topic, with cross-refs to relevant sections.

Also fixed #10291, which was related, and cleaned up some inconsistent doc labels.

[Luke Plant]

(In [12230]) [1.1.X] Created a 'DB optimization' topic, with cross-refs to relevant sections.

Also fixed #10291, which was related, and cleaned up some inconsistent doc labels.

Backport of r12229 from trunk

[Luke Plant]

Oops, meant to says "thanks ikelly" in that commit message, seeing as I used your patch wholesale. Cheers.