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).

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?