mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-03-12 18:30:48 +00:00
Code Issues 32 Releases Wiki Activity

Auth-related doc cleanups:

Browse Source 
* 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).


git-svn-id: http://code.djangoproject.com/svn/django/trunk@9835 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Gary Wilson Jr 2009-02-16 05:10:31 +00:00
parent f76cb41251
commit 88837875f2
2 changed files with 223 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

401
docs/topics/auth.txt
View File

@ -58,12 +58,13 @@ Fields
.. class:: models.User .. class:: models.User
:class:`~django.contrib.auth.models.User` objects have the following fields: :class:`~django.contrib.auth.models.User` objects have the following
fields:
.. attribute:: models.User.username .. attribute:: models.User.username
Required. 30 characters or fewer. Alphanumeric characters only (letters, Required. 30 characters or fewer. Alphanumeric characters only
digits and underscores). (letters, digits and underscores).
.. attribute:: models.User.first_name .. attribute:: models.User.first_name
@ -92,17 +93,17 @@ Fields
Boolean. Designates whether this user account should be considered Boolean. Designates whether this user account should be considered
active. Set this flag to ``False`` instead of deleting accounts. active. Set this flag to ``False`` instead of deleting accounts.
This doesn't control whether or not the user can log in. Nothing in This doesn't control whether or not the user can log in. Nothing in the
the authentication path checks the ``is_active`` flag, so if you want authentication path checks the ``is_active`` flag, so if you want to
to reject a login based on ``is_active`` being ``False``, it is up to reject a login based on ``is_active`` being ``False``, it is up to you
you to check that in your own login view. However, permission checking to check that in your own login view. However, permission checking
using the methods like :meth:`~models.User.has_perm` does check this using the methods like :meth:`~models.User.has_perm` does check this
flag and will always return ``False`` for inactive users. flag and will always return ``False`` for inactive users.
.. attribute:: models.User.is_superuser .. attribute:: models.User.is_superuser
Boolean. Designates that this user has all permissions without explicitly Boolean. Designates that this user has all permissions without
assigning them. explicitly assigning them.
.. attribute:: models.User.last_login .. attribute:: models.User.last_login
@ -111,8 +112,8 @@ Fields
.. attribute:: models.User.date_joined .. attribute:: models.User.date_joined
A datetime designating when the account was created. Is set to the current A datetime designating when the account was created. Is set to the
date/time by default when the account is created. current date/time by default when the account is created.
Methods Methods
~~~~~~~ ~~~~~~~
@ -122,7 +123,8 @@ Methods
:class:`~django.contrib.auth.models.User` objects have two many-to-many :class:`~django.contrib.auth.models.User` objects have two many-to-many
fields: models.User. ``groups`` and ``user_permissions``. fields: models.User. ``groups`` and ``user_permissions``.
:class:`~django.contrib.auth.models.User` objects can access their related :class:`~django.contrib.auth.models.User` objects can access their related
objects in the same way as any other :ref:`Django model <topics-db-models>`: objects in the same way as any other :ref:`Django model
<topics-db-models>`:
.. code-block:: python .. code-block:: python
@ -150,16 +152,16 @@ Methods
.. method:: models.User.is_authenticated() .. method:: models.User.is_authenticated()
Always returns ``True``. This is a way to Always returns ``True``. This is a way to tell if the user has been
tell if the user has been authenticated. This does not imply any authenticated. This does not imply any permissions, and doesn't check
permissions, and doesn't check if the user is active - it only indicates if the user is active - it only indicates that the user has provided a
that the user has provided a valid username and password. valid username and password.
.. method:: models.User.get_full_name() .. method:: models.User.get_full_name()
Returns the :attr:`~django.contrib.auth.models.User.first_name` plus the Returns the :attr:`~django.contrib.auth.models.User.first_name` plus
:attr:`~django.contrib.auth.models.User.last_name`, the :attr:`~django.contrib.auth.models.User.last_name`, with a space in
with a space in between. between.
.. method:: models.User.set_password(raw_password) .. method:: models.User.set_password(raw_password)
@ -169,15 +171,16 @@ Methods
.. method:: models.User.check_password(raw_password) .. method:: models.User.check_password(raw_password)
Returns ``True`` if the given raw string is the correct password for the Returns ``True`` if the given raw string is the correct password for
user. (This takes care of the password hashing in making the comparison.) the user. (This takes care of the password hashing in making the
comparison.)
.. method:: models.User.set_unusable_password() .. method:: models.User.set_unusable_password()
.. versionadded:: 1.0 .. versionadded:: 1.0
Marks the user as having no password set. This isn't the same as having Marks the user as having no password set. This isn't the same as
a blank string for a password. having a blank string for a password.
:meth:`~django.contrib.auth.models.User.check_password()` for this user :meth:`~django.contrib.auth.models.User.check_password()` for this user
will never return ``True``. Doesn't save the will never return ``True``. Doesn't save the
:class:`~django.contrib.auth.models.User` object. :class:`~django.contrib.auth.models.User` object.
@ -200,31 +203,31 @@ Methods
.. method:: models.User.get_all_permissions() .. method:: models.User.get_all_permissions()
Returns a list of permission strings that the user has, both through group Returns a list of permission strings that the user has, both through
and user permissions. group and user permissions.
.. method:: models.User.has_perm(perm) .. method:: models.User.has_perm(perm)
Returns ``True`` if the user has the specified permission, where perm is Returns ``True`` if the user has the specified permission, where perm
in the format ``"package.codename"``. If the user is inactive, this method is in the format ``"package.codename"``. If the user is inactive, this
will always return ``False``. method will always return ``False``.
.. method:: models.User.has_perms(perm_list) .. method:: models.User.has_perms(perm_list)
Returns ``True`` if the user has each of the specified permissions, where Returns ``True`` if the user has each of the specified permissions,
each perm is in the format ``"package.codename"``. If the user is inactive, where each perm is in the format ``"package.codename"``. If the user is
this method will always return ``False``. inactive, this method will always return ``False``.
.. method:: models.User.has_module_perms(package_name) .. method:: models.User.has_module_perms(package_name)
Returns ``True`` if the user has any permissions in the given package (the Returns ``True`` if the user has any permissions in the given package
Django app label). If the user is inactive, this method will always return (the Django app label). If the user is inactive, this method will
``False``. always return ``False``.
.. method:: models.User.get_and_delete_messages() .. method:: models.User.get_and_delete_messages()
Returns a list of :class:`~django.contrib.auth.models.Message` objects in Returns a list of :class:`~django.contrib.auth.models.Message` objects
the user's queue and deletes the messages from the queue. in the user's queue and deletes the messages from the queue.
.. method:: models.User.email_user(subject, message, from_email=None) .. method:: models.User.email_user(subject, message, from_email=None)
@ -235,10 +238,10 @@ Methods
.. method:: models.User.get_profile() .. method:: models.User.get_profile()
Returns a site-specific profile for this user. Raises Returns a site-specific profile for this user. Raises
:exc:`django.contrib.auth.models.SiteProfileNotAvailable` if the current :exc:`django.contrib.auth.models.SiteProfileNotAvailable` if the
site doesn't allow profiles. For information on how to define a current site doesn't allow profiles. For information on how to define a
site-specific user profile, see the section on site-specific user profile, see the section on `storing additional user
`storing additional user information`_ below. information`_ below.
.. _storing additional user information: #storing-additional-information-about-users .. _storing additional user information: #storing-additional-information-about-users
@ -255,12 +258,12 @@ Manager functions
Creates, saves and returns a :class:`~django.contrib.auth.models.User`. Creates, saves and returns a :class:`~django.contrib.auth.models.User`.
The :attr:`~django.contrib.auth.models.User.username`, The :attr:`~django.contrib.auth.models.User.username`,
:attr:`~django.contrib.auth.models.User.email` and :attr:`~django.contrib.auth.models.User.email` and
:attr:`~django.contrib.auth.models.User.password` are set as given, and the :attr:`~django.contrib.auth.models.User.password` are set as given, and
:class:`~django.contrib.auth.models.User` gets ``is_active=True``. the :class:`~django.contrib.auth.models.User` gets ``is_active=True``.
If no password is provided, If no password is provided,
:meth:`~django.contrib.auth.models.User.set_unusable_password()` will be :meth:`~django.contrib.auth.models.User.set_unusable_password()` will
called. be called.
See `Creating users`_ for example usage. See `Creating users`_ for example usage.
@ -268,8 +271,12 @@ Manager functions
Returns a random password with the given length and given string of Returns a random password with the given length and given string of
allowed characters. (Note that the default value of ``allowed_chars`` allowed characters. (Note that the default value of ``allowed_chars``
doesn't contain letters that can cause user confusion, including ``1``, doesn't contain letters that can cause user confusion, including:
``I`` and ``0``).
* ``i``, ``l``, ``I``, and ``1`` (lowercase letter i, lowercase
letter L, uppercase letter i, and the number one)
* ``o``, ``O``, and ``0`` (uppercase letter o, lowercase letter o,
and zero)
Basic usage Basic usage
----------- -----------
@ -310,7 +317,9 @@ Django requires add *and* change permissions as a slight security measure.
Changing passwords Changing passwords
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
Change a password with :meth:`~django.contrib.auth.models.User.set_password()`:: Change a password with :meth:`~django.contrib.auth.models.User.set_password()`:
.. code-block:: python
>>> from django.contrib.auth.models import User >>> from django.contrib.auth.models import User
>>> u = User.objects.get(username__exact='john') >>> u = User.objects.get(username__exact='john')
@ -365,15 +374,18 @@ Anonymous users
* :attr:`~django.contrib.auth.models.User.id` is always ``None``. * :attr:`~django.contrib.auth.models.User.id` is always ``None``.
* :attr:`~django.contrib.auth.models.User.is_staff` and * :attr:`~django.contrib.auth.models.User.is_staff` and
:attr:`~django.contrib.auth.models.User.is_superuser` are always ``False``. :attr:`~django.contrib.auth.models.User.is_superuser` are always
``False``.
* :attr:`~django.contrib.auth.models.User.is_active` is always ``False``. * :attr:`~django.contrib.auth.models.User.is_active` is always ``False``.
* :attr:`~django.contrib.auth.models.User.groups` and * :attr:`~django.contrib.auth.models.User.groups` and
:attr:`~django.contrib.auth.models.User.user_permissions` are always empty. :attr:`~django.contrib.auth.models.User.user_permissions` are always
empty.
* :meth:`~django.contrib.auth.models.User.is_anonymous()` returns ``True`` * :meth:`~django.contrib.auth.models.User.is_anonymous()` returns ``True``
instead of ``False``. instead of ``False``.
* :meth:`~django.contrib.auth.models.User.is_authenticated()` returns * :meth:`~django.contrib.auth.models.User.is_authenticated()` returns
``False`` instead of ``True``. ``False`` instead of ``True``.
* :meth:`~django.contrib.auth.models.User.has_perm()` always returns ``False``. * :meth:`~django.contrib.auth.models.User.has_perm()` always returns
``False``.
* :meth:`~django.contrib.auth.models.User.set_password()`, * :meth:`~django.contrib.auth.models.User.set_password()`,
:meth:`~django.contrib.auth.models.User.check_password()`, :meth:`~django.contrib.auth.models.User.check_password()`,
:meth:`~django.contrib.auth.models.User.save()`, :meth:`~django.contrib.auth.models.User.save()`,
@ -392,10 +404,10 @@ Creating superusers
.. versionadded:: 1.0 .. versionadded:: 1.0
The ``manage.py createsuperuser`` command is new. The ``manage.py createsuperuser`` command is new.
:djadmin:`manage.py syncdb <syncdb>` prompts you to create a superuser the first time :djadmin:`manage.py syncdb <syncdb>` prompts you to create a superuser the
you run it after adding ``'django.contrib.auth'`` to your first time you run it after adding ``'django.contrib.auth'`` to your
:setting:`INSTALLED_APPS`. If you need to create a superuser at a later date, :setting:`INSTALLED_APPS`. If you need to create a superuser at a later date,
you can use a command line utility. you can use a command line utility::
manage.py createsuperuser --username=joe --email=joe@example.com manage.py createsuperuser --username=joe --email=joe@example.com
@ -409,48 +421,47 @@ on the command line still works::
python /path/to/django/contrib/auth/create_superuser.py python /path/to/django/contrib/auth/create_superuser.py
...where :file:`/path/to` is the path to the Django codebase on your ...where :file:`/path/to` is the path to the Django codebase on your
filesystem. The ``manage.py`` command is preferred because it figures filesystem. The ``manage.py`` command is preferred because it figures out the
out the correct path and environment for you. correct path and environment for you.
.. _auth-profiles: .. _auth-profiles:
Storing additional information about users Storing additional information about users
------------------------------------------ ------------------------------------------
If you'd like to store additional information related to your users, If you'd like to store additional information related to your users, Django
Django provides a method to specify a site-specific related model -- provides a method to specify a site-specific related model -- termed a "user
termed a "user profile" -- for this purpose. profile" -- for this purpose.
To make use of this feature, define a model with fields for the To make use of this feature, define a model with fields for the additional
additional information you'd like to store, or additional methods information you'd like to store, or additional methods you'd like to have
you'd like to have available, and also add a available, and also add a :class:`~django.db.models.Field.ForeignKey` from your
:class:`~django.db.models.Field.ForeignKey` from your model to the model to the :class:`~django.contrib.auth.models.User` model, specified with
:class:`~django.contrib.auth.models.User` model, specified with ``unique=True`` ``unique=True`` to ensure only one instance of your model can be created for
to ensure only one instance of your model can be created for each each :class:`~django.contrib.auth.models.User`.
:class:`~django.contrib.auth.models.User`.
To indicate that this model is the user profile model for a given To indicate that this model is the user profile model for a given site, fill in
site, fill in the setting :setting:`AUTH_PROFILE_MODULE` with a string the setting :setting:`AUTH_PROFILE_MODULE` with a string consisting of the
consisting of the following items, separated by a dot: following items, separated by a dot:
1. The (normalized to lower-case) name of the application in which the 1. The (normalized to lower-case) name of the application in which the user
user profile model is defined (in other words, an all-lowercase profile model is defined (in other words, an all-lowercase version of the
version of the name which was passed to name which was passed to :djadmin:`manage.py startapp <startapp>` to create
:djadmin:`manage.py startapp <startapp>` to create the application). the application).
2. The (normalized to lower-case) name of the model class. 2. The (normalized to lower-case) name of the model class.
For example, if the profile model was a class named ``UserProfile`` For example, if the profile model was a class named ``UserProfile`` and was
and was defined inside an application named ``accounts``, the defined inside an application named ``accounts``, the appropriate setting would
appropriate setting would be:: be::
AUTH_PROFILE_MODULE = 'accounts.userprofile' AUTH_PROFILE_MODULE = 'accounts.userprofile'
When a user profile model has been defined and specified in this When a user profile model has been defined and specified in this manner, each
manner, each :class:`~django.contrib.auth.models.User` object will have a :class:`~django.contrib.auth.models.User` object will have a method --
method -- :class:`~django.contrib.auth.models.User.get_profile()` :class:`~django.contrib.auth.models.User.get_profile()` -- which returns the
-- which returns the instance of the user profile model associated instance of the user profile model associated with that
with that :class:`~django.contrib.auth.models.User`. :class:`~django.contrib.auth.models.User`.
For more information, see `Chapter 12 of the Django book`_. For more information, see `Chapter 12 of the Django book`_.
@ -485,6 +496,8 @@ section). You can tell them apart with
else: else:
# Do something for anonymous users. # Do something for anonymous users.
.. _howtologauserin:
How to log a user in How to log a user in
-------------------- --------------------
@ -495,10 +508,10 @@ Django provides two functions in :mod:`django.contrib.auth`:
.. function:: authenticate() .. function:: authenticate()
To authenticate a given username and password, use To authenticate a given username and password, use
:func:`~django.contrib.auth.authenticate()`. It :func:`~django.contrib.auth.authenticate()`. It takes two keyword
takes two keyword arguments, ``username`` and ``password``, and it returns arguments, ``username`` and ``password``, and it returns a
a :class:`~django.contrib.auth.models.User` object if the password is :class:`~django.contrib.auth.models.User` object if the password is valid
valid for the given username. If the password is invalid, for the given username. If the password is invalid,
:func:`~django.contrib.auth.authenticate()` returns ``None``. Example:: :func:`~django.contrib.auth.authenticate()` returns ``None``. Example::
from django.contrib.auth import authenticate from django.contrib.auth import authenticate
@ -546,9 +559,9 @@ Django provides two functions in :mod:`django.contrib.auth`:
:func:`~django.contrib.auth.login()`. :func:`~django.contrib.auth.login()`.
:func:`~django.contrib.auth.authenticate()` :func:`~django.contrib.auth.authenticate()`
sets an attribute on the :class:`~django.contrib.auth.models.User` noting sets an attribute on the :class:`~django.contrib.auth.models.User` noting
which authentication backend successfully authenticated that user (see which authentication backend successfully authenticated that user (see the
the `backends documentation`_ for details), and this information is `backends documentation`_ for details), and this information is needed
needed later during the login process. later during the login process.
.. _backends documentation: #other-authentication-sources .. _backends documentation: #other-authentication-sources
@ -557,12 +570,12 @@ Manually checking a user's password
.. function:: check_password() .. function:: check_password()
If you'd like to manually authenticate a user by comparing a If you'd like to manually authenticate a user by comparing a plain-text
plain-text password to the hashed password in the database, use the password to the hashed password in the database, use the convenience
convenience function :func:`django.contrib.auth.models.check_password`. It function :func:`django.contrib.auth.models.check_password`. It takes two
takes two arguments: the plain-text password to check, and the full arguments: the plain-text password to check, and the full value of a user's
value of a user's ``password`` field in the database to check against, ``password`` field in the database to check against, and returns ``True``
and returns ``True`` if they match, ``False`` otherwise. if they match, ``False`` otherwise.
How to log a user out How to log a user out
--------------------- ---------------------
@ -581,18 +594,18 @@ How to log a user out
logout(request) logout(request)
# Redirect to a success page. # Redirect to a success page.
Note that :func:`~django.contrib.auth.logout()` doesn't throw any errors Note that :func:`~django.contrib.auth.logout()` doesn't throw any errors if
if the user wasn't logged in. the user wasn't logged in.
.. versionchanged:: 1.0 .. versionchanged:: 1.0
Calling ``logout()`` now cleans session data. Calling ``logout()`` now cleans session data.
When you call :func:`~django.contrib.auth.logout()`, the session When you call :func:`~django.contrib.auth.logout()`, the session data for
data for the current request is completely cleaned out. All existing data the current request is completely cleaned out. All existing data is
is removed. This is to prevent another person from using the same web removed. This is to prevent another person from using the same web browser
browser to log in and have access to the previous user's session data. to log in and have access to the previous user's session data. If you want
If you want to put anything into the session that will be available to to put anything into the session that will be available to the user
the user immediately after logging out, do that *after* calling immediately after logging out, do that *after* calling
:func:`django.contrib.auth.logout()`. :func:`django.contrib.auth.logout()`.
Limiting access to logged-in users Limiting access to logged-in users
@ -669,8 +682,8 @@ The login_required decorator
``next`` or the value of ``redirect_field_name``. For example: ``next`` or the value of ``redirect_field_name``. For example:
``/accounts/login/?next=/polls/3/``. ``/accounts/login/?next=/polls/3/``.
* If the user is logged in, execute the view normally. The view code * If the user is logged in, execute the view normally. The view code is
is free to assume the user is logged in. free to assume the user is logged in.
Note that you'll need to map the appropriate Django view to Note that you'll need to map the appropriate Django view to
:setting:`settings.LOGIN_URL <LOGIN_URL>`. For example, using the defaults, add :setting:`settings.LOGIN_URL <LOGIN_URL>`. For example, using the defaults, add
@ -682,31 +695,33 @@ the following line to your URLconf::
Here's what ``django.contrib.auth.views.login`` does: Here's what ``django.contrib.auth.views.login`` does:
* If called via ``GET``, it displays a login form that POSTs to the same * If called via ``GET``, it displays a login form that POSTs to the
URL. More on this in a bit. same URL. More on this in a bit.
* If called via ``POST``, it tries to log the user in. If login is * If called via ``POST``, it tries to log the user in. If login is
successful, the view redirects to the URL specified in ``next``. If successful, the view redirects to the URL specified in ``next``. If
``next`` isn't provided, it redirects to :setting:`settings.LOGIN_REDIRECT_URL <LOGIN_REDIRECT_URL>` ``next`` isn't provided, it redirects to
(which defaults to ``/accounts/profile/``). If login isn't successful, :setting:`settings.LOGIN_REDIRECT_URL <LOGIN_REDIRECT_URL>` (which
it redisplays the login form. defaults to ``/accounts/profile/``). If login isn't successful, it
redisplays the login form.
It's your responsibility to provide the login form in a template called It's your responsibility to provide the login form in a template called
``registration/login.html`` by default. This template gets passed three ``registration/login.html`` by default. This template gets passed three
template context variables: template context variables:
* ``form``: A :class:`~django.forms.Form` object representing the * ``form``: A :class:`~django.forms.Form` object representing the login
login form. See the :ref:`forms documentation <topics-forms-index>` form. See the :ref:`forms documentation <topics-forms-index>` for
for more on ``Form`` objects. more on ``Form`` objects.
* ``next``: The URL to redirect to after successful login. This may contain * ``next``: The URL to redirect to after successful login. This may
a query string, too. contain a query string, too.
* ``site_name``: The name of the current * ``site_name``: The name of the current
:class:`~django.contrib.sites.models.Site`, according to the :class:`~django.contrib.sites.models.Site`, according to the
:setting:`SITE_ID` setting. If you're using the Django development version :setting:`SITE_ID` setting. If you're using the Django development
and you don't have the site framework installed, this will be set to the version and you don't have the site framework installed, this will be
value of ``request.META['SERVER_NAME']``. For more on sites, see set to the value of :attr:`request.META['SERVER_NAME']
<django.http.HttpRequest.META>`. For more on sites, see
:ref:`ref-contrib-sites`. :ref:`ref-contrib-sites`.
If you'd prefer not to call the template :file:`registration/login.html`, If you'd prefer not to call the template :file:`registration/login.html`,
@ -718,7 +733,9 @@ the following line to your URLconf::
Here's a sample :file:`registration/login.html` template you can use as a Here's a sample :file:`registration/login.html` template you can use as a
starting point. It assumes you have a :file:`base.html` template that starting point. It assumes you have a :file:`base.html` template that
defines a ``content`` block:: defines a ``content`` block:
.. code-block:: html
{% extends "base.html" %} {% extends "base.html" %}
@ -730,8 +747,14 @@ the following line to your URLconf::
<form method="post" action="."> <form method="post" action=".">
<table> <table>
<tr><td>{{ form.username.label_tag }}</td><td>{{ form.username }}</td></tr> <tr>
<tr><td>{{ form.password.label_tag }}</td><td>{{ form.password }}</td></tr> <td>{{ form.username.label_tag }}</td>
<td>{{ form.username }}</td>
</tr>
<tr>
<td>{{ form.password.label_tag }}</td>
<td>{{ form.password }}</td>
</tr>
</table> </table>
<input type="submit" value="login" /> <input type="submit" value="login" />
@ -746,15 +769,18 @@ the following line to your URLconf::
Other built-in views Other built-in views
-------------------- --------------------
In addition to the ``login`` view, the authentication system includes a In addition to the :func:`~views.login` view, the authentication system
few other useful built-in views: includes a few other useful built-in views located in
:mod:`django.contrib.auth.views`:
.. function:: django.contrib.auth.views.logout .. function:: views.logout(request, [next_page, template_name])
Logs a user out. Logs a user out.
**Optional arguments:** **Optional arguments:**
* ``next_page``: The URL to redirect to after logout.
* ``template_name``: The full name of a template to display after * ``template_name``: The full name of a template to display after
logging the user out. This will default to logging the user out. This will default to
:file:`registration/logged_out.html` if no argument is supplied. :file:`registration/logged_out.html` if no argument is supplied.
@ -763,17 +789,16 @@ few other useful built-in views:
* ``title``: The string "Logged out", localized. * ``title``: The string "Logged out", localized.
.. function:: django.contrib.auth.views.logout_then_login .. function:: views.logout_then_login(request[, login_url])
Logs a user out, then redirects to the login page. Logs a user out, then redirects to the login page.
**Optional arguments:** **Optional arguments:**
* ``login_url``: The URL of the login page to redirect to. This * ``login_url``: The URL of the login page to redirect to. This will
will default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.
supplied.
.. function:: django.contrib.auth.views.password_change .. function:: views.password_change(request[, template_name, post_change_redirect])
Allows a user to change their password. Allows a user to change their password.
@ -783,11 +808,14 @@ few other useful built-in views:
displaying the password change form. This will default to displaying the password change form. This will default to
:file:`registration/password_change_form.html` if not supplied. :file:`registration/password_change_form.html` if not supplied.
* ``post_change_redirect``: The URL to redirect to after successful
password change.
**Template context:** **Template context:**
* ``form``: The password change form. * ``form``: The password change form.
.. function:: django.contrib.auth.views.password_change_done .. function:: views.password_change_done(request[, template_name])
The page shown after a user has changed their password. The page shown after a user has changed their password.
@ -797,7 +825,7 @@ few other useful built-in views:
default to :file:`registration/password_change_done.html` if not default to :file:`registration/password_change_done.html` if not
supplied. supplied.
.. function:: django.contrib.auth.views.password_reset .. function:: views.password_reset
Allows a user to reset their password, and sends them the new password Allows a user to reset their password, and sends them the new password
in an e-mail. in an e-mail.
@ -816,7 +844,7 @@ few other useful built-in views:
* ``form``: The form for resetting the user's password. * ``form``: The form for resetting the user's password.
.. function:: django.contrib.auth.views.password_reset_done .. function:: views.password_reset_done
The page shown after a user has reset their password. The page shown after a user has reset their password.
@ -826,7 +854,7 @@ few other useful built-in views:
default to :file:`registration/password_reset_done.html` if not default to :file:`registration/password_reset_done.html` if not
supplied. supplied.
.. function:: django.contrib.auth.views.redirect_to_login .. function:: views.redirect_to_login
Redirects to the login page, and then back to another URL after a Redirects to the login page, and then back to another URL after a
successful login. successful login.
@ -837,42 +865,51 @@ few other useful built-in views:
**Optional arguments:** **Optional arguments:**
* ``login_url``: The URL of the login page to redirect to. This * ``login_url``: The URL of the login page to redirect to. This will
will default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.
supplied.
Built-in forms Built-in forms
--------------------- --------------
If you don't want to use the built-in views, but want the convenience .. module:: django.contrib.auth.forms
of not having to write forms for this functionality, the authentication
system provides several built-in forms:
* :class:`django.contrib.auth.forms.AdminPasswordChangeForm`: A form used If you don't want to use the built-in views, but want the convenience of not
in the admin interface to change a user's password. having to write forms for this functionality, the authentication system
provides several built-in forms located in :mod:`django.contrib.auth.forms`:
* :class:`django.contrib.auth.forms.AuthenticationForm`: A form for .. class:: AdminPasswordChangeForm
logging a user in.
* :class:`django.contrib.auth.forms.PasswordChangeForm`: A form for A form used in the admin interface to change a user's password.
allowing a user to change their password.
* :class:`django.contrib.auth.forms.PasswordResetForm`: A form for .. class:: AuthenticationForm
resetting a user's password and e-mailing the new password to them.
* :class:`django.contrib.auth.forms.UserCreationForm`: A form for creating A form for logging a user in.
a new user.
.. class:: PasswordChangeForm
A form for allowing a user to change their password.
.. class:: PasswordResetForm
A form for resetting a user's password and e-mailing the new password to
them.
.. class:: UserCreationForm
A form for creating a new user.
Limiting access to logged-in users that pass a test Limiting access to logged-in users that pass a test
--------------------------------------------------- ---------------------------------------------------
.. currentmodule:: django.contrib.auth
To limit access based on certain permissions or some other test, you'd do To limit access based on certain permissions or some other test, you'd do
essentially the same thing as described in the previous section. essentially the same thing as described in the previous section.
The simple way is to run your test on The simple way is to run your test on :attr:`request.user
:attr:`request.user <django.http.HttpRequest.user>` in the view directly. <django.http.HttpRequest.user>` in the view directly. For example, this view
For example, this view checks to make sure the user is logged in and has the checks to make sure the user is logged in and has the permission
permission ``polls.can_vote``:: ``polls.can_vote``::
def my_view(request): def my_view(request):
if not (request.user.is_authenticated() and request.user.has_perm('polls.can_vote')): if not (request.user.is_authenticated() and request.user.has_perm('polls.can_vote')):
@ -891,7 +928,7 @@ permission ``polls.can_vote``::
We're using this particular test as a relatively simple example. However, We're using this particular test as a relatively simple example. However,
if you just want to test whether a permission is available to a user, you if you just want to test whether a permission is available to a user, you
can use the :func:`django.contrib.auth.decorators.permission_required()` can use the :func:`~django.contrib.auth.decorators.permission_required()`
decorator, described later in this document. decorator, described later in this document.
Here's the same thing, using Python 2.4's decorator syntax:: Here's the same thing, using Python 2.4's decorator syntax::
@ -955,8 +992,8 @@ The permission_required decorator
# ... # ...
my_view = permission_required('polls.can_vote', login_url='/loginpage/')(my_view) my_view = permission_required('polls.can_vote', login_url='/loginpage/')(my_view)
As in the ``login_required`` decorator, ``login_url`` defaults to As in the :func:`~decorators.login_required` decorator, ``login_url``
:setting:`settings.LOGIN_URL <LOGIN_URL>`. defaults to :setting:`settings.LOGIN_URL <LOGIN_URL>`.
Limiting access to generic views Limiting access to generic views
-------------------------------- --------------------------------
@ -1001,17 +1038,17 @@ Default permissions
------------------- -------------------
When ``django.contrib.auth`` is listed in your :setting:`INSTALLED_APPS` When ``django.contrib.auth`` is listed in your :setting:`INSTALLED_APPS`
setting, it will ensure that three default permissions -- add, change setting, it will ensure that three default permissions -- add, change and
and delete -- are created for each Django model defined in one of your delete -- are created for each Django model defined in one of your installed
installed applications. applications.
These permissions will be created when you run These permissions will be created when you run :djadmin:`manage.py syncdb
:djadmin:`manage.py syncdb <syncdb>`; the first time you run ``syncdb`` after <syncdb>`; the first time you run ``syncdb`` after adding
adding ``django.contrib.auth`` to :setting:`INSTALLED_APPS`, the default ``django.contrib.auth`` to :setting:`INSTALLED_APPS`, the default permissions
permissions will be created for all previously-installed models, as well as will be created for all previously-installed models, as well as for any new
for any new models being installed at that time. Afterward, it will create models being installed at that time. Afterward, it will create default
default permissions for new models each time you run permissions for new models each time you run :djadmin:`manage.py syncdb
:djadmin:`manage.py syncdb <syncdb>`. <syncdb>`.
.. _custom-permissions: .. _custom-permissions:
@ -1040,8 +1077,8 @@ API reference
.. class:: models.Permission .. class:: models.Permission
Just like users, permissions are implemented in a Django model that lives in Just like users, permissions are implemented in a Django model that lives
`django/contrib/auth/models.py`_. in `django/contrib/auth/models.py`_.
.. _django/contrib/auth/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py .. _django/contrib/auth/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py
@ -1057,8 +1094,8 @@ fields:
.. attribute:: models.Permission.content_type .. attribute:: models.Permission.content_type
Required. A reference to the ``django_content_type`` database table, Required. A reference to the ``django_content_type`` database table, which
which contains a record for each installed Django model. contains a record for each installed Django model.
.. attribute:: models.Permission.codename .. attribute:: models.Permission.codename
@ -1091,7 +1128,9 @@ Users
The currently logged-in user, either a The currently logged-in user, either a
:class:`~django.contrib.auth.models.User` instance or an :class:`~django.contrib.auth.models.User` instance or an
:class:`~django.contrib.auth.models.AnonymousUser` instance, is stored in the :class:`~django.contrib.auth.models.AnonymousUser` instance, is stored in the
template variable ``{{ user }}``:: template variable ``{{ user }}``:
.. code-block:: html
{% if user.is_authenticated %} {% if user.is_authenticated %}
<p>Welcome, {{ user.username }}. Thanks for logging in.</p> <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
@ -1121,7 +1160,9 @@ would display ``True`` if the logged-in user had the permission
{{ perms.foo.can_vote }} {{ perms.foo.can_vote }}
Thus, you can check permissions in template ``{% if %}`` statements:: Thus, you can check permissions in template ``{% if %}`` statements:
.. code-block:: html
{% if perms.foo %} {% if perms.foo %}
<p>You have permission to do something in the foo app.</p> <p>You have permission to do something in the foo app.</p>
@ -1187,7 +1228,9 @@ a playlist::
When you use :class:`~django.template.context.RequestContext`, the currently When you use :class:`~django.template.context.RequestContext`, the currently
logged-in user and his/her messages are made available in the logged-in user and his/her messages are made available in the
:ref:`template context <ref-templates-api>` as the template variable :ref:`template context <ref-templates-api>` as the template variable
``{{ messages }}``. Here's an example of template code that displays messages:: ``{{ messages }}``. Here's an example of template code that displays messages:
.. code-block:: html
{% if messages %} {% if messages %}
<ul> <ul>
@ -1229,10 +1272,10 @@ Specifying authentication backends
Behind the scenes, Django maintains a list of "authentication backends" that it Behind the scenes, Django maintains a list of "authentication backends" that it
checks for authentication. When somebody calls checks for authentication. When somebody calls
:func:`django.contrib.auth.authenticate()` -- as described in "How to log a :func:`django.contrib.auth.authenticate()` -- as described in :ref:`How to log
user in" above -- Django tries authenticating across all of its authentication a user in` above -- Django tries authenticating across all of its
backends. If the first authentication method fails, Django tries the second authentication backends. If the first authentication method fails, Django tries
one, and so on, until all backends have been attempted. the second one, and so on, until all backends have been attempted.
The list of authentication backends to use is specified in the The list of authentication backends to use is specified in the
:setting:`AUTHENTICATION_BACKENDS` setting. This should be a tuple of Python :setting:`AUTHENTICATION_BACKENDS` setting. This should be a tuple of Python
@ -1245,9 +1288,9 @@ By default, :setting:`AUTHENTICATION_BACKENDS` is set to::
That's the basic authentication scheme that checks the Django users database. That's the basic authentication scheme that checks the Django users database.
The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same username The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same
and password is valid in multiple backends, Django will stop processing at the username and password is valid in multiple backends, Django will stop
first positive match. processing at the first positive match.
Writing an authentication backend Writing an authentication backend
--------------------------------- ---------------------------------

2
docs/topics/http/sessions.txt
View File

@ -145,7 +145,7 @@ It also has these methods:
session key value that is sent back to the user in the cookie. This is session key value that is sent back to the user in the cookie. This is
used if you want to ensure that the previous session data can't be used if you want to ensure that the previous session data can't be
accessed again from the user's browser (for example, the accessed again from the user's browser (for example, the
``django.contrib.auth.logout()`` method calls it). :func:`django.contrib.auth.logout()` function calls it).
* ``set_test_cookie()`` * ``set_test_cookie()``