Opened 11 years ago
Last modified 3 weeks ago
#20768 new New feature
Create a reference of public Manager methods
Reported by: | Ramiro Morales | Owned by: | nobody |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | |
Cc: | Ülgen Sarıkavak, Clifford Gama | Triage Stage: | Accepted |
Has patch: | no | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
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
Change History (6)
comment:1 by , 11 years ago
Triage Stage: | Unreviewed → Accepted |
---|
comment:2 by , 11 years ago
comment:3 by , 11 years ago
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 allQuerySet
public methods butdelete()
are available fromManager
. - Reference the
from_queryset()
,get_queryset()
,raw()
methods and themodel
,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
andQuerySet.as_manager
) - A new section about creating a
Manager
by compositingQuerySets
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.
comment:4 by , 11 years ago
While addressing this, we should account for @ramiro's comment on the commit. Probably by removing the custom __init__
altogether.
comment:5 by , 8 months ago
Cc: | added |
---|
comment:6 by , 3 weeks ago
Cc: | added |
---|
In master there are news in this front #20625 and [31fadc120213284da76801cc7bc56e9f32d7281b]