Cleanup and documentation of AbstractUser base class.

django/contrib/auth/models.py

@@ -228,10 +228,11 @@ def _user_has_module_perms(user, app_label):
 
 
 class AbstractBaseUser(models.Model):
-    REQUIRED_FIELDS = []
     password = models.CharField(_('password'), max_length=128)
     last_login = models.DateTimeField(_('last login'), default=timezone.now)
 
+    REQUIRED_FIELDS = []
+
     class Meta:
         abstract = True
 
@@ -279,12 +280,11 @@ class AbstractBaseUser(models.Model):
 @python_2_unicode_compatible
 class AbstractUser(AbstractBaseUser):
     """
-    Users within the Django authentication system are represented by this
-    model.
+    An abstract base class implementing a fully featured User model with
+    admin-compliant permissions.
 
-    Username and password are required. Other fields are optional.
+    Username, password and email are required. Other fields are optional.
     """
-    REQUIRED_FIELDS = ['email']
     username = models.CharField(_('username'), max_length=30, unique=True,
         help_text=_('Required. 30 characters or fewer. Letters, numbers and '
                     '@/./+/-/_ characters'),
@@ -314,6 +314,8 @@ class AbstractUser(AbstractBaseUser):
 
     objects = UserManager()
 
+    REQUIRED_FIELDS = ['email']
+
     class Meta:
         verbose_name = _('user')
         verbose_name_plural = _('users')
@@ -434,10 +436,18 @@ class AbstractUser(AbstractBaseUser):
                 raise SiteProfileNotAvailable
         return self._profile_cache
 
+
 class User(AbstractUser):
+    """
+    Users within the Django authentication system are represented by this
+    model.
+
+    Username, password and email are required. Other fields are optional.
+    """
     class Meta:
         swappable = 'AUTH_USER_MODEL'
 
+
 @python_2_unicode_compatible
 class AnonymousUser(object):
     id = None

docs/topics/auth.txt

@@ -1918,6 +1918,14 @@ additional methods:
     Unlike `create_user()`, `create_superuser()` *must* require the caller
     to provider a password.
 
+Extending Django's default User
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're entirely happy with Django's :class:`~django.contrib.auth.models.User`
+model and you just want to add some additional profile information, you can
+simply subclass :class:`~django.contrib.auth.models.AbstractUser` and add your
+custom profile fields.
+
 Custom users and django.contrib.admin
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~