Opened 8 years ago

Closed 8 years ago

#3807 closed (fixed)

errata for db-api (Database API Reference) documentation

Reported by: jon.i.austin@… Owned by: mtredinnick
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@… 8 years ago.
docs/db-api.txt fix

Download all attachments as: .zip

Change History (11)

comment:1 Changed 8 years ago by mtredinnick

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to wontfix
  • Status changed from new to closed

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 8 years ago by jon.i.austin@…

  • Resolution wontfix deleted
  • Status changed from closed to reopened

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 8 years ago by jacob

  • Resolution set to invalid
  • Status changed from reopened to closed

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 8 years ago by SmileyChris

  • Resolution invalid deleted
  • Status changed from closed to reopened
  • Triage Stage changed from Unreviewed to Accepted

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 follow-up: Changed 8 years ago by mtredinnick

  • Owner changed from jacob to mtredinnick
  • Status changed from reopened to new

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 8 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 8 years ago by SmileyChris

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 8 years ago by jon.i.austin@…

docs/db-api.txt fix

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

thanks for the instruction :)

comment:9 Changed 8 years ago by SmileyChris

  • Has patch set
  • Triage Stage changed from Accepted to Ready for checkin

comment:10 Changed 8 years ago by mtredinnick

  • Resolution set to fixed
  • Status changed from new to closed

(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