[Django] #20768: Create a reference of public Manager methods
Django
-----------------------------------------+------------------------
Reporter: ramiro | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-----------------------------------------+------------------------
In the "Natural keys" documentation, an example of a custom manager's
`get_by_natural_key()` method calls `self.get()`
(https://docs.djangoproject.com/en/dev/topics/serialization
/#deserialization-of-natural-keys) but we don't document which the
available methods are.
We should expand the reference-type documentation of manager, even if only
to note some of them simply proxy to the respective !QuerySet methods:
https://github.com/django/django/blob/master/django/db/models/manager.py#L111
--
Ticket URL: <https://code.djangoproject.com/ticket/20768>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: ramiro | Owner: nobody
Type: New feature | 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: 0 | UI/UX: 0
Changes (by timo):
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/20768#comment:1>
Django
Reporter: ramiro | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by ramiro):
In master there are news in this front #20625 and
[31fadc120213284da76801cc7bc56e9f32d7281b]
--
Ticket URL: <https://code.djangoproject.com/ticket/20768#comment:2>
Django
Reporter: ramiro | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by loic84):
IMO `ref/models/managers.txt` should take over a fair chunk from the topic
guide `topics/db/managers.txt`.
The reference would include the stock `Manager` methods and attributes and
everything one needs to know about '''using''' managers (either the stock
`Manager` or subclasses like `CurrentSiteManager`). I suggest the
following:
- A section about `QuerySet` methods. I'm not sure if we should list them
all or just mention that all `QuerySet` public methods but `delete()` are
available from `Manager`.
- Reference the `from_queryset()`, `get_queryset()`, `raw()` methods and
the `model`, `db`, `use_for_related_fields` attributes.
- Get "Manager names" from the topic guide.
- Split "Modifying initial Manager QuerySets" from the topic guide into
two parts, one that goes within the `get_queryset()` definition and the
other one into a new section "Using multiple managers on the same model".
- Get "Custom managers and model inheritance" from the topic guide.
The topic guide would then stick to the ins and outs of creating a custom
Manager:
- "Calling custom QuerySet methods from the Manager"
- "Creating Manager with QuerySet methods" (linked from
`Manager.from_queryset` and `QuerySet.as_manager`)
- A new section about creating a `Manager` by compositing `QuerySets` like
the example in
https://github.com/django/django/pull/1328#issuecomment-21439470
- "Implementation concerns"
- "Controlling automatic Manager types" (Linked from
`Manager.use_for_related_fields`)
- "Writing correct Managers for use in automatic Manager instances"
(Linked from `Manager.use_for_related_fields`)
While we are at it, we should remove the Male/Female distinction from the
examples.
Feedback welcome.
--
Ticket URL: <https://code.djangoproject.com/ticket/20768#comment:3>
Django
Reporter: ramiro | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by loic84):
While addressing this, we should account for @ramiro's
[https://github.com/django/django/commit/31fadc120213284da76801cc7bc56e9f32d7281b#commitcomment-3725813
on the PR]. Probably by removing the custom `__init__` altogether.
--
Ticket URL: <https://code.djangoproject.com/ticket/20768#comment:4>
Django
Reporter: Ramiro Morales | Owner: nobody
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Ülgen Sarıkavak):
* cc: Ülgen Sarıkavak (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/20768#comment:5>
Django
Reporter: Ramiro Morales | Owner: nobody
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Clifford Gama):
* cc: Clifford Gama (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/20768#comment:6>
Django
Reporter: Ramiro Morales | Owner: Clifford Gama
Type: New feature | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Clifford Gama):
* owner: nobody => Clifford Gama
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/20768#comment:7>