Opened 20 months ago

Last modified 19 months ago

#20768 new New feature

Create a reference of public Manager methods

Reported by: ramiro Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: 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 (4)

comment:1 Changed 20 months ago by timo

  • Triage Stage changed from Unreviewed to Accepted

comment:2 Changed 19 months ago by ramiro

In master there are news in this front #20625 and [31fadc120213284da76801cc7bc56e9f32d7281b]

comment:3 Changed 19 months ago 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.

comment:4 Changed 19 months ago by loic84

While addressing this, we should account for @ramiro's on the PR. Probably by removing the custom __init__ altogether.

Version 0, edited 19 months ago by loic84 (next)
Note: See TracTickets for help on using tickets.
Back to Top