Code

Opened 3 years ago

Closed 3 years ago

Last modified 3 years ago

#15257 closed (fixed)

Suggestion: examples of double-underscore usage/meaning

Reported by: MixedContent Owned by: dwillis
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 gabrielhurley)

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 dwillis 3 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 Changed 3 years ago by PaulM

  • Needs documentation set
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

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 Changed 3 years ago by gabrielhurley

  • 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 3 years ago by dwillis

  • Owner changed from nobody to dwillis
  • Status changed from new to assigned

Changed 3 years ago by dwillis

comment:4 Changed 3 years ago by dwillis

  • Has patch set
Version 0, edited 3 years ago by dwillis (next)

comment:5 Changed 3 years ago by timo

  • Resolution set to fixed
  • Status changed from assigned to closed

In [15624]:

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

comment:6 Changed 3 years ago by timo

In [15625]:

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

Backport of r15624 from trunk.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.