Opened 13 years ago

Closed 13 years ago

Last modified 13 years ago

#15257 closed (fixed)

Suggestion: examples of double-underscore usage/meaning

Reported by: John Chandler Owned by: Derek Willis
Component: Documentation Version: 1.2
Severity: Keywords: syntax examples
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by Gabriel Hurley)

On this page:

http://docs.djangoproject.com/en/1.2/intro/tutorial01

this text appears:

# The API automatically follows relationships as far as you need.
# Use double underscores to separate relationships.
# This works as many levels deep as you want; there's no limit.
# Find all Choices for any poll whose pub_date is in 2007.

The use of double-underscore as a syntactic element is not familiar to me. I accept without objection that it *is* used in this context, but it is unfamiliar. Since the audience for this tutorial *probably* includes at least *some* people as ignorant as I am, maybe a separate page for some examples of how the double-underscore syntax relates to particular object references would be helpful. (E.g., "See examples _here_", linking to a page with examples, "this__that__the-other" ==> "this.that.the-other" etc.)

Since I explicitly lack experience here, my recommendation could be completely wrong; I leave that to you.

Attachments (1)

15257.diff (1.2 KB ) - added by Derek Willis 13 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 by Paul McMillan, 13 years ago

Needs documentation: set
Triage Stage: UnreviewedAccepted

I remember being confused by that same point when I read the tutorials a while ago. We should add a link to

http://docs.djangoproject.com/en/1.2/topics/db/queries/#field-lookups

right after the "Accessing model relations" link. We don't want to give new users too many links, but the existing model relations doesn't say anything about the dunder syntax, and the field lookups info is buried WAY down the queries docs.

comment:2 by Gabriel Hurley, 13 years ago

Description: modified (diff)
Needs documentation: unset

I suppose Paul's suggestion is as good a solution as any. That snippet he links to at least gives a general introduction to "this is the way it is", which is better than nothing. The reality, though, is that the double underscore is a relatively arbitrary delimiter, and is used by convention (not just in Django). I am not aware of any good links on why it's used as such.

I'll accept a patch as per Paul's comment, though.

comment:3 by Derek Willis, 13 years ago

Owner: changed from nobody to Derek Willis
Status: newassigned

by Derek Willis, 13 years ago

Attachment: 15257.diff added

comment:4 by Derek Willis, 13 years ago

Has patch: set

Added patch with link to Field lookup per PaulM's suggestion.

Last edited 13 years ago by Derek Willis (previous) (diff)

comment:5 by Tim Graham, 13 years ago

Resolution: fixed
Status: assignedclosed

In [15624]:

Fixed #15257 - Add a link about field lookups to the tutorial; thanks dwillis.

comment:6 by Tim Graham, 13 years ago

In [15625]:

[1.2.X] Fixed #15257 - Add a link about field lookups to the tutorial; thanks dwillis.

Backport of r15624 from trunk.

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