Code

Opened 16 months ago

Closed 14 months ago

Last modified 14 months ago

#20183 closed Cleanup/optimization (fixed)

"Making Queries" documentation assumes an Entry instance has already been created.

Reported by: Katya <internum.odium@…> Owned by: Tim Graham <timograham@…>
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: bmispelon@…, tadeck Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

https://docs.djangoproject.com/en/1.5/topics/db/queries/#saving-foreignkey-and-manytomanyfield-fields

>>> entry = Entry.objects.get(pk=1)

I couldn't find where the Entry object with pk=1 gets assigned, so I predictably get an error when trying to run this line of code.

Attachments (1)

1171.diff (740 bytes) - added by tadeck 14 months ago.
DIFF for fix in ticket #20183 (pull request no. 1171)

Download all attachments as: .zip

Change History (12)

comment:1 Changed 16 months ago by bmispelon

  • Cc bmispelon@… added
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to invalid
  • Status changed from new to closed

Hi,

This tracker is for reporting bugs. For support, you should try the mailing-list django-users or the IRC channel.

See https://docs.djangoproject.com/en/1.5/faq/help/#how-do-i-do-x-why-doesn-t-y-work-where-can-i-go-to-get-help

As for your report, I'm not sure exactly what problems you're running into.

The Entry model is defined a bit higher in the page

The objects attribute is a manager, whose behavior is defined in the documentation: https://docs.djangoproject.com/en/1.5/topics/db/managers/.

Finally, the get method on querysets is described there: https://docs.djangoproject.com/en/1.5/ref/models/querysets/#get

comment:2 Changed 16 months ago by Katya <internum.odium@…>

>>> entry = Entry.objects.get(pk=1)

At that point there are no objects in Entry. The same goes for the object with the name "Cheddar Talk" in Blog:

>>> cheese_blog = Blog.objects.get(name="Cheddar Talk")

That would be nice to add lines creating those objects or, if they are created somewhere else in documentation, put a reference to that place.

comment:3 Changed 16 months ago by bmispelon

  • Resolution invalid deleted
  • Status changed from closed to new
  • Summary changed from Can't find where the object gets assigned before use to "Making Queries" documentation assumes an Entry instance has already been created.
  • Triage Stage changed from Unreviewed to Accepted

Ah, I understand what you mean now.

You're right, this part of the documentation assumes that an Entry has already been created, which is confusing and not obvious.

I'm re-opening the ticket and accepting.

comment:4 follow-up: Changed 16 months ago by timo

The examples aren't designed to be run verbatim, they are merely hypothetical queries you could run given some set of objects. I think it would actually introduce a lot of cruft, overhead, and confusion if we ensured you could run the entire page top to bottom. Maybe we should add a note about that, but this page has existed for several years without this being an issue so I'm inclined to won't fix.

comment:5 in reply to: ↑ 4 Changed 16 months ago by Katya <internum.odium@…>

Replying to timo:

The examples aren't designed to be run verbatim, they are merely hypothetical queries you could run given some set of objects. I think it would actually introduce a lot of cruft, overhead, and confusion if we ensured you could run the entire page top to bottom. Maybe we should add a note about that, but this page has existed for several years without this being an issue so I'm inclined to won't fix.

Thanks a lot for your answer and sorry for disturbing! A note would be appreciated.

comment:6 Changed 16 months ago by bmispelon

I agree with the fact that creating an Entry instance beforehand would add a lot of noise to the page (especially considering all its fields are required).

As for the examples not being designed to be run verbatim, it's not that obvious to me:

First, the use of the prompt >>> encourages users to try things out in a shell so one might assume that the code is self-sufficient (by the way, the use of this prompt is not consistent throughout the whole page).

Second, most examples import their models before use, which again hints at the fact that the code is self-sufficient (later examples assume that the datetime module has been imported by the user, without explicitely doing so).

Finally, in the previous section, there's a note saying "Given a Blog instance b5 that has already been saved to the database[...]". Why not add the same kind of note in this section as well?

---

Overall though, I think this page is meant as a reference, not as a tutorial so one shouldn't expect to be able to just run the code as is.

However, the copious amount of examples (which is a good thing I believe) and the lack of a warning could confuse someone expecting a tutorial-like documentation so maybe adding a note at the top could be beneficial.

comment:7 Changed 15 months ago by anonymous

  • Type changed from Uncategorized to Cleanup/optimization

comment:8 Changed 14 months ago by tadeck

  • Owner changed from nobody to tadeck
  • Status changed from new to assigned
  • Version changed from 1.5 to master

Will add proper note.

Choosing between blurring the important part (by adding code for creation of the entity) and not being able to just copy & paste the code that "just works"(TM), I would try to solve that on the user interface. Something like expandable details (unnecessary to understand the content, but useful for real beginners) would be great, but I do not think there is anything like that in the current documentation (thus adding the note seems to be least problematic).

Changed 14 months ago by tadeck

DIFF for fix in ticket #20183 (pull request no. 1171)

comment:9 Changed 14 months ago by tadeck

  • Cc tadeck added
  • Has patch set
  • Owner tadeck deleted
  • Status changed from assigned to new

The patch is ready for review as pull request: https://github.com/django/django/pull/1171

comment:10 Changed 14 months ago by Tim Graham <timograham@…>

  • Owner set to Tim Graham <timograham@…>
  • Resolution set to fixed
  • Status changed from new to closed

In 41bea033b7e6b9d28c99f8c1ddedecad13009bd0:

Fixed #20183 - Clarified docs assumption that certain objects exist in database.

Thanks Tomasz Jaskowski for the patch.

comment:11 Changed 14 months ago by Tim Graham <timograham@…>

In 66005c643c806995ff8430f1b66a3fb779418de0:

[1.5.X] Fixed #20183 - Clarified docs assumption that certain objects exist in database.

Thanks Tomasz Jaskowski for the patch.

Backport of 41bea033b7 from master

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.