Finished docs/authentication.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@1127 bcc190cf-cafb-0310-a4f2-bffc1f526a37

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.