Opened 6 years ago

Closed 6 years ago

Last modified 6 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: UI/UX:

Description (last modified by Gabriel Hurley)

On this page:

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 6 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 Changed 6 years ago by Paul McMillan

Needs documentation: set
Needs tests: unset
Patch needs improvement: unset
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

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 Changed 6 years ago by Gabriel Hurley

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 Changed 6 years ago by Derek Willis

Owner: changed from nobody to Derek Willis
Status: newassigned

Changed 6 years ago by Derek Willis

Attachment: 15257.diff added

comment:4 Changed 6 years ago by Derek Willis

Has patch: set

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

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

comment:5 Changed 6 years ago by Tim Graham

Resolution: fixed
Status: assignedclosed

In [15624]:

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

comment:6 Changed 6 years ago by Tim Graham

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