Opened 9 years ago

Closed 9 years ago

Last modified 9 years ago

#23732 closed Bug (fixed)

select_related() documentation examples use incorrect fieldnames, and are slightly misleading

Reported by: Daniele Procida Owned by: Tim Graham
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

https://docs.djangoproject.com/en/dev/ref/models/querysets/#django.db.models.query.QuerySet.select_related says that if you have the models

class City(models.Model):
    # ...
    pass

class Person(models.Model):
    # ...
    hometown = models.ForeignKey(City)

class Book(models.Model):
    # ...
    author = models.ForeignKey(Person)

then you can do a Book.objects.select_related('person__city').get(id=4) .

But in fact that, and the other examples that follow, should be using select_related('author__hometown') (the names of the fields, rather than of the models they refer to).

These examples should be changed.

A related issue in the same section: the examples might lead one to believe that select_related works only when retrieving a single item with get() (unlike prefetch_related, whose examples involve retrieving multiple objects), whereas this is not in fact the case.

An example using filter() or some more explicit wording in the description (or both) would help here.

Attachments (1)

23732.diff (1.5 KB ) - added by Tim Graham 9 years ago.

Download all attachments as: .zip

Change History (6)

comment:1 by Tim Graham, 9 years ago

Triage Stage: UnreviewedAccepted

comment:2 by Tim Graham, 9 years ago

Owner: changed from nobody to Tim Graham
Status: newassigned

by Tim Graham, 9 years ago

Attachment: 23732.diff added

comment:3 by Tim Graham, 9 years ago

Has patch: set

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

Resolution: fixed
Status: assignedclosed

In e958c760f90672e6d1422fb5509f64c12527a451:

Fixed #23732 -- Corrected and enhanced select_related() docs.

Thanks Daniele Procida for the report and review.

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

In e876c7f1ee4e0f071f7920b729829a3373ce2a9b:

[1.7.x] Fixed #23732 -- Corrected and enhanced select_related() docs.

Thanks Daniele Procida for the report and review.

Backport of e958c760f9 from master

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