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
parent
f76cb41251
commit
88837875f2
|
|
@ -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
|
||||
---------------------------------
|
||||
|
|
|
|||
|
|
@ -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()``
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue