Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#10291 closed (fixed)

Correction to QuerySet.iterator() documentation

Reported by: ikelly Owned by: nobody
Component: Documentation Version: master
Severity: Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

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

Attachments (1)

10291.diff (1.3 KB) - added by ikelly 7 years ago.

Download all attachments as: .zip

Change History (9)

Changed 7 years ago by ikelly

comment:1 Changed 7 years ago by Alex

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

comment:2 Changed 6 years ago by timo

  • Has patch set
  • Triage Stage changed from Accepted to Ready for checkin

looks like a nice clarification to me

comment:3 Changed 6 years ago by adrian

  • Resolution set to invalid
  • Status changed from new to closed

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

comment:4 Changed 6 years ago by ikelly

  • Resolution invalid deleted
  • Status changed from closed to reopened

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?

comment:5 Changed 6 years ago by lukeplant

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.

comment:6 Changed 6 years ago by lukeplant

  • Resolution set to fixed
  • Status changed from reopened to closed

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

comment:7 Changed 6 years ago by lukeplant

(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

comment:8 Changed 6 years ago by lukeplant

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

Note: See TracTickets for help on using tickets.
Back to Top