[Django] #23878: Query object/expression documentation needs to tidied
Django
--------------------------------------+--------------------
Reporter: EvilDMP | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+--------------------
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
--
Ticket URL: <https://code.djangoproject.com/ticket/23878>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: EvilDMP | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by carljm):
* needs_better_patch: => 0
* stage: Unreviewed => Accepted
* needs_tests: => 0
* needs_docs: => 0
Comment:
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!
--
Ticket URL: <https://code.djangoproject.com/ticket/23878#comment:1>
Django
Reporter: EvilDMP | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (by jarshwah):
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/23878#comment:2>
Django
Reporter: EvilDMP | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (by carljm):
@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).
--
Ticket URL: <https://code.djangoproject.com/ticket/23878#comment:3>
Django
Reporter: EvilDMP | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (by jarshwah):
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/23878#comment:4>
Django
Reporter: EvilDMP | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (by carljm):
Yeah that last proposal makes sense to me.
--
Ticket URL: <https://code.djangoproject.com/ticket/23878#comment:5>
Django
Reporter: EvilDMP | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (by evildmp):
I think that's reasonable.
--
Ticket URL: <https://code.djangoproject.com/ticket/23878#comment:6>
Django
Reporter: EvilDMP | Owner: ngzhian
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Changes (by ngzhian):
* owner: nobody => ngzhian
* status: new => assigned
Comment:
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]
--
Ticket URL: <https://code.djangoproject.com/ticket/23878#comment:7>
Django
Reporter: EvilDMP | Owner: ngzhian
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"8f5d6c77b6bbe0390b683cea649de6ad24d80fef"]:
{{{
#!CommitTicketReference repository=""
revision="8f5d6c77b6bbe0390b683cea649de6ad24d80fef"
Fixed #23878 -- Moved Query and Prefetch documentation
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/23878#comment:8>