From fd8bb4e3e498a92d7a8b340f0684d5f088aa4c92 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Sun, 16 Sep 2012 14:20:14 +0800 Subject: [PATCH] Documentation improvements coming from community review. --- docs/topics/auth.txt | 69 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 53 insertions(+), 16 deletions(-) diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt index 617922372c..525130f8ff 100644 --- a/docs/topics/auth.txt +++ b/docs/topics/auth.txt @@ -57,10 +57,6 @@ API reference Fields ~~~~~~ -TODO document which attributes/methods come from AbstractBaseUser -TODO tone down references to get_profile - it's not the best way of doing things -any more. - .. class:: models.User :class:`~django.contrib.auth.models.User` objects have the following @@ -254,6 +250,12 @@ Methods .. method:: models.User.get_profile() + .. deprecated:: 1.5 + With the introduction of :ref:`custom User models `, + the use of :setting:`AUTH_PROFILE_MODULE` to define a single profile + model is no longer supported. See the + :doc:`Django 1.5 release notes` for more information. + Returns a site-specific profile for this user. Raises :exc:`django.contrib.auth.models.SiteProfileNotAvailable` if the current site doesn't allow profiles, or @@ -1784,6 +1786,12 @@ model that you wish to use as your User model. to set :setting:`AUTH_USER_MODEL`, you should set it before running ``manage.py syncdb`` for the first time. + If you have an existing project and you want to migrate to using a custom + User model, you may need to look into using a migration tool like South_ + to ease the transition. + +.. _South: http://south.aeracode.org + Referencing the User model -------------------------- @@ -1821,22 +1829,50 @@ Specifying a custom User model apps. On the other hand, queries to retrieve this related information will involve a database join, which may have an effect on performance. -Django expects your custom User model to meet some minimum requirements. The -easiest way to construct a compliant custom User model is to inherit from -:class:`~django.contrib.auth.models.AbstractBaseUser` and provide some key -definitions: +Django expects your custom User model to meet some minimum requirements. + +1. Your model must have a single unique field that can be used for + identification purposes. This can be a username, an email address, + or any other unique attribute. + +2. Your model must provide a way to address the user in a "short" and + "long" form. The most common interpretation of this would be to use + the user's given name as the "short" identifier, and the user's full + name as the "long" identifier. However, there are no constraints on + what these two methods return - if you want, they can return exactly + the same value. + +The easiest way to construct a compliant custom User model is to inherit from +:class:`~django.contrib.auth.models.AbstractBaseUser`. +:class:`~django.contrib.auth.models.AbstractBaseUser` provides the core +implementation of a `User` model, including hashed passwords and tokenized +password resets. You must then provide some key implementation details: .. attribute:: User.USERNAME_FIELD A string describing the name of the field on the User model that is used as the unique identifier. This will usually be a username of some kind, but it can also be an email address, or any other unique - identifier. + identifier. In the following example, the field `identifier` is used + as the identifying field:: + + class MyUser(AbstractBaseUser): + identfier = models.CharField(max_length=40, unique=True, db_index=True) + ... + USERNAME_FIELD = 'identifier' .. attribute:: User.REQUIRED_FIELDS A list of the field names that *must* be provided when creating - a user. + a user. For example, here is the partial definition for a User model + that defines two required fields - a date of birth and height:: + + class MyUser(AbstractBaseUser): + ... + date_of_birth = models.DateField() + height = models.FloatField() + ... + REQUIRED_FIELDS = ['date_of_birth', 'height'] .. method:: User.get_full_name(): @@ -1855,8 +1891,9 @@ You should also define a custom manager for your User model. If your User model defines `username` and `email` fields the same as Django's default User, you can just install Django's :class:`~django.contrib.auth.models.UserManager`; however, if your User model -defines different fields, you will need to define a custom manager with 2 -methods. +defines different fields, you will need to define a custom manager that +extends :class:`~django.contrib.auth.models.BaseUserManager` providing two +additional methods: .. method:: UserManager.create_user(username, password=None, **other_fields) @@ -1890,7 +1927,7 @@ control access of the User to admin content: .. attribute:: User.is_staff - Returns True if the user is a member of staff. + Returns True if the user is allowed to have access to the admin site. .. attribute:: User.is_active @@ -1908,10 +1945,10 @@ control access of the User to admin content: the given app. -Worked Example -~~~~~~~~~~~~~~ +A full example +-------------- -As a worked example, here is a full models.py for an admin-compliant custom +Here is an example of a full models.py for an admin-compliant custom user app. This user model uses an email address as the username, and has a required date of birth; it provides no permission checking, beyond a simple `admin` flag on the user account::