Opened 6 years ago

Closed 6 years ago

#30222 closed Bug (invalid)

documentation bug for base managers

Reported by: David Gudeman Owned by: nobody
Component: Documentation Version: 2.1
Severity: Normal Keywords: base_manager
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The documentation (https://docs.djangoproject.com/en/2.2/topics/db/managers/#base-managers) for "Managers->Base managers" seems to contradict itself:

para 1, line 1: "By default, Django uses an instance of the Model._base_manager manager class when accessing related objects"

para 3, line 1: "Base managers aren’t used when querying on related models."

This is reinforced with an example in para 3, but is then (apparently) contradicted again:

para 4, line 1: "This manager is used to access objects that are related to from some other model."

Furthermore, para 3 give an example of a base model that filters out some rows and then in the next section we get a scary-sounding warning not to do that or bad things will happen. But the scary warning is odd because it seems to be warning me that it will do exactly what I intend it to do. If I use the example from para 3, then I *want* it to filter out deleted rows. Why is that bad? And especially, why is it bad when para 3 says it won't work anyway?

Finally, para 1 and 2 seem to say that to change Model._base_manager I should change Meta.base_manager_name, but doesn't say what the difference it makes.

Change History (1)

comment:1 by Carlton Gibson, 6 years ago

Resolution: invalid
Status: newclosed

Grrr... Hi David.

Can I first say, you pretty much want to forget this bit of the docs exists — unless you're super sure what you're doing, and even then, leave _base_manager well alone. (TBH not sure why it's documented the _ prefix implies private method... — NoteToSelf: should look up why it's documented)

The key point is that the .filter(question__name__startswith) bit, as a query, will use Question._default_manager even though the choice.question lookup, as a direct access, will use _base_manager.

Have a read of (some of) `django/db/models/fields/related_descriptors.py` to see where _base_manager is used in this way. (Imagine you have a foreign key to an object filtered by _default_manager 💥...)

I'm not sure this is really addressable. Bar a big warning banner saying "Here be dragons" I don't think there's much we can do to clarify this. (But concrete suggestions always to be considered...)

Note: See TracTickets for help on using tickets.
Back to Top