Query object/expression documentation needs to tidied

[Daniele Procida]

docs/ref/models/queries.txt Query-related classes was created for new F() documentation, and then the notes on Q() were added, followed later by Prefetch().

As that document noted, "This document provides reference material for query-related tools not documented elsewhere" - in other words, things that we couldn't find a good place for elsewhere.

Now F() has moved out, into the new docs/ref/models/expressions.txt Query Expressions document, and Query-related classes now looks even less satisfactory than before.

I propose:

• moving the note on Q() into docs/ref/models/expressions.txt
• moving Prefetch() into ​https://docs.djangoproject.com/en/dev/ref/models/querysets/#prefetch-related, or perhaps elsewhere on that page
• moving the ​https://docs.djangoproject.com/en/dev/ref/models/querysets/#aggregation-functions documentation into docs/ref/models/expressions.txt
• and of course, removing docs/ref/models/queries.txt altogether

[Carl Meyer]

Sounds good to me. I'm not sure the reference documentation for Prefetch should go right into the prefetch_related section -- even though it's of course very closely related, it feels like it complicates the structure of the document too much to have a full class reference inside a method reference inside the QuerySet class reference. So I might put it at the bottom of the document, with a link to it. (Similar to the field lookups). But if you can find a way to do it inline that seems to work OK, great!

[Josh Smeaton]

I agree that Q() needs a better home, but I don't think the expressions doc is the right place either. Everything inside Expressions is self contained, and all builds upon a base Expression class. Q() is only related, implementation wise, because it is a Tree. From a quick scan of the index I think the lookups documentation *might* be a better place, but it's still a bit of a clash.

[Carl Meyer]

@jarshwah Hmm. The Q documentation says "A Q() object, like an F object, encapsulates a SQL expression in a Python object that can be used in database-related operations." That certainly makes it _sound_ like something that belongs, with F objects, in the documentation about objects that represent SQL expressions, regardless of common ancestry. I guess maybe that documentation sentence is technically not quite on point -- a Q object represents a boolean condition (or tree of boolean conditions), which are made up of expressions but aren't precisely an expression.

Q does not implement the query expression API (​https://docs.djangoproject.com/en/dev/ref/models/lookups/#the-query-expression-api). (As an aside, it seems like the general query expression API documentation might belong in the expressions doc, which seems more "general", rather than the lookups doc.)

I'm not sure where Q belongs, but it seems to me that between just the expressions doc and the lookups doc, it would be a better fit in the expressions doc. Q is very clearly neither a lookup nor a transform, but it is something that represents a SQL expression (broadly construed).

[Josh Smeaton]

Agreed that the query expression API should be moved to expressions.txt.

Yeah lookups are not really an appropriate place either - I was thinking about the relationship between lookups and filters. But the problem with including Q in the expressions document, is that the expressions document really focuses on composability and a strict API, neither of which Q() implements.

If Prefetch was to be moved to the querysets document, perhaps at the bottom with a link as suggested by @carljm, I would think the same could be done with Q() with a link from filter and exclude. The documentation for these 2 classes are sparse, and shouldn't complicate the rest of the documentation too much.

[Carl Meyer]

Yeah that last proposal makes sense to me.

[Daniele Procida]

I think that's reasonable.

[Ng Zhi An]

As per the suggestions I have moved the description of Q objects and Prefetch objects from queries.txt into querysets.txt.
I've also added links from filter and exclude to Q, although the wording there may not be the best.
There is already a link from prefetch_related paragraph to Prefetch, so I didn't add any new description there.

This is currently on GitHub as a pull request ​https://github.com/django/django/pull/3889

[Tim Graham <timograham@…>]

In 8f5d6c77b6bbe0390b683cea649de6ad24d80fef:

Fixed #23878 -- Moved Query and Prefetch documentation