[Django] #24881: order_with_respect_to needs better docs
Django
-------------------------------+--------------------
Reporter: karyon | Owner: nobody
Type: Bug | Status: new
Component: Documentation | Version: 1.8
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------
the model meta option order_with_respect_to is documented
(https://docs.djangoproject.com/en/1.8/ref/models/options/#order-with-
respect-to), but i found the docs to be incomplete.
it says "Marks this object as “orderable” with respect to the given field.
This is almost always used with related objects to allow them to be
ordered with respect to a parent object." What i don't know is what it
actually means for an object to be "orderable with respect to something".
Also, these sentences only say that something is "marked" and they are
"allowed" to be ordered. Under what circumstances does ordering actually
happen? do i need to do something for a queryset of such objects to be
ordered? And what does"almost always" mean, is there anything else this
might be used for?
[[BR]]
Also, i kinda expected this feature to order objects only when queried
coming from the parent class, e.g.
{{{
Question.objects.first().answer_set()
}}}
but not order them when doing e.g.
{{{
Answer.objects.all()
}}}
because the ordering is only with respect to the parent object, right?
that this is not the case might be worth mentioning explicitly.
[[BR]]
I read some code and did experiments and from my point of view, what this
actually does is:
- add a "_order" field to the model
- initializing that field when adding an instance, based on the number of
other instances with the same parent (not mentioned in the docs)
- add some convenience setters/getters for that field
- set the "ordering"-option to that field (most important part and not
mentioned in the docs)
[[BR]]
I hope that helps!
--
Ticket URL: <https://code.djangoproject.com/ticket/24881>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: karyon | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
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 timgraham):
* needs_better_patch: => 0
* needs_tests: => 0
* easy: 0 => 1
* needs_docs: => 0
* type: Bug => Cleanup/optimization
* stage: Unreviewed => Accepted
Comment:
Thanks for the suggestions. It would be even more helpful if you could
submit a patch with proposed changes.
--
Ticket URL: <https://code.djangoproject.com/ticket/24881#comment:1>
Django
Reporter: karyon | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* cc: karyon (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/24881#comment:2>
Django
Reporter: karyon | Owner:
Type: | marissazhou
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
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 marissazhou):
* owner: nobody => marissazhou
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/24881#comment:3>
Django
Reporter: karyon | Owner:
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
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 marissazhou):
* owner: marissazhou =>
* status: assigned => new
--
Ticket URL: <https://code.djangoproject.com/ticket/24881#comment:4>
Django
Reporter: karyon | Owner: karyon
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* status: new => assigned
* owner: => karyon
--
Ticket URL: <https://code.djangoproject.com/ticket/24881#comment:5>
Django
Reporter: karyon | Owner: karyon
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by timgraham):
* has_patch: 0 => 1
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/24881#comment:6>
Django
Reporter: karyon | Owner: karyon
Cleanup/optimization |
Component: Documentation | Version: 1.8
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"27c839e0fce99254ad61322bb827a821f832e840" 27c839e0]:
{{{
#!CommitTicketReference repository=""
revision="27c839e0fce99254ad61322bb827a821f832e840"
Fixed #24881 -- Clarified Meta.order_with_respect_to documentation
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/24881#comment:7>
Django
Reporter: karyon | Owner: karyon
Type: | Status: closed
Cleanup/optimization |
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"aa00f482801c78d0688ec347160177fd05e5d4c6" aa00f482]:
{{{
#!CommitTicketReference repository=""
revision="aa00f482801c78d0688ec347160177fd05e5d4c6"
[1.8.x] Fixed #24881 -- Clarified Meta.order_with_respect_to documentation
Backport of 27c839e0fce99254ad61322bb827a821f832e840 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/24881#comment:8>