Opened 11 years ago

Closed 11 years ago

Last modified 11 years 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: dev
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 11 years ago.
DIFF for fix in ticket #20183 (pull request no. 1171)

Download all attachments as: .zip

Change History (12)

comment:1 by Baptiste Mispelon, 11 years ago

Cc: bmispelon@… added
Resolution: invalid
Status: newclosed

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 by Katya <internum.odium@…>, 11 years ago

>>> 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 by Baptiste Mispelon, 11 years ago

Resolution: invalid
Status: closednew
Summary: Can't find where the object gets assigned before use"Making Queries" documentation assumes an Entry instance has already been created.
Triage Stage: UnreviewedAccepted

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 by Tim Graham, 11 years ago

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.

in reply to:  4 comment:5 by Katya <internum.odium@…>, 11 years ago

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 by Baptiste Mispelon, 11 years ago

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 by anonymous, 11 years ago

Type: UncategorizedCleanup/optimization

comment:8 by tadeck, 11 years ago

Owner: changed from nobody to tadeck
Status: newassigned
Version: 1.5master

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).

by tadeck, 11 years ago

Attachment: 1171.diff added

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

comment:9 by tadeck, 11 years ago

Cc: tadeck added
Has patch: set
Owner: tadeck removed
Status: assignednew

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

comment:10 by Tim Graham <timograham@…>, 11 years ago

Owner: set to Tim Graham <timograham@…>
Resolution: fixed
Status: newclosed

In 41bea033b7e6b9d28c99f8c1ddedecad13009bd0:

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

Thanks Tomasz Jaskowski for the patch.

comment:11 by Tim Graham <timograham@…>, 11 years ago

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

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