id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
13099	Documentation: Second exclude example is incorrect	istruble	nobody	"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 #[http://code.djangoproject.com/ticket/10631 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 #[http://code.djangoproject.com/changeset/10303#file17 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."		closed	Documentation	1.2-beta		fixed		istruble@…	Ready for checkin	1	0	0	0	0	0