Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Documentation improvements coming from community review.

  • Loading branch information...
commit fd8bb4e3e498a92d7a8b340f0684d5f088aa4c92 1 parent b550a6d
Russell Keith-Magee authored September 16, 2012

Showing 1 changed file with 53 additions and 16 deletions. Show diff stats Hide diff stats

  1. 69  docs/topics/auth.txt
69  docs/topics/auth.txt
@@ -57,10 +57,6 @@ API reference
57 57
 Fields
58 58
 ~~~~~~
59 59
 
60  
-TODO document which attributes/methods come from AbstractBaseUser
61  
-TODO tone down references to get_profile - it's not the best way of doing things
62  
-any more.
63  
-
64 60
 .. class:: models.User
65 61
 
66 62
     :class:`~django.contrib.auth.models.User` objects have the following
@@ -254,6 +250,12 @@ Methods
254 250
 
255 251
     .. method:: models.User.get_profile()
256 252
 
  253
+        .. deprecated:: 1.5
  254
+            With the introduction of :ref:`custom User models <auth-custom-user>`,
  255
+            the use of :setting:`AUTH_PROFILE_MODULE` to define a single profile
  256
+            model is no longer supported. See the
  257
+            :doc:`Django 1.5 release notes</releases/1.5>` for more information.
  258
+
257 259
         Returns a site-specific profile for this user. Raises
258 260
         :exc:`django.contrib.auth.models.SiteProfileNotAvailable` if the
259 261
         current site doesn't allow profiles, or
@@ -1784,6 +1786,12 @@ model that you wish to use as your User model.
1784 1786
    to set :setting:`AUTH_USER_MODEL`, you should set it before running
1785 1787
    ``manage.py syncdb`` for the first time.
1786 1788
 
  1789
+   If you have an existing project and you want to migrate to using a custom
  1790
+   User model, you may need to look into using a migration tool like South_
  1791
+   to ease the transition.
  1792
+
  1793
+.. _South: http://south.aeracode.org
  1794
+
1787 1795
 Referencing the User model
1788 1796
 --------------------------
1789 1797
 
@@ -1821,22 +1829,50 @@ Specifying a custom User model
1821 1829
     apps. On the other hand, queries to retrieve this related information
1822 1830
     will involve a database join, which may have an effect on performance.
1823 1831
 
1824  
-Django expects your custom User model to meet some minimum requirements. The
1825  
-easiest way to construct a compliant custom User model is to inherit from
1826  
-:class:`~django.contrib.auth.models.AbstractBaseUser` and provide some key
1827  
-definitions:
  1832
+Django expects your custom User model to meet some minimum requirements.
  1833
+
  1834
+1. Your model must have a single unique field that can be used for
  1835
+   identification purposes. This can be a username, an email address,
  1836
+   or any other unique attribute.
  1837
+
  1838
+2. Your model must provide a way to address the user in a "short" and
  1839
+   "long" form. The most common interpretation of this would be to use
  1840
+   the user's given name as the "short" identifier, and the user's full
  1841
+   name as the "long" identifier. However, there are no constraints on
  1842
+   what these two methods return - if you want, they can return exactly
  1843
+   the same value.
  1844
+
  1845
+The easiest way to construct a compliant custom User model is to inherit from
  1846
+:class:`~django.contrib.auth.models.AbstractBaseUser`.
  1847
+:class:`~django.contrib.auth.models.AbstractBaseUser` provides the core
  1848
+implementation of a `User` model, including hashed passwords and tokenized
  1849
+password resets. You must then provide some key implementation details:
1828 1850
 
1829 1851
 .. attribute:: User.USERNAME_FIELD
1830 1852
 
1831 1853
     A string describing the name of the field on the User model that is
1832 1854
     used as the unique identifier. This will usually be a username of
1833 1855
     some kind, but it can also be an email address, or any other unique
1834  
-    identifier.
  1856
+    identifier. In the following example, the field `identifier` is used
  1857
+    as the identifying field::
  1858
+
  1859
+        class MyUser(AbstractBaseUser):
  1860
+            identfier = models.CharField(max_length=40, unique=True, db_index=True)
  1861
+            ...
  1862
+            USERNAME_FIELD = 'identifier'
1835 1863
 
1836 1864
 .. attribute:: User.REQUIRED_FIELDS
1837 1865
 
1838 1866
     A list of the field names that *must* be provided when creating
1839  
-    a user.
  1867
+    a user. For example, here is the partial definition for a User model
  1868
+    that defines two required fields - a date of birth and height::
  1869
+
  1870
+        class MyUser(AbstractBaseUser):
  1871
+            ...
  1872
+            date_of_birth = models.DateField()
  1873
+            height = models.FloatField()
  1874
+            ...
  1875
+            REQUIRED_FIELDS = ['date_of_birth', 'height']
1840 1876
 
1841 1877
 .. method:: User.get_full_name():
1842 1878
 
@@ -1855,8 +1891,9 @@ You should also define a custom manager for your User model. If your User
1855 1891
 model defines `username` and `email` fields the same as Django's default User,
1856 1892
 you can just install Django's
1857 1893
 :class:`~django.contrib.auth.models.UserManager`; however, if your User model
1858  
-defines different fields, you will need to define a custom manager with 2
1859  
-methods.
  1894
+defines different fields, you will need to define a custom manager that
  1895
+extends :class:`~django.contrib.auth.models.BaseUserManager` providing two
  1896
+additional methods:
1860 1897
 
1861 1898
 .. method:: UserManager.create_user(username, password=None, **other_fields)
1862 1899
 
@@ -1890,7 +1927,7 @@ control access of the User to admin content:
1890 1927
 
1891 1928
 .. attribute:: User.is_staff
1892 1929
 
1893  
-    Returns True if the user is a member of staff.
  1930
+    Returns True if the user is allowed to have access to the admin site.
1894 1931
 
1895 1932
 .. attribute:: User.is_active
1896 1933
 
@@ -1908,10 +1945,10 @@ control access of the User to admin content:
1908 1945
     the given app.
1909 1946
 
1910 1947
 
1911  
-Worked Example
1912  
-~~~~~~~~~~~~~~
  1948
+A full example
  1949
+--------------
1913 1950
 
1914  
-As a worked example, here is a full models.py for an admin-compliant custom
  1951
+Here is an example of a full models.py for an admin-compliant custom
1915 1952
 user app. This user model uses an email address as the username, and has a
1916 1953
 required date of birth; it provides no permission checking, beyond a simple
1917 1954
 `admin` flag on the user account::

0 notes on commit fd8bb4e

Please sign in to comment.
Something went wrong with that request. Please try again.