Documentation: Second exclude example is incorrect
|Reported by:||istruble||Owned by:||nobody|
|Cc:||istruble@…||Triage Stage:||Ready for checkin|
|Has patch:||yes||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
The second example attempts to show how to create an ORed query but creates an ANDed query.
This example has been worked on a few times but is still in need of attention. Ticket #10631 requested that the example's SQL be changed. The ticket was rejected because the example SQL did in fact match up with the example code at the time. However, the code did not match up with the description. This code and description mismatch was not mentioned in the ticket.
This example excludes all entries whose ``pub_date`` is later than 2005-1-3 OR whose headline is "Hello":: Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline='Hello') In SQL terms, that evaluates to:: SELECT ... WHERE NOT pub_date > '2005-1-3' AND NOT headline = 'Hello' Note the second example is more restrictive.
The SQL was updated with commit #10303 to match the example's "OR" description. This left a mismatch between the code and description.
SELECT ... WHERE NOT pub_date > '2005-1-3' OR NOT headline = 'Hello'
This example should either have it's example code be updated so that the description, code and SQL all match up or the entire example should be replaced with a reference to the complex lookups with Q. I think it would be best to replace the example with a reference to the complex lookups with Q. Someone else may have a good reason for updating it instead of replacing it so here is an update to the example code:
Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)) | Entry.objects.exclude(headline='Hello')
Diffs for both replacing and updating the example are attached. Choose one.
Change History (8)
comment:1 Changed 7 years ago by
|Patch needs improvement:||unset|
comment:2 follow-up: 3 Changed 7 years ago by
|Triage Stage:||Unreviewed → Ready for checkin|