Code

Opened 13 months ago

Last modified 10 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.

Attachments (0)

Change History (4)

comment:1 Changed 10 months ago by kedmiston

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

comment:2 Changed 10 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 10 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 10 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 10 months ago by kedmiston (previous) (diff)

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as assigned
The owner will be changed from kedmiston to anonymous. Next status will be 'assigned'
The ticket will be disowned. Next status will be 'new'
as The resolution will be set. Next status will be 'closed'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.