Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Finished docs/authentication.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@1127 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 8b71b9b87001b80df71262c505812bf285210874 1 parent c7b28cf
@adrianholovaty adrianholovaty authored
Showing with 193 additions and 5 deletions.
  1. +193 −5 docs/authentication.txt
View
198 docs/authentication.txt
@@ -147,8 +147,9 @@ The most basic way to create users is to use the standard Django
... is_active=True, is_superuser=False)
>>> u.save()
-Note that ``password_md5`` requires the raw MD5 hash. Because that's a pain,
-there's a ``create_user`` helper function::
+Note that ``password_md5`` requires the raw MD5 hash (as created by
+``md5.new().hexdigest()``). Because that's a pain, there's a ``create_user``
+helper function::
>>> from django.models.auth import users
>>> u = users.create_user('john', 'lennon@thebeatles.com', 'johnpassword')
@@ -196,7 +197,12 @@ previous section). You can tell them apart with ``is_anonymous()``, like so::
else:
# Do something for logged-in users.
+If you want to use ``request.user`` in your view code, make sure you have
+``SessionMiddleware`` enabled. See the `session documentation`_ for more
+information.
+
.. _request objects: http://www.djangoproject.com/documentation/request_response/#httprequest-objects
+.. _session documentation: http://www.djangoproject.com/documentation/sessions/
Limiting access to logged-in users
----------------------------------
@@ -251,8 +257,8 @@ Here's the same thing, using Python 2.4's decorator syntax::
Limiting access to logged-in users that pass a test
---------------------------------------------------
-To limit access based on certain permissions or another test, you'd do the same
-thing as described in the previous section.
+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 ``request.user`` in the view directly.
For example, this view checks to make sure the user is logged in and has the
@@ -276,13 +282,195 @@ As a shortcut, you can use the convenient ``user_passes_test`` decorator::
Note that ``user_passes_test`` does not automatically check that the ``User``
is not anonymous.
+Permissions
+===========
+
+Django comes with a simple permissions system. It provides a way to assign
+permissions to specific users and groups of users.
+
+It's used by the Django admin site, but you're welcome to use it in your own
+code.
+
+The Django admin site uses permissions as follows:
+
+ * Access to view the "add" form and add an object is limited to users with
+ the "add" permission for that type of object.
+ * Access to view the change list, view the "change" form and change an
+ object is limited to users with the "change" permission for that type of
+ object.
+ * Access to delete an object is limited to users with the "delete"
+ permission for that type of object.
+
+Permissions are set globally per type of object, not per specific object
+instance. For example, it's possible to say "Mary may change news stories," but
+it's not currently possible to say "Mary may change news stories, but only the
+ones she created herself" or "Mary may only change news stories that have a
+certain status or publication date." The latter functionality is something
+Django developers are currently discussing.
+
+Default permissions
+-------------------
+
+Three basic permissions -- add, create and delete -- are automatically created
+for each Django model that has ``admin`` set. Behind the scenes, these
+permissions are added to the ``auth_permissions`` database table when you run
+``django-admin.py install [app]``. You can view the exact SQL ``INSERT``
+statements by running ``django-admin.py sqlinitialdata [app]``.
+
+Note that if your model doesn't have ``admin`` set when you run
+``django-admin.py install``, the permissions won't be created. If you
+initialize your database and add ``admin`` to models after the fact, you'll
+need to add the permissions to the database manually. Do this by running
+``django-admin.py installperms [app]``, which creates any missing permissions
+for the given app.
+
+Custom permissions
+------------------
+
+To create custom permissions for a given model object, use the ``permissions``
+`model META attribute`_.
+
+This example model creates three custom permissions::
+
+ class USCitizen(meta.Model):
+ # ...
+ class META:
+ permissions = (
+ ("can_drive", "Can drive"),
+ ("can_vote", "Can vote in elections"),
+ ("can_drink", "Can drink alcohol"),
+ )
+
+.. _model META attribute: http://www.djangoproject.com/documentation/model_api/#meta-options
+
+API reference
+-------------
+
+Just like users, permissions are implemented in a Django model that lives in
+`django/models/auth.py`_.
+
+Fields
+~~~~~~
+
+``Permission`` objects have the following fields:
+
+ * ``name`` -- Required. 50 characters or fewer. Example: ``'Can vote'``.
+ * ``package`` -- Required. A reference to the ``packages`` database table,
+ which contains a record for each installed Django application.
+ * ``codename`` -- Required. 100 characters or fewer. Example: ``'can_vote'``.
+
+Methods
+~~~~~~~
+
+``Permission`` objects have the standard data-access methods like any other
+`Django model`_:
+
+Authentication data in templates
+================================
+
+The currently logged-in user and his/her permissions are made available in the
+`template context`_ when you use ``DjangoContext``.
+
+Users
+-----
+
+The currently logged-in user, either a ``User`` object or an``AnonymousUser``
+instance, is stored in the template variable ``{{ user }}``::
+ {% if user.is_anonymous %}
+ <p>Welcome, new user. Please log in.</p>
+ {% else %}
+ <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
+ {% endif %}
Permissions
-===========
+-----------
+
+The currently logged-in user's permissions are stored in the template variable
+``{{ perms }}``. This is an instance of ``django.core.extensions.PermWrapper``,
+which is a template-friendly proxy of permissions.
+
+In the ``{{ perms }}`` object, single-attribute lookup is a proxy to
+``User.has_module_perms``. This example would display ``True`` if the logged-in
+user had any permissions in the ``foo`` app::
+
+ {{ perms.foo }}
+
+Two-level-attribute lookup is a proxy to ``User.has_perm``. This example would
+display ``True`` if the logged-in user had the permission ``foo.can_vote``::
+
+ {{ perms.foo.can_vote }}
+
+Thus, you can check permissions in template ``{% if %}`` statements::
+
+ {% if perms.foo %}
+ <p>You have permission to do something in the foo app.</p>
+ {% if perms.foo.can_vote %}
+ <p>You can vote!</p>
+ {% endif %}
+ {% if perms.foo.can_drive %}
+ <p>You can drive!</p>
+ {% endif %}
+ {% else %}
+ <p>You don't have permission to do anything in the foo app.</p>
+ {% endif %}
+
+.. _template context: http://www.djangoproject.com/documentation/models/templates_python/
Groups
======
+Groups are a generic way of categorizing users to apply permissions, or some
+other label, to those users. A user can belong to any number of groups.
+
+A user in a group automatically has the permissions granted to that group. For
+example, if the group ``Site editors`` has the permission
+``can_edit_home_page``, any user in that group will have that permission.
+
+Beyond permissions, groups are a convenient way to categorize users to apply
+some label, or extended functionality, to them. For example, you could create
+a group ``'Special users'``, and you could write code that would do special
+things to those users -- such as giving them access to a members-only portion
+of your site, or sending them members-only e-mail messages.
+
Messages
========
+
+The message system is a lightweight way to queue messages for given users.
+
+A message is associated with a User. There's no concept of expiration or
+timestamps.
+
+Messages are used by the Django admin after successful actions. For example,
+``"The poll Foo was created successfully."`` is a message.
+
+The API is simple::
+
+ * To add messages, use ``user.add_message(message_text)``.
+ * To retrieve/delete messages, use ``user.get_and_delete_messages()``,
+ which returns a list of ``Message`` objects in the user's queue (if any)
+ and deletes the messages from the queue.
+
+In this example view, the system saves a message for the user after creating
+a playlist::
+
+ def create_playlist(request, songs):
+ # Create the playlist with the given songs.
+ # ...
+ request.user.add_message("Your playlist was added successfully.")
+ return render_to_response("playlists/create", context_instance=DjangoContext)
+
+When you use ``DjangoContext``, the currently logged-in user and his/her
+messages are made available in the `template context`_ as the template variable
+``{{ messages }}``. Here's an example of template code that displays messages::
+
+ {% if messages %}
+ <ul>
+ {% for message in messages %}
+ <li>{{ message.message }}</li>
+ {% endfor %}
+ </ul>
+ {% endif %}
+
+Note that ``DjangoContext`` calls ``get_and_delete_messages`` behind the
+scenes, so any messages will be deleted even if you don't display them.
Please sign in to comment.
Something went wrong with that request. Please try again.