Opened 10 years ago

Closed 9 years ago

#3807 closed (fixed)

errata for db-api (Database API Reference) documentation

Reported by: jon.i.austin@… Owned by: Malcolm Tredinnick
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

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'

Attachments (1)

db-api.txt.diff (1.0 KB) - added by jon.i.austin@… 9 years ago.
docs/db-api.txt fix

Download all attachments as: .zip

Change History (11)

comment:1 Changed 9 years ago by Malcolm Tredinnick

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Resolution: wontfix
Status: newclosed

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.

comment:2 Changed 9 years ago by jon.i.austin@…

Resolution: wontfix
Status: closedreopened

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

comment:3 Changed 9 years ago by Jacob

Resolution: invalid
Status: reopenedclosed

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.

comment:4 Changed 9 years ago by Chris Beaven

Resolution: invalid
Status: closedreopened
Triage Stage: UnreviewedAccepted

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

comment:5 Changed 9 years ago by Malcolm Tredinnick

Owner: changed from Jacob to Malcolm Tredinnick
Status: reopenednew

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.

comment:6 Changed 9 years ago by 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"


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

comment:7 in reply to:  5 Changed 9 years ago by 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.

Changed 9 years ago by jon.i.austin@…

Attachment: db-api.txt.diff added

docs/db-api.txt fix

comment:8 Changed 9 years ago by jon.i.austin@…

thanks for the instruction :)

comment:9 Changed 9 years ago by Chris Beaven

Has patch: set
Triage Stage: AcceptedReady for checkin

comment:10 Changed 9 years ago by Malcolm Tredinnick

Resolution: fixed
Status: newclosed

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

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