Opened 2 years ago

Last modified 21 months ago

#20629 assigned Cleanup/optimization

Admonitions in custom User model documentation may be scaring off users

Reported by: russellm Owned by: kedmiston
Component: Documentation Version: 1.5
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

Evan Stone on django-users indicated that he was initially hesitant to use custom User models because the documentation made it sound like it was going to be painful. Specifically, he identified the following pieces of documentation:

  1. "Think carefully before handling information not directly related to authentication in your custom User Model."
  1. "It may be better to store app-specific user information in a model that has a relation with the User model. That allows each app to specify its own user data requirements without risking conflicts with other apps...."
  1. "One limitation of custom User models is that installing a custom User model will break any proxy model extending User. ..."

and

  1. "Another limitation of custom User models is that you can’t use django.contrib.auth.get_user_model() as the sender or target of "

Points 1 and 2 are asking users to consider an architectural question -- do you need a custom user model at all? If you actually *are* using a username-based login system, and you just want to track some extra information about the user, the right approach may *not* be to create a custom user model.

Points 3 and 4 are pointing out known limitations. Proxy models are a problem because they use subclassing, and they will be subclassing the wrong class; signals are a problem because at the point the signal is registered, there's no guarantee that the User model has been correctly defined. There's not much we can do about (3); (4) is something that should get cleaned up when we eventually land app refactor.

The points made by the documentation are all valid, but could perhaps be made in less threatening or alarmist tones, or clarified so that they don't seem like such big problems.

Change History (4)

comment:1 Changed 21 months ago by kedmiston

  • Owner changed from nobody to kedmiston
  • Status changed from new to assigned

comment:2 Changed 21 months ago by kedmiston

Considering modification of the admonition section in the docs...from this:

Model design considerations

Think carefully before handling information not directly related to authentication in your custom User Model.

It may be better to store app-specific user information in a model that has a relation with the User model. That allows each app to specify its own user data requirements without risking conflicts with other apps. On the other hand, queries to retrieve this related information will involve a database join, which may have an effect on performance.

to this:

Model design considerations

A point to think about in your design/decision is whether you need a custom user model at all?

Before choosing to handle information not directly related to authentication in your custom User Model, consider that it may be a better choice to store app-specific user information in a model that has a relation with the User model. This approach allows each app to specify its own user data requirements without risking conflicts with other apps. Keep in mind that queries to retrieve this related information will involve a database join, which may have an effect on performance.


Let me know your thoughts and I'll make a pull request.

comment:3 follow-up: Changed 21 months ago by russellm

Looks like a good update to cover the first point, but points 2-4 are still relevant.

comment:4 in reply to: ↑ 3 Changed 21 months ago by kedmiston

Replying to russellm:

Looks like a good update to cover the first point, but points 2-4 are still relevant.

I'm a bit confused then. I felt like the above suggestion "softened the edges" a bit for 1 & 2 both. Perhaps you can be more explicit about what it should look like in accommodating 2?

Reading your initial report above, I took it to mean that 3 wasn't something we could really do anything about here and 4 was more of a fix that will come in a later version.

Can you help me better understand how to change this to address all 4 points?

Last edited 21 months ago by kedmiston (previous) (diff)
Note: See TracTickets for help on using tickets.
Back to Top