Opened 10 years ago

Closed 10 years ago

#23878 closed Cleanup/optimization (fixed)

Query object/expression documentation needs to tidied

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

Description

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:

Change History (8)

comment:1 by Carl Meyer, 10 years ago

Triage Stage: UnreviewedAccepted

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!

comment:2 by Josh Smeaton, 10 years ago

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.

comment:3 by Carl Meyer, 10 years ago

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

comment:4 by Josh Smeaton, 10 years ago

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.

comment:5 by Carl Meyer, 10 years ago

Yeah that last proposal makes sense to me.

comment:6 by Daniele Procida, 10 years ago

I think that's reasonable.

comment:7 by Ng Zhi An, 10 years ago

Owner: changed from nobody to Ng Zhi An
Status: newassigned

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

comment:8 by Tim Graham <timograham@…>, 10 years ago

Resolution: fixed
Status: assignedclosed

In 8f5d6c77b6bbe0390b683cea649de6ad24d80fef:

Fixed #23878 -- Moved Query and Prefetch documentation

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