Django

Code

Ticket #3807 (closed: fixed)

Opened 1 year ago

Last modified 1 year ago

errata for db-api (Database API Reference) documentation

Reported by: jon.i.austin@gmail.com Assigned to: mtredinnick
Milestone: Component: Documentation
Version: SVN Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: 1 Needs documentation: 0
Needs tests: 0 Patch needs improvement: 0

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

db-api.txt.diff (1.0 kB) - added by jon.i.austin@gmail.com on 06/10/07 14:24:48.
docs/db-api.txt fix

Change History

05/27/07 06:44:13 changed by mtredinnick

  • status changed from new to closed.
  • needs_better_patch changed.
  • resolution set to wontfix.
  • needs_tests changed.
  • needs_docs changed.

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.

05/27/07 12:34:59 changed by jon.i.austin@gmail.com

  • status changed from closed to reopened.
  • resolution deleted.

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

06/07/07 12:59:42 changed by jacob

  • status changed from reopened to closed.
  • resolution set to invalid.

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.

06/07/07 15:31:03 changed by SmileyChris

  • status changed from closed to reopened.
  • resolution deleted.
  • 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)"

(follow-up: ↓ 7 ) 06/07/07 19:12:24 changed 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.

06/08/07 14:57:07 changed 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"

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

(in reply to: ↑ 5 ) 06/08/07 23:25:14 changed 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.

06/10/07 14:24:48 changed by jon.i.austin@gmail.com

  • attachment db-api.txt.diff added.

docs/db-api.txt fix

06/10/07 14:25:27 changed by jon.i.austin@gmail.com

thanks for the instruction :)

06/10/07 15:48:31 changed by SmileyChris

  • has_patch set to 1.
  • stage changed from Accepted to Ready for checkin.

06/11/07 06:14:05 changed by mtredinnick

  • status changed from new to closed.
  • resolution set to fixed.

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


Add/Change #3807 (errata for db-api (Database API Reference) documentation)




Change Properties
Action