Add reference docs for models.ForeignObject

[Ömer Faruk Abacı]

While trying to implement a custom multiple-column join I have spent hours to find an elegant way, at the end I have found an old issue here:

https://code.djangoproject.com/ticket/19385

Then I have realized that I can use ForeignObject for custom joins. Almost all of the solutions online suggest using raw SQLs with Manager.raw() or QuerySet.extra(), none of them mention about ForeignObject. I don't know if it was on purpose or not but I thought that it might be good to mention about the ForeignObject in the following section:

​https://docs.djangoproject.com/en/4.1/ref/models/relations/

What do you think?

[David Sanders]

ForeignObject isn't documented because it isn't earmarked for public use. That being said there's some external documentation on it in a few places to implement custom joins, one good one here: ​https://devblog.kogan.com/blog/custom-relationships-in-django

Closing as won'tfix. If you'd like to raise this topic making ForeignObject public please free to start a discussion on the DevelopersMailingList.

[Ömer Faruk Abacı]

I see your point, thank you!

[Carlton Gibson]

Simon had a proposal in his DjangoCon US 2020 keynote about documenting some of the internals in a way that would help people learn the ORM, but not make them public and so commit to API stability. I don't know how that would role out, or if this would fall under it specifically, but it seems related.

[Mariusz Felisiak]

Replying to Carlton Gibson:

Simon had a proposal in his DjangoCon US 2020 keynote about documenting some of the internals in a way that would help people learn the ORM, but not make them public and so commit to API stability. I don't know how that would role out, or if this would fall under it specifically, but it seems related.

We have a ticket for this :), see #27617.

[Carlton Gibson]

Of course we do :D

[Sarah Boyce]

Note that since 978aae4334fa71ba78a3e94408f0f3aebde8d07c (#373) ForeignObject has been included in the docs related to CompositePrimaryKeys.
We have also followed a deprecation process in the past, see 8b1ff0da4b162e87edebd94e61f2cd153e9e159d. Reopening for us to reconsider adding reference documentation

See also discussion on the following PR: ​https://github.com/django/django/pull/21114

[Sarah Boyce <42296566+sarahboyce@…>]

In 2c87f51:

Refs #373, #34122 -- Removed warning that ForeignObject is an internal tool.

ForeignObject should not be treated as an internal tool. In the past
we made changes in its API with a proper deprecation, e.g.
8b1ff0da4b162e87edebd94e61f2cd153e9e159d.

[Sarah Boyce <42296566+sarahboyce@…>]

In 8ee7341:

[6.0.x] Refs #373, #34122 -- Removed warning that ForeignObject is an internal tool.

ForeignObject should not be treated as an internal tool. In the past
we made changes in its API with a proper deprecation, e.g.
8b1ff0da4b162e87edebd94e61f2cd153e9e159d.

Backport of 2c87f519f48038398c8d8a840fa5bf5497c353bb from main.

[somi]

Picking this up. Plan to mirror the ForeignKey reference structure.
Thanks for reopening!

[somi]

​PR

[H. White]

Reviewed, approved.