Suggestion: examples of double-underscore usage/meaning

[John Chandler]

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.

[Paul McMillan]

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.

[Gabriel Hurley]

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.