Opened 14 years ago

Last modified 14 years ago

#15257 closed

Suggestion: examples of double-underscore usage/meaning — at Version 2

Reported by: John Chandler Owned by: nobody
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.

Change History (2)

comment:1 by Paul McMillan, 14 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, 14 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.

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