errata for db-api (Database API Reference) documentation

[jon.i.austin@…]

In the below text there appears to be a few errors:

fixes preceded by >>

This example excludes all entries whose pub_date is the current date/time AND whose headline is “Hello”:
>> s#the current date/time#later than 2005-1-3#

Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline='Hello')

In SQL terms, that evaluates to:

SELECT ...
WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')

This example excludes all entries whose pub_date is the current date/time OR whose headline is “Hello”:
>> s#the current date/time OR whose headline is "Hello"#later than 2005-1-3 AND whose headline is NOT "Hello"#
>> the below code means: get all rows whose pub_date is not later then 2005-1-3 and then query THAT queryset for all headlines which are not equal to Hello -- so it should be 'exclude all entries whose pub_date is later than 2005-1-3 AND whose headline is not "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'

[Malcolm Tredinnick]

Not worth changing. I don't think any reader is going to have trouble understanding that it refers to the moment the tutorial was written.

[jon.i.austin@…]

hi,

umm, the 2005 date has nothing to do with it, the real issue is the that the description and the actual meaning of the code statement (i.e. SQL) do not agree.
Please read the bug again and you'll see what I mean.

thanks,
jon

[Jacob]

Like Malcolm, I can't figure out what you're talking about here. Please resubmit this as a proper patch (​http://www.djangoproject.com/documentation/contributing/#submitting-patches) if it's still an issue.

[Chris Beaven]

It's a valid ticket (albiet with a confusing description)

​http://www.djangoproject.com/documentation/db-api/#exclude-kwargs

The documentation text alludes to finding records where "pub_date is the current date/time" but the code mentions "pub_date__gt=datetime.date(2005, 1, 3)"

[Malcolm Tredinnick]

No, Chris, that's not the bug. There's an "or" that needs to be replaced by an "and". I worked out what the important difference mentioned was at one point. I'll work it out again in the near future and commit it.

[anonymous]

Hi, sorry if my explanation wasn't clear. The changes are simply this:

1. In the line that says: This example excludes all entries whose pub_date is the current date/time AND whose headline is "Hello"

change: "the current date/time"

to: "later than 2005-1-3"

2. In the line that says: This example excludes all entries whose pub_date is the current date/time OR whose headline is "Hello":

change: "the current date/time OR whose headline is "Hello""

to: "later than 2005-1-3 AND whose headline is NOT "Hello""


hope that makes more sense :)

to clear up the original comment a bit: (the s#xxx#xxx# is the substitution operator from perl -- sorry, been doing a lot of perl coding lately)

jon

[Chris Beaven]

Replying to mtredinnick:

No, Chris, that's not the bug.

Turns out we were both right ;)

Jon: The best way to show what needs to be changed is to change your local copy, make a diff file of the changes, and attach that.

[jon.i.austin@…]

docs/db-api.txt fix

[jon.i.austin@…]

thanks for the instruction :)

[Malcolm Tredinnick]

(In [5458]) Fixed #3807 -- Some small fixes to a couple of examples. Thanks,
jon.i.austin@….