Opened 3 months ago

Closed 3 months ago

Last modified 3 months ago

#31591 closed Cleanup/optimization (fixed)

Spanning relationship backwards when related_name is used.

Reported by: Nat S Dunn Owned by: Carlton Gibson
Component: Documentation Version: 3.0
Severity: Normal Keywords: related_name
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

Under https://docs.djangoproject.com/en/3.0/topics/db/queries/#lookups-that-span-relationships, the documentation says:

It works backwards, too. To refer to a “reverse” relationship, use the lowercase name of the model.

This works only if the name of that relationship hasn't been changed with related_name.

I suggest updating the doc to read:

It works backwards, too. To refer to a “reverse” relationship, use the lowercase name of the model, unless you have used related_name to override the name of the relationship, in which case you should use the related_name you have set.

Change History (3)

comment:1 Changed 3 months ago by Carlton Gibson

Has patch: set
Owner: changed from nobody to Carlton Gibson
Status: newassigned
Triage Stage: UnreviewedAccepted

OK, yes. Good spot.

The docs should probably cross-reference https://docs.djangoproject.com/en/3.0/topics/db/queries/#following-relationships-backward related_query_name here.

At the least it's lowercased + _set, so correcting the examples to match the sample models at the top would probably also ease confusion.

PR

Update: It's the lookup, rather than the reverse descriptor that's in play here so it's related_query_name that's really in play.

...unless you have used related_name to override the name of the relationship, in which case you should use the related_name you have set,

...unless you set related_query_name... — and so on. I'm inclined towards just adding a , "By default, ... " 🤔

Last edited 3 months ago by Carlton Gibson (previous) (diff)

comment:2 Changed 3 months ago by GitHub <noreply@…>

Resolution: fixed
Status: assignedclosed

In 5af17ba:

Fixed #31591 -- Clarified "reverse" lookup name in making queries docs.

comment:3 Changed 3 months ago by Mariusz Felisiak <felisiak.mariusz@…>

In 844e0591:

[3.1.x] Fixed #31591 -- Clarified "reverse" lookup name in making queries docs.

Backport of 5af17babb0f895cf129fdeee92548d2ac12e78e2 from master

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