Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.0.X] Auth-related doc cleanups:

  * Added to documentation of missing characters from `allowed_chars` in `make_random_password`.
  * Fixed several long lines and word wraps.
  * Added a reference link to the "How to log a user in" section and made a later reference to this section an actual link using the `:ref:` directive.
  * Turned a command line code example into a code block.
  * Added attribute reference link for a ``request.META`` mention.
  * Added `code-block:: html` directives for HTML examples.
  * Corrected reference links for all the `auth.views` functions.
  * Added a few function signatures and documentation of optional parameters that were missing for some of the the `auth.views` functions (refs #10272).

Backport of r9835 from trunk.


git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.0.X@9836 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 910aa0ea288e107c11c4f9973c88158d47fe2bd5 1 parent b09a197
Gary Wilson Jr. authored
403  docs/topics/auth.txt
@@ -58,12 +58,13 @@ Fields
58 58
 
59 59
 .. class:: models.User
60 60
 
61  
-    :class:`~django.contrib.auth.models.User` objects have the following fields:
  61
+    :class:`~django.contrib.auth.models.User` objects have the following
  62
+    fields:
62 63
 
63 64
     .. attribute:: models.User.username
64 65
 
65  
-        Required. 30 characters or fewer. Alphanumeric characters only (letters,
66  
-        digits and underscores).
  66
+        Required. 30 characters or fewer. Alphanumeric characters only
  67
+        (letters, digits and underscores).
67 68
 
68 69
     .. attribute:: models.User.first_name
69 70
 
@@ -92,17 +93,17 @@ Fields
92 93
         Boolean. Designates whether this user account should be considered
93 94
         active. Set this flag to ``False`` instead of deleting accounts.
94 95
 
95  
-        This doesn't control whether or not the user can log in. Nothing in
96  
-        the authentication path checks the ``is_active`` flag, so if you want
97  
-        to reject a login based on ``is_active`` being ``False``, it is up to
98  
-        you to check that in your own login view. However, permission checking
  96
+        This doesn't control whether or not the user can log in. Nothing in the
  97
+        authentication path checks the ``is_active`` flag, so if you want to
  98
+        reject a login based on ``is_active`` being ``False``, it is up to you
  99
+        to check that in your own login view. However, permission checking
99 100
         using the methods like :meth:`~models.User.has_perm` does check this
100 101
         flag and will always return ``False`` for inactive users.
101 102
 
102 103
     .. attribute:: models.User.is_superuser
103 104
 
104  
-        Boolean. Designates that this user has all permissions without explicitly
105  
-        assigning them.
  105
+        Boolean. Designates that this user has all permissions without
  106
+        explicitly assigning them.
106 107
 
107 108
     .. attribute:: models.User.last_login
108 109
 
@@ -111,8 +112,8 @@ Fields
111 112
 
112 113
     .. attribute:: models.User.date_joined
113 114
 
114  
-        A datetime designating when the account was created. Is set to the current
115  
-        date/time by default when the account is created.
  115
+        A datetime designating when the account was created. Is set to the
  116
+        current date/time by default when the account is created.
116 117
 
117 118
 Methods
118 119
 ~~~~~~~
@@ -122,7 +123,8 @@ Methods
122 123
     :class:`~django.contrib.auth.models.User` objects have two many-to-many
123 124
     fields: models.User. ``groups`` and ``user_permissions``.
124 125
     :class:`~django.contrib.auth.models.User` objects can access their related
125  
-    objects in the same way as any other :ref:`Django model <topics-db-models>`:
  126
+    objects in the same way as any other :ref:`Django model
  127
+    <topics-db-models>`:
126 128
 
127 129
     .. code-block:: python
128 130
 
@@ -150,16 +152,16 @@ Methods
150 152
 
151 153
     .. method:: models.User.is_authenticated()
152 154
 
153  
-        Always returns ``True``. This is a way to
154  
-        tell if the user has been authenticated. This does not imply any
155  
-        permissions, and doesn't check if the user is active - it only indicates
156  
-        that the user has provided a valid username and password.
  155
+        Always returns ``True``. This is a way to tell if the user has been
  156
+        authenticated. This does not imply any permissions, and doesn't check
  157
+        if the user is active - it only indicates that the user has provided a
  158
+        valid username and password.
157 159
 
158 160
     .. method:: models.User.get_full_name()
159 161
 
160  
-        Returns the :attr:`~django.contrib.auth.models.User.first_name` plus the
161  
-        :attr:`~django.contrib.auth.models.User.last_name`,
162  
-        with a space in between.
  162
+        Returns the :attr:`~django.contrib.auth.models.User.first_name` plus
  163
+        the :attr:`~django.contrib.auth.models.User.last_name`, with a space in
  164
+        between.
163 165
 
164 166
     .. method:: models.User.set_password(raw_password)
165 167
 
@@ -169,15 +171,16 @@ Methods
169 171
 
170 172
     .. method:: models.User.check_password(raw_password)
171 173
 
172  
-        Returns ``True`` if the given raw string is the correct password for the
173  
-        user. (This takes care of the password hashing in making the comparison.)
  174
+        Returns ``True`` if the given raw string is the correct password for
  175
+        the user. (This takes care of the password hashing in making the
  176
+        comparison.)
174 177
 
175 178
     .. method:: models.User.set_unusable_password()
176 179
 
177 180
         .. versionadded:: 1.0
178 181
 
179  
-        Marks the user as having no password set.  This isn't the same as having
180  
-        a blank string for a password.
  182
+        Marks the user as having no password set.  This isn't the same as
  183
+        having a blank string for a password.
181 184
         :meth:`~django.contrib.auth.models.User.check_password()` for this user
182 185
         will never return ``True``. Doesn't save the
183 186
         :class:`~django.contrib.auth.models.User` object.
@@ -200,31 +203,31 @@ Methods
200 203
 
201 204
     .. method:: models.User.get_all_permissions()
202 205
 
203  
-        Returns a list of permission strings that the user has, both through group
204  
-        and user permissions.
  206
+        Returns a list of permission strings that the user has, both through
  207
+        group and user permissions.
205 208
 
206 209
     .. method:: models.User.has_perm(perm)
207 210
 
208  
-        Returns ``True`` if the user has the specified permission, where perm is
209  
-        in the format ``"package.codename"``. If the user is inactive, this method
210  
-        will always return ``False``.
  211
+        Returns ``True`` if the user has the specified permission, where perm
  212
+        is in the format ``"package.codename"``. If the user is inactive, this
  213
+        method will always return ``False``.
211 214
 
212 215
     .. method:: models.User.has_perms(perm_list)
213 216
 
214  
-        Returns ``True`` if the user has each of the specified permissions, where
215  
-        each perm is in the format ``"package.codename"``. If the user is inactive,
216  
-        this method will always return ``False``.
  217
+        Returns ``True`` if the user has each of the specified permissions,
  218
+        where each perm is in the format ``"package.codename"``. If the user is
  219
+        inactive, this method will always return ``False``.
217 220
 
218 221
     .. method:: models.User.has_module_perms(package_name)
219 222
 
220  
-        Returns ``True`` if the user has any permissions in the given package (the
221  
-        Django app label). If the user is inactive, this method will always return
222  
-        ``False``.
  223
+        Returns ``True`` if the user has any permissions in the given package
  224
+        (the Django app label). If the user is inactive, this method will
  225
+        always return ``False``.
223 226
 
224 227
     .. method:: models.User.get_and_delete_messages()
225 228
 
226  
-        Returns a list of :class:`~django.contrib.auth.models.Message` objects in
227  
-        the user's queue and deletes the messages from the queue.
  229
+        Returns a list of :class:`~django.contrib.auth.models.Message` objects
  230
+        in the user's queue and deletes the messages from the queue.
228 231
 
229 232
     .. method:: models.User.email_user(subject, message, from_email=None)
230 233
 
@@ -235,10 +238,10 @@ Methods
235 238
     .. method:: models.User.get_profile()
236 239
 
237 240
         Returns a site-specific profile for this user. Raises
238  
-        :exc:`django.contrib.auth.models.SiteProfileNotAvailable` if the current
239  
-        site doesn't allow profiles. For information on how to define a
240  
-        site-specific user profile, see the section on
241  
-        `storing additional user information`_ below.
  241
+        :exc:`django.contrib.auth.models.SiteProfileNotAvailable` if the
  242
+        current site doesn't allow profiles. For information on how to define a
  243
+        site-specific user profile, see the section on `storing additional user
  244
+        information`_ below.
242 245
 
243 246
 .. _storing additional user information: #storing-additional-information-about-users
244 247
 
@@ -255,12 +258,12 @@ Manager functions
255 258
         Creates, saves and returns a :class:`~django.contrib.auth.models.User`.
256 259
         The :attr:`~django.contrib.auth.models.User.username`,
257 260
         :attr:`~django.contrib.auth.models.User.email` and
258  
-        :attr:`~django.contrib.auth.models.User.password` are set as given, and the
259  
-        :class:`~django.contrib.auth.models.User` gets ``is_active=True``.
  261
+        :attr:`~django.contrib.auth.models.User.password` are set as given, and
  262
+        the :class:`~django.contrib.auth.models.User` gets ``is_active=True``.
260 263
 
261 264
         If no password is provided,
262  
-        :meth:`~django.contrib.auth.models.User.set_unusable_password()` will be
263  
-        called.
  265
+        :meth:`~django.contrib.auth.models.User.set_unusable_password()` will
  266
+        be called.
264 267
 
265 268
         See `Creating users`_ for example usage.
266 269
 
@@ -268,8 +271,12 @@ Manager functions
268 271
 
269 272
         Returns a random password with the given length and given string of
270 273
         allowed characters. (Note that the default value of ``allowed_chars``
271  
-        doesn't contain letters that can cause user confusion, including ``1``,
272  
-        ``I`` and ``0``).
  274
+        doesn't contain letters that can cause user confusion, including:
  275
+
  276
+            * ``i``, ``l``, ``I``, and ``1`` (lowercase letter i, lowercase
  277
+              letter L, uppercase letter i, and the number one)
  278
+            * ``o``, ``O``, and ``0`` (uppercase letter o, lowercase letter o,
  279
+              and zero)
273 280
 
274 281
 Basic usage
275 282
 -----------
@@ -310,7 +317,9 @@ Django requires add *and* change permissions as a slight security measure.
310 317
 Changing passwords
311 318
 ~~~~~~~~~~~~~~~~~~
312 319
 
313  
-Change a password with :meth:`~django.contrib.auth.models.User.set_password()`::
  320
+Change a password with :meth:`~django.contrib.auth.models.User.set_password()`:
  321
+
  322
+.. code-block:: python
314 323
 
315 324
     >>> from django.contrib.auth.models import User
316 325
     >>> u = User.objects.get(username__exact='john')
@@ -365,15 +374,18 @@ Anonymous users
365 374
 
366 375
     * :attr:`~django.contrib.auth.models.User.id` is always ``None``.
367 376
     * :attr:`~django.contrib.auth.models.User.is_staff` and
368  
-      :attr:`~django.contrib.auth.models.User.is_superuser` are always ``False``.
  377
+      :attr:`~django.contrib.auth.models.User.is_superuser` are always
  378
+      ``False``.
369 379
     * :attr:`~django.contrib.auth.models.User.is_active` is always ``False``.
370 380
     * :attr:`~django.contrib.auth.models.User.groups` and
371  
-      :attr:`~django.contrib.auth.models.User.user_permissions` are always empty.
  381
+      :attr:`~django.contrib.auth.models.User.user_permissions` are always
  382
+      empty.
372 383
     * :meth:`~django.contrib.auth.models.User.is_anonymous()` returns ``True``
373 384
       instead of ``False``.
374 385
     * :meth:`~django.contrib.auth.models.User.is_authenticated()` returns
375 386
       ``False`` instead of ``True``.
376  
-    * :meth:`~django.contrib.auth.models.User.has_perm()` always returns ``False``.
  387
+    * :meth:`~django.contrib.auth.models.User.has_perm()` always returns
  388
+      ``False``.
377 389
     * :meth:`~django.contrib.auth.models.User.set_password()`,
378 390
       :meth:`~django.contrib.auth.models.User.check_password()`,
379 391
       :meth:`~django.contrib.auth.models.User.save()`,
@@ -392,10 +404,10 @@ Creating superusers
392 404
 .. versionadded:: 1.0
393 405
    The ``manage.py createsuperuser`` command is new.
394 406
 
395  
-:djadmin:`manage.py syncdb <syncdb>` prompts you to create a superuser the first time
396  
-you run it after adding ``'django.contrib.auth'`` to your
  407
+:djadmin:`manage.py syncdb <syncdb>` prompts you to create a superuser the
  408
+first time you run it after adding ``'django.contrib.auth'`` to your
397 409
 :setting:`INSTALLED_APPS`. If you need to create a superuser at a later date,
398  
-you can use a command line utility.
  410
+you can use a command line utility::
399 411
 
400 412
     manage.py createsuperuser --username=joe --email=joe@example.com
401 413
 
@@ -409,48 +421,47 @@ on the command line still works::
409 421
     python /path/to/django/contrib/auth/create_superuser.py
410 422
 
411 423
 ...where :file:`/path/to` is the path to the Django codebase on your
412  
-filesystem. The ``manage.py`` command is preferred because it figures
413  
-out the correct path and environment for you.
  424
+filesystem. The ``manage.py`` command is preferred because it figures out the
  425
+correct path and environment for you.
414 426
 
415 427
 .. _auth-profiles:
416 428
 
417 429
 Storing additional information about users
418 430
 ------------------------------------------
419 431
 
420  
-If you'd like to store additional information related to your users,
421  
-Django provides a method to specify a site-specific related model --
422  
-termed a "user profile" -- for this purpose.
  432
+If you'd like to store additional information related to your users, Django
  433
+provides a method to specify a site-specific related model -- termed a "user
  434
+profile" -- for this purpose.
423 435
 
424  
-To make use of this feature, define a model with fields for the
425  
-additional information you'd like to store, or additional methods
426  
-you'd like to have available, and also add a
427  
-:class:`~django.db.models.Field.ForeignKey` from your model to the
428  
-:class:`~django.contrib.auth.models.User` model, specified with ``unique=True``
429  
-to ensure only one instance of your model can be created for each
430  
-:class:`~django.contrib.auth.models.User`.
  436
+To make use of this feature, define a model with fields for the additional
  437
+information you'd like to store, or additional methods you'd like to have
  438
+available, and also add a :class:`~django.db.models.Field.ForeignKey` from your
  439
+model to the :class:`~django.contrib.auth.models.User` model, specified with
  440
+``unique=True`` to ensure only one instance of your model can be created for
  441
+each :class:`~django.contrib.auth.models.User`.
431 442
 
432  
-To indicate that this model is the user profile model for a given
433  
-site, fill in the setting :setting:`AUTH_PROFILE_MODULE` with a string
434  
-consisting of the following items, separated by a dot:
  443
+To indicate that this model is the user profile model for a given site, fill in
  444
+the setting :setting:`AUTH_PROFILE_MODULE` with a string consisting of the
  445
+following items, separated by a dot:
435 446
 
436  
-1. The (normalized to lower-case) name of the application in which the
437  
-   user profile model is defined (in other words, an all-lowercase
438  
-   version of the name which was passed to
439  
-   :djadmin:`manage.py startapp <startapp>` to create the application).
  447
+1. The (normalized to lower-case) name of the application in which the user
  448
+   profile model is defined (in other words, an all-lowercase version of the
  449
+   name which was passed to :djadmin:`manage.py startapp <startapp>` to create
  450
+   the application).
440 451
 
441 452
 2. The (normalized to lower-case) name of the model class.
442 453
 
443  
-For example, if the profile model was a class named ``UserProfile``
444  
-and was defined inside an application named ``accounts``, the
445  
-appropriate setting would be::
  454
+For example, if the profile model was a class named ``UserProfile`` and was
  455
+defined inside an application named ``accounts``, the appropriate setting would
  456
+be::
446 457
 
447 458
     AUTH_PROFILE_MODULE = 'accounts.userprofile'
448 459
 
449  
-When a user profile model has been defined and specified in this
450  
-manner, each :class:`~django.contrib.auth.models.User` object will have a
451  
-method -- :class:`~django.contrib.auth.models.User.get_profile()`
452  
--- which returns the instance of the user profile model associated
453  
-with that :class:`~django.contrib.auth.models.User`.
  460
+When a user profile model has been defined and specified in this manner, each
  461
+:class:`~django.contrib.auth.models.User` object will have a method --
  462
+:class:`~django.contrib.auth.models.User.get_profile()` -- which returns the
  463
+instance of the user profile model associated with that
  464
+:class:`~django.contrib.auth.models.User`.
454 465
 
455 466
 For more information, see `Chapter 12 of the Django book`_.
456 467
 
@@ -485,6 +496,8 @@ section). You can tell them apart with
485 496
     else:
486 497
         # Do something for anonymous users.
487 498
 
  499
+.. _howtologauserin:
  500
+
488 501
 How to log a user in
489 502
 --------------------
490 503
 
@@ -495,10 +508,10 @@ Django provides two functions in :mod:`django.contrib.auth`:
495 508
 .. function:: authenticate()
496 509
 
497 510
     To authenticate a given username and password, use
498  
-    :func:`~django.contrib.auth.authenticate()`. It
499  
-    takes two keyword arguments, ``username`` and ``password``, and it returns
500  
-    a :class:`~django.contrib.auth.models.User` object if the password is
501  
-    valid for the given username. If the password is invalid,
  511
+    :func:`~django.contrib.auth.authenticate()`. It takes two keyword
  512
+    arguments, ``username`` and ``password``, and it returns a
  513
+    :class:`~django.contrib.auth.models.User` object if the password is valid
  514
+    for the given username. If the password is invalid,
502 515
     :func:`~django.contrib.auth.authenticate()` returns ``None``. Example::
503 516
 
504 517
         from django.contrib.auth import authenticate
@@ -546,9 +559,9 @@ Django provides two functions in :mod:`django.contrib.auth`:
546 559
     :func:`~django.contrib.auth.login()`.
547 560
     :func:`~django.contrib.auth.authenticate()`
548 561
     sets an attribute on the :class:`~django.contrib.auth.models.User` noting
549  
-    which authentication backend successfully authenticated that user (see
550  
-    the `backends documentation`_ for details), and this information is
551  
-    needed later during the login process.
  562
+    which authentication backend successfully authenticated that user (see the
  563
+    `backends documentation`_ for details), and this information is needed
  564
+    later during the login process.
552 565
 
553 566
 .. _backends documentation: #other-authentication-sources
554 567
 
@@ -557,12 +570,12 @@ Manually checking a user's password
557 570
 
558 571
 .. function:: check_password()
559 572
 
560  
-    If you'd like to manually authenticate a user by comparing a
561  
-    plain-text password to the hashed password in the database, use the
562  
-    convenience function :func:`django.contrib.auth.models.check_password`. It
563  
-    takes two arguments: the plain-text password to check, and the full
564  
-    value of a user's ``password`` field in the database to check against,
565  
-    and returns ``True`` if they match, ``False`` otherwise.
  573
+    If you'd like to manually authenticate a user by comparing a plain-text
  574
+    password to the hashed password in the database, use the convenience
  575
+    function :func:`django.contrib.auth.models.check_password`. It takes two
  576
+    arguments: the plain-text password to check, and the full value of a user's
  577
+    ``password`` field in the database to check against, and returns ``True``
  578
+    if they match, ``False`` otherwise.
566 579
 
567 580
 How to log a user out
568 581
 ---------------------
@@ -581,18 +594,18 @@ How to log a user out
581 594
             logout(request)
582 595
             # Redirect to a success page.
583 596
 
584  
-    Note that :func:`~django.contrib.auth.logout()` doesn't throw any errors
585  
-    if the user wasn't logged in.
  597
+    Note that :func:`~django.contrib.auth.logout()` doesn't throw any errors if
  598
+    the user wasn't logged in.
586 599
 
587 600
     .. versionchanged:: 1.0
588 601
        Calling ``logout()`` now cleans session data.
589 602
 
590  
-    When you call :func:`~django.contrib.auth.logout()`, the session
591  
-    data for the current request is completely cleaned out. All existing data
592  
-    is removed. This is to prevent another person from using the same web
593  
-    browser to log in and have access to the previous user's session data.
594  
-    If you want to put anything into the session that will be available to
595  
-    the user immediately after logging out, do that *after* calling
  603
+    When you call :func:`~django.contrib.auth.logout()`, the session data for
  604
+    the current request is completely cleaned out. All existing data is
  605
+    removed. This is to prevent another person from using the same web browser
  606
+    to log in and have access to the previous user's session data. If you want
  607
+    to put anything into the session that will be available to the user
  608
+    immediately after logging out, do that *after* calling
596 609
     :func:`django.contrib.auth.logout()`.
597 610
 
598 611
 Limiting access to logged-in users
@@ -669,8 +682,8 @@ The login_required decorator
669 682
           ``next`` or the value of ``redirect_field_name``. For example:
670 683
           ``/accounts/login/?next=/polls/3/``.
671 684
 
672  
-        * If the user is logged in, execute the view normally. The view code
673  
-          is free to assume the user is logged in.
  685
+        * If the user is logged in, execute the view normally. The view code is
  686
+          free to assume the user is logged in.
674 687
 
675 688
 Note that you'll need to map the appropriate Django view to
676 689
 :setting:`settings.LOGIN_URL <LOGIN_URL>`. For example, using the defaults, add
@@ -682,31 +695,33 @@ the following line to your URLconf::
682 695
 
683 696
     Here's what ``django.contrib.auth.views.login`` does:
684 697
 
685  
-        * If called via ``GET``, it displays a login form that POSTs to the same
686  
-          URL. More on this in a bit.
  698
+        * If called via ``GET``, it displays a login form that POSTs to the
  699
+          same URL. More on this in a bit.
687 700
 
688 701
         * If called via ``POST``, it tries to log the user in. If login is
689 702
           successful, the view redirects to the URL specified in ``next``. If
690  
-          ``next`` isn't provided, it redirects to :setting:`settings.LOGIN_REDIRECT_URL <LOGIN_REDIRECT_URL>`
691  
-          (which defaults to ``/accounts/profile/``). If login isn't successful,
692  
-          it redisplays the login form.
  703
+          ``next`` isn't provided, it redirects to
  704
+          :setting:`settings.LOGIN_REDIRECT_URL <LOGIN_REDIRECT_URL>` (which
  705
+          defaults to ``/accounts/profile/``). If login isn't successful, it
  706
+          redisplays the login form.
693 707
 
694 708
     It's your responsibility to provide the login form in a template called
695 709
     ``registration/login.html`` by default. This template gets passed three
696 710
     template context variables:
697 711
 
698  
-        * ``form``: A :class:`~django.forms.Form` object representing the
699  
-          login form. See the :ref:`forms documentation <topics-forms-index>`
700  
-          for more on ``Form`` objects.
  712
+        * ``form``: A :class:`~django.forms.Form` object representing the login
  713
+          form. See the :ref:`forms documentation <topics-forms-index>` for
  714
+          more on ``Form`` objects.
701 715
 
702  
-        * ``next``: The URL to redirect to after successful login. This may contain
703  
-          a query string, too.
  716
+        * ``next``: The URL to redirect to after successful login. This may
  717
+          contain a query string, too.
704 718
 
705 719
         * ``site_name``: The name of the current
706 720
           :class:`~django.contrib.sites.models.Site`, according to the
707  
-          :setting:`SITE_ID` setting. If you're using the Django development version
708  
-          and you don't have the site framework installed, this will be set to the
709  
-          value of ``request.META['SERVER_NAME']``. For more on sites, see
  721
+          :setting:`SITE_ID` setting. If you're using the Django development
  722
+          version and you don't have the site framework installed, this will be
  723
+          set to the value of :attr:`request.META['SERVER_NAME']
  724
+          <django.http.HttpRequest.META>`. For more on sites, see
710 725
           :ref:`ref-contrib-sites`.
711 726
 
712 727
     If you'd prefer not to call the template :file:`registration/login.html`,
@@ -718,7 +733,9 @@ the following line to your URLconf::
718 733
 
719 734
     Here's a sample :file:`registration/login.html` template you can use as a
720 735
     starting point. It assumes you have a :file:`base.html` template that
721  
-    defines a ``content`` block::
  736
+    defines a ``content`` block:
  737
+
  738
+    .. code-block:: html
722 739
 
723 740
         {% extends "base.html" %}
724 741
 
@@ -730,8 +747,14 @@ the following line to your URLconf::
730 747
 
731 748
         <form method="post" action=".">
732 749
         <table>
733  
-        <tr><td>{{ form.username.label_tag }}</td><td>{{ form.username }}</td></tr>
734  
-        <tr><td>{{ form.password.label_tag }}</td><td>{{ form.password }}</td></tr>
  750
+        <tr>
  751
+            <td>{{ form.username.label_tag }}</td>
  752
+            <td>{{ form.username }}</td>
  753
+        </tr>
  754
+        <tr>
  755
+            <td>{{ form.password.label_tag }}</td>
  756
+            <td>{{ form.password }}</td>
  757
+        </tr>
735 758
         </table>
736 759
 
737 760
         <input type="submit" value="login" />
@@ -746,15 +769,18 @@ the following line to your URLconf::
746 769
 Other built-in views
747 770
 --------------------
748 771
 
749  
-In addition to the ``login`` view, the authentication system includes a
750  
-few other useful built-in views:
  772
+In addition to the :func:`~views.login` view, the authentication system
  773
+includes a few other useful built-in views located in
  774
+:mod:`django.contrib.auth.views`:
751 775
 
752  
-.. function:: django.contrib.auth.views.logout
  776
+.. function:: views.logout(request, [next_page, template_name])
753 777
 
754 778
     Logs a user out.
755 779
 
756 780
     **Optional arguments:**
757 781
 
  782
+        * ``next_page``: The URL to redirect to after logout.
  783
+
758 784
         * ``template_name``: The full name of a template to display after
759 785
           logging the user out. This will default to
760 786
           :file:`registration/logged_out.html` if no argument is supplied.
@@ -763,17 +789,16 @@ few other useful built-in views:
763 789
 
764 790
         * ``title``: The string "Logged out", localized.
765 791
 
766  
-.. function:: django.contrib.auth.views.logout_then_login
  792
+.. function:: views.logout_then_login(request[, login_url])
767 793
 
768 794
     Logs a user out, then redirects to the login page.
769 795
 
770 796
     **Optional arguments:**
771 797
 
772  
-        * ``login_url``: The URL of the login page to redirect to. This
773  
-          will default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not
774  
-          supplied.
  798
+        * ``login_url``: The URL of the login page to redirect to. This will
  799
+          default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.
775 800
 
776  
-.. function:: django.contrib.auth.views.password_change
  801
+.. function:: views.password_change(request[, template_name, post_change_redirect])
777 802
 
778 803
     Allows a user to change their password.
779 804
 
@@ -783,11 +808,14 @@ few other useful built-in views:
783 808
           displaying the password change form. This will default to
784 809
           :file:`registration/password_change_form.html` if not supplied.
785 810
 
  811
+        * ``post_change_redirect``: The URL to redirect to after successful
  812
+          password change.
  813
+
786 814
     **Template context:**
787 815
 
788 816
         * ``form``: The password change form.
789 817
 
790  
-.. function:: django.contrib.auth.views.password_change_done
  818
+.. function:: views.password_change_done(request[, template_name])
791 819
 
792 820
     The page shown after a user has changed their password.
793 821
 
@@ -797,7 +825,7 @@ few other useful built-in views:
797 825
           default to :file:`registration/password_change_done.html` if not
798 826
           supplied.
799 827
 
800  
-.. function:: django.contrib.auth.views.password_reset
  828
+.. function:: views.password_reset
801 829
 
802 830
     Allows a user to reset their password, and sends them the new password
803 831
     in an e-mail.
@@ -816,7 +844,7 @@ few other useful built-in views:
816 844
 
817 845
         * ``form``: The form for resetting the user's password.
818 846
 
819  
-.. function:: django.contrib.auth.views.password_reset_done
  847
+.. function:: views.password_reset_done
820 848
 
821 849
     The page shown after a user has reset their password.
822 850
 
@@ -826,7 +854,7 @@ few other useful built-in views:
826 854
           default to :file:`registration/password_reset_done.html` if not
827 855
           supplied.
828 856
 
829  
-.. function:: django.contrib.auth.views.redirect_to_login
  857
+.. function:: views.redirect_to_login
830 858
 
831 859
     Redirects to the login page, and then back to another URL after a
832 860
     successful login.
@@ -837,42 +865,51 @@ few other useful built-in views:
837 865
 
838 866
     **Optional arguments:**
839 867
 
840  
-        * ``login_url``: The URL of the login page to redirect to. This
841  
-          will default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not
842  
-          supplied.
  868
+        * ``login_url``: The URL of the login page to redirect to. This will
  869
+          default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.
843 870
 
844 871
 Built-in forms
845  
----------------------
  872
+--------------
846 873
 
847  
-If you don't want to use the built-in views, but want the convenience
848  
-of not having to write forms for this functionality, the authentication
849  
-system provides several built-in forms:
  874
+.. module:: django.contrib.auth.forms
850 875
 
851  
-    * :class:`django.contrib.auth.forms.AdminPasswordChangeForm`: A form used
852  
-      in the admin interface to change a user's password.
  876
+If you don't want to use the built-in views, but want the convenience of not
  877
+having to write forms for this functionality, the authentication system
  878
+provides several built-in forms located in :mod:`django.contrib.auth.forms`:
853 879
 
854  
-    * :class:`django.contrib.auth.forms.AuthenticationForm`: A form for
855  
-      logging a user in.
  880
+.. class:: AdminPasswordChangeForm
856 881
 
857  
-    * :class:`django.contrib.auth.forms.PasswordChangeForm`: A form for
858  
-      allowing a user to change their password.
  882
+    A form used in the admin interface to change a user's password.
859 883
 
860  
-    * :class:`django.contrib.auth.forms.PasswordResetForm`: A form for
861  
-      resetting a user's password and e-mailing the new password to them.
  884
+.. class:: AuthenticationForm
862 885
 
863  
-    * :class:`django.contrib.auth.forms.UserCreationForm`: A form for creating
864  
-      a new user.
  886
+    A form for logging a user in.
  887
+
  888
+.. class:: PasswordChangeForm
  889
+
  890
+    A form for allowing a user to change their password.
  891
+
  892
+.. class:: PasswordResetForm
  893
+
  894
+    A form for resetting a user's password and e-mailing the new password to
  895
+    them.
  896
+
  897
+.. class:: UserCreationForm
  898
+
  899
+    A form for creating a new user.
865 900
 
866 901
 Limiting access to logged-in users that pass a test
867 902
 ---------------------------------------------------
868 903
 
  904
+.. currentmodule:: django.contrib.auth
  905
+
869 906
 To limit access based on certain permissions or some other test, you'd do
870 907
 essentially the same thing as described in the previous section.
871 908
 
872  
-The simple way is to run your test on
873  
-:attr:`request.user <django.http.HttpRequest.user>` in the view directly.
874  
-For example, this view checks to make sure the user is logged in and has the
875  
-permission ``polls.can_vote``::
  909
+The simple way is to run your test on :attr:`request.user
  910
+<django.http.HttpRequest.user>` in the view directly. For example, this view
  911
+checks to make sure the user is logged in and has the permission
  912
+``polls.can_vote``::
876 913
 
877 914
     def my_view(request):
878 915
         if not (request.user.is_authenticated() and request.user.has_perm('polls.can_vote')):
@@ -891,7 +928,7 @@ permission ``polls.can_vote``::
891 928
 
892 929
     We're using this particular test as a relatively simple example. However,
893 930
     if you just want to test whether a permission is available to a user, you
894  
-    can use the :func:`django.contrib.auth.decorators.permission_required()`
  931
+    can use the :func:`~django.contrib.auth.decorators.permission_required()`
895 932
     decorator, described later in this document.
896 933
 
897 934
     Here's the same thing, using Python 2.4's decorator syntax::
@@ -955,8 +992,8 @@ The permission_required decorator
955 992
             # ...
956 993
         my_view = permission_required('polls.can_vote', login_url='/loginpage/')(my_view)
957 994
 
958  
-    As in the ``login_required`` decorator, ``login_url`` defaults to
959  
-    :setting:`settings.LOGIN_URL <LOGIN_URL>`.
  995
+    As in the :func:`~decorators.login_required` decorator, ``login_url``
  996
+    defaults to :setting:`settings.LOGIN_URL <LOGIN_URL>`.
960 997
 
961 998
 Limiting access to generic views
962 999
 --------------------------------
@@ -1001,17 +1038,17 @@ Default permissions
1001 1038
 -------------------
1002 1039
 
1003 1040
 When ``django.contrib.auth`` is listed in your :setting:`INSTALLED_APPS`
1004  
-setting, it will ensure that three default permissions -- add, change
1005  
-and delete -- are created for each Django model defined in one of your
1006  
-installed applications.
1007  
-
1008  
-These permissions will be created when you run
1009  
-:djadmin:`manage.py syncdb <syncdb>`; the first time you run ``syncdb`` after
1010  
-adding ``django.contrib.auth`` to :setting:`INSTALLED_APPS`, the default
1011  
-permissions will be created for all previously-installed models, as well as
1012  
-for any new models being installed at that time. Afterward, it will create
1013  
-default permissions for new models each time you run
1014  
-:djadmin:`manage.py syncdb <syncdb>`.
  1041
+setting, it will ensure that three default permissions -- add, change and
  1042
+delete -- are created for each Django model defined in one of your installed
  1043
+applications.
  1044
+
  1045
+These permissions will be created when you run :djadmin:`manage.py syncdb
  1046
+<syncdb>`; the first time you run ``syncdb`` after adding
  1047
+``django.contrib.auth`` to :setting:`INSTALLED_APPS`, the default permissions
  1048
+will be created for all previously-installed models, as well as for any new
  1049
+models being installed at that time. Afterward, it will create default
  1050
+permissions for new models each time you run :djadmin:`manage.py syncdb
  1051
+<syncdb>`.
1015 1052
 
1016 1053
 .. _custom-permissions:
1017 1054
 
@@ -1040,8 +1077,8 @@ API reference
1040 1077
 
1041 1078
 .. class:: models.Permission
1042 1079
 
1043  
-    Just like users, permissions are implemented in a Django model that lives in
1044  
-    `django/contrib/auth/models.py`_.
  1080
+    Just like users, permissions are implemented in a Django model that lives
  1081
+    in `django/contrib/auth/models.py`_.
1045 1082
 
1046 1083
 .. _django/contrib/auth/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py
1047 1084
 
@@ -1057,8 +1094,8 @@ fields:
1057 1094
 
1058 1095
 .. attribute:: models.Permission.content_type
1059 1096
 
1060  
-    Required. A reference to the ``django_content_type`` database table,
1061  
-    which contains a record for each installed Django model.
  1097
+    Required. A reference to the ``django_content_type`` database table, which
  1098
+    contains a record for each installed Django model.
1062 1099
 
1063 1100
 .. attribute:: models.Permission.codename
1064 1101
 
@@ -1091,7 +1128,9 @@ Users
1091 1128
 The currently logged-in user, either a
1092 1129
 :class:`~django.contrib.auth.models.User` instance or an
1093 1130
 :class:`~django.contrib.auth.models.AnonymousUser` instance, is stored in the
1094  
-template variable ``{{ user }}``::
  1131
+template variable ``{{ user }}``:
  1132
+
  1133
+.. code-block:: html
1095 1134
 
1096 1135
     {% if user.is_authenticated %}
1097 1136
         <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
@@ -1121,7 +1160,9 @@ would display ``True`` if the logged-in user had the permission
1121 1160
 
1122 1161
     {{ perms.foo.can_vote }}
1123 1162
 
1124  
-Thus, you can check permissions in template ``{% if %}`` statements::
  1163
+Thus, you can check permissions in template ``{% if %}`` statements:
  1164
+
  1165
+.. code-block:: html
1125 1166
 
1126 1167
     {% if perms.foo %}
1127 1168
         <p>You have permission to do something in the foo app.</p>
@@ -1187,7 +1228,9 @@ a playlist::
1187 1228
 When you use :class:`~django.template.context.RequestContext`, the currently
1188 1229
 logged-in user and his/her messages are made available in the
1189 1230
 :ref:`template context <ref-templates-api>` as the template variable
1190  
-``{{ messages }}``. Here's an example of template code that displays messages::
  1231
+``{{ messages }}``. Here's an example of template code that displays messages:
  1232
+
  1233
+.. code-block:: html
1191 1234
 
1192 1235
     {% if messages %}
1193 1236
     <ul>
@@ -1229,10 +1272,10 @@ Specifying authentication backends
1229 1272
 
1230 1273
 Behind the scenes, Django maintains a list of "authentication backends" that it
1231 1274
 checks for authentication. When somebody calls
1232  
-:func:`django.contrib.auth.authenticate()` -- as described in "How to log a
1233  
-user in" above -- Django tries authenticating across all of its authentication
1234  
-backends. If the first authentication method fails, Django tries the second
1235  
-one, and so on, until all backends have been attempted.
  1275
+:func:`django.contrib.auth.authenticate()` -- as described in :ref:`How to log
  1276
+a user in` above -- Django tries authenticating across all of its
  1277
+authentication backends. If the first authentication method fails, Django tries
  1278
+the second one, and so on, until all backends have been attempted.
1236 1279
 
1237 1280
 The list of authentication backends to use is specified in the
1238 1281
 :setting:`AUTHENTICATION_BACKENDS` setting. This should be a tuple of Python
@@ -1245,9 +1288,9 @@ By default, :setting:`AUTHENTICATION_BACKENDS` is set to::
1245 1288
 
1246 1289
 That's the basic authentication scheme that checks the Django users database.
1247 1290
 
1248  
-The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same username
1249  
-and password is valid in multiple backends, Django will stop processing at the
1250  
-first positive match.
  1291
+The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same
  1292
+username and password is valid in multiple backends, Django will stop
  1293
+processing at the first positive match.
1251 1294
 
1252 1295
 Writing an authentication backend
1253 1296
 ---------------------------------
2  docs/topics/http/sessions.txt
@@ -122,7 +122,7 @@ It also has these methods:
122 122
       session key value that is sent back to the user in the cookie. This is
123 123
       used if you want to ensure that the previous session data can't be
124 124
       accessed again from the user's browser (for example, the
125  
-      ``django.contrib.auth.logout()`` method calls it).
  125
+      :func:`django.contrib.auth.logout()` function calls it).
126 126
 
127 127
     * ``set_test_cookie()``
128 128
 

0 notes on commit 910aa0e

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