Django——用python语言写的开源web开发框架

.. _topics-auth: ============================= User authentication in Django ============================= .. module:: django.contrib.auth :synopsis: Django's authentication framework. Django comes with a user authentication system. It handles user accounts, groups, permissions and cookie-based user sessions. This document explains how things work. Overview ======== The auth system consists of: * Users * Permissions: Binary (yes/no) flags designating whether a user may perform a certain task. * Groups: A generic way of applying labels and permissions to more than one user. * Messages: A simple way to queue messages for given users. Installation ============ Authentication support is bundled as a Django application in ``django.contrib.auth``. To install it, do the following: 1. Put ``'django.contrib.auth'`` in your :setting:`INSTALLED_APPS` setting. 2. Run the command ``manage.py syncdb``. Note that the default :file:`settings.py` file created by :djadmin:`django-admin.py startproject` includes ``'django.contrib.auth'`` in :setting:`INSTALLED_APPS` for convenience. If your :setting:`INSTALLED_APPS` already contains ``'django.contrib.auth'``, feel free to run :djadmin:`manage.py syncdb` again; you can run that command as many times as you'd like, and each time it'll only install what's needed. The :djadmin:`syncdb` command creates the necessary database tables, creates permission objects for all installed apps that need 'em, and prompts you to create a superuser account the first time you run it. Once you've taken those steps, that's it. Users ===== .. class:: models.User API reference ------------- Fields ~~~~~~ .. class:: models.User :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). .. attribute:: models.User.first_name Optional. 30 characters or fewer. .. attribute:: models.User.last_name Optional. 30 characters or fewer. .. attribute:: models.User.email Optional. E-mail address. .. attribute:: models.User.password Required. A hash of, and metadata about, the password. (Django doesn't store the raw password.) Raw passwords can be arbitrarily long and can contain any character. See the "Passwords" section below. .. attribute:: models.User.is_staff Boolean. Designates whether this user can access the admin site. .. attribute:: models.User.is_active Boolean. Designates whether this account can be used to log in. Set this flag to ``False`` instead of deleting accounts. .. attribute:: models.User.is_superuser Boolean. Designates that this user has all permissions without explicitly assigning them. .. attribute:: models.User.last_login A datetime of the user's last login. Is set to the current date/time by default. .. 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. Methods ~~~~~~~ .. class:: models.User :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>`: .. code-block:: python myuser.groups = [group_list] myuser.groups.add(group, group, ...) myuser.groups.remove(group, group, ...) myuser.groups.clear() myuser.user_permissions = [permission_list] myuser.user_permissions.add(permission, permission, ...) myuser.user_permissions.remove(permission, permission, ...) myuser.user_permissions.clear() In addition to those automatic API methods, :class:`~django.contrib.auth.models.User` objects have the following custom methods: .. method:: models.User.is_anonymous() Always returns ``False``. This is a way of differentiating :class:`~django.contrib.auth.models.User` and :class:`~django.contrib.auth.models.AnonymousUser` objects. Generally, you should prefer using :meth:`~django.contrib.auth.models.User.is_authenticated()` to this method. .. 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. .. 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. .. method:: models.User.set_password(raw_password) Sets the user's password to the given raw string, taking care of the password hashing. Doesn't save the :class:`~django.contrib.auth.models.User` object. .. 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.) .. 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. :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. You may need this if authentication for your application takes place against an existing external source such as an LDAP directory. .. method:: models.User.has_usable_password() .. versionadded:: 1.0 Returns ``False`` if :meth:`~django.contrib.auth.models.User.set_unusable_password()` has been called for this user. .. method:: models.User.get_group_permissions() Returns a list of permission strings that the user has, through his/her groups. .. method:: models.User.get_all_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``. .. 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``. .. 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``. .. 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. .. method:: models.User.email_user(subject, message, from_email=None) Sends an e-mail to the user. If :attr:`~django.contrib.auth.models.User.from_email` is ``None``, Django uses the :setting:`DEFAULT_FROM_EMAIL`. .. 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