p31829507
/
django
mirror of https://github.com/django/django.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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).


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