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

[Katya <internum.odium@…>]

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

[Baptiste Mispelon]

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

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

[Baptiste Mispelon]

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.

[Tim Graham]

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.

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

[Baptiste Mispelon]

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.

[tadeck]

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

[tadeck]

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

[tadeck]

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

[Tim Graham <timograham@…>]

In 41bea033b7e6b9d28c99f8c1ddedecad13009bd0:

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

Thanks Tomasz Jaskowski for the patch.

[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