Quickstart: Using Improved User

This document provides a quick tutorial for the recommended way to setup Improved User.

See Select a Configuration Method for Improved User for an overview of options and tradeoffs.

Installation

In a Terminal, use pip to install the package from PyPI. To use the UserFactory provided by the package to allow for testing with factory-boy, include it in the installation.

$ pip install django-improved-user[factory]

If factory-boy is unnecessary, it can be omitted by installing normally.

$ pip install django-improved-user

Configuration and Usage

1. In a Django project, create a new app. For the purposes of this documentation, we will assume the name of your new app is user_app, but you could name it whatever you wish.

   $ python3 manage.py startapp user_app
   

2. In your project’s settings, add user_app.apps.UserAppConfig to INSTALLED_APPS (replace user_app and UserAppConfig as necessary).

3. In user_app/models.py, import Improved User’s AbstractUser.

   from improved_user.model_mixins import AbstractUser
   

4. Create a new User model. If you omit comments, you may need to add pass to the line below the class.

   class User(AbstractUser):
       """A User model that extends the Improved User"""
   

Attention

If you add your own fields to the model, you may wish to modify REQUIRED_FIELDS.

5. Define or replace AUTH_USER_MODEL in your project settings with the new model, as below (replace user_app with the name of your own app).

   AUTH_USER_MODEL='user_app.User'
   

Tip

Remember to use get_user_model() to get your new model. Don’t import it directly!

6. While still in settings, change UserAttributeSimilarityValidator to match correct AbstractUser fields, as shown below.

   AUTH_PREFIX = 'django.contrib.auth.password_validation.'
   AUTH_PASSWORD_VALIDATORS = [
       {
           'NAME': AUTH_PREFIX + 'UserAttributeSimilarityValidator',
           'OPTIONS': {
               'user_attributes': ('email', 'full_name', 'short_name')
           },
       },
       # include other password validators here
   ]
   

7. You’re done! 🎉 Run migrations or go back to programming the rest of your project.

Note

Improved user also comes with forms, test factories, and an admin panel. Take a look at the Package Reference for more information.