Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Documentation improvements coming from community review.

  • Loading branch information...
commit fd8bb4e3e498a92d7a8b340f0684d5f088aa4c92 1 parent b550a6d
Russell Keith-Magee freakboy3742 authored
Showing with 53 additions and 16 deletions.
  1. +53 −16 docs/topics/auth.txt
69 docs/topics/auth.txt
View
@@ -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 <auth-custom-user>`,
+ 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</releases/1.5>` 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::
Please sign in to comment.
Something went wrong with that request. Please try again.