Opened 14 years ago

Closed 14 years ago

Last modified 12 years ago

#13099 closed (fixed)

Documentation: Second exclude example is incorrect

Reported by: istruble Owned by: nobody
Component: Documentation Version: 1.2-beta
Severity: Keywords:
Cc: istruble@… Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

See http://docs.djangoproject.com/en/dev/ref/models/querysets/#exclude-kwargs.

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.

Attachments (2)

ticket_13099_replace_example.diff (829 bytes ) - added by istruble 14 years ago.
ticket_13099_update_example.diff (929 bytes ) - added by istruble 14 years ago.

Download all attachments as: .zip

Change History (8)

by istruble, 14 years ago

by istruble, 14 years ago

comment:2 by Russell Keith-Magee, 14 years ago

milestone: 1.2
Triage Stage: UnreviewedReady for checkin

It's a bit hard to track exactly what sequence of events has happened here, but the SQL example should definitely read AND.

in reply to:  2 ; comment:3 by istruble, 14 years ago

Replying to russellm:

[...] the SQL example should definitely read AND.

It would be more correct to say that the current example code will generate SQL with an AND in it but this example needs code that will generate SQL with an OR in it.

I should have made it more clear that there are two examples given in this section of the documentation. The first example accurately shows exclusion with AND. The second example attempts to show exclusion with OR but the code portion of it needs attention. The intent of this ticket is to fix the second example in the section.

Erring on the side of caution, here is a rewritten problem statement.


Currently example 2 of the exclude(kwargs) section looks like this:

  • description-with-OR
  • code-with-AND-logic
  • sql-with-OR

We need to update the code so that example 2 looks like this:

  • description-with-OR
  • code-with-OR-logic
  • sql-with-OR

in reply to:  3 comment:4 by Luke Plant, 14 years ago

Replying to istruble:

Replying to russellm:

[...] the SQL example should definitely read AND.

It would be more correct to say that the current example code will generate SQL with an AND in it but this example needs code that will generate SQL with an OR in it.

The example is to demonstrate the difference between use of a single call to .exclude() with two parameters, and multiple calls to .exclude(). It is in fact only the SQL that is incorrect - the English matches the code. If I "exclude" everything matching predicate_A OR predicate_B, then I "select" everything matching NOT predicate_A AND NOT predicate_B (De Morgan's laws).

comment:5 by Luke Plant, 14 years ago

Resolution: fixed
Status: newclosed

(In [12936]) Fixed #13099 - incorrect SQL for exclude() example

Thanks to istruble for the report.

comment:6 by Jacob, 12 years ago

milestone: 1.2

Milestone 1.2 deleted

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