From f7e00af2c3f5ec096222ab900cb55d7a9355a644 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Tue, 4 Apr 2006 12:28:17 +0000 Subject: [PATCH] magic-removal: Updated documentation for authentication app. git-svn-id: http://code.djangoproject.com/svn/django/branches/magic-removal@2609 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/authentication.txt | 50 ++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/docs/authentication.txt b/docs/authentication.txt index 8c96c62082..48ea8892eb 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -27,9 +27,9 @@ Users ===== Users are represented by a standard Django model, which lives in -`django/models/auth.py`_. +`django/contrib/auth/models.py`_. -.. _django/models/auth.py: http://code.djangoproject.com/browser/django/trunk/django/models/auth.py +.. _django/contrib/auth/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py API reference ------------- @@ -62,13 +62,17 @@ Methods ~~~~~~~ ``User`` objects have two many-to-many fields: ``groups`` and -``user_permissions``. Because of those relationships, ``User`` objects get -data-access methods like any other `Django model`_: +``user_permissions``. ``User`` objects can access their related +objects in the same way as any other `Django model`_: - * ``get_group_list(**kwargs)`` - * ``set_groups(id_list)`` - * ``get_permission_list(**kwargs)`` - * ``set_user_permissions(id_list)`` + * ``myuser.objects.groups = [group_list]`` + * ``myuser.objects.groups.add(group, group,...)`` + * ``myuser.objects.groups.remove(group, group,...)`` + * ``myuser.objects.groups.clear()`` + * ``myuser.objects.permissions = [permission_list]`` + * ``myuser.objects.permissions.add(permission, permission, ...)`` + * ``myuser.objects.permissions.remove(permission, permission, ...]`` + * ``myuser.objects.permissions.clear()`` In addition to those automatic API methods, ``User`` objects have the following methods: @@ -116,10 +120,10 @@ methods: .. _Django model: http://www.djangoproject.com/documentation/model_api/ .. _DEFAULT_FROM_EMAIL: http://www.djangoproject.com/documentation/settings/#default-from-email -Module functions -~~~~~~~~~~~~~~~~ +Manager functions +~~~~~~~~~~~~~~~~~ -The ``django.models.auth.users`` module has the following helper functions: +The ``User`` model has a custom manager that has the following helper functions: * ``create_user(username, email, password)`` -- Creates, saves and returns a ``User``. The ``username``, ``email`` and ``password`` are set as @@ -140,10 +144,10 @@ Creating users The most basic way to create users is to use the ``create_user`` helper function that comes with Django:: - >>> from django.models.auth import users - >>> user = users.create_user('john', 'lennon@thebeatles.com', 'johnpassword') + >>> from django.contrib.auth.models import User + >>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword') - # Now, user is a User object already saved to the database. + # At this point, user is a User object ready to be saved to the database. # You can continue to change its attributes if you want to change other fields. >>> user.is_staff = True >>> user.save() @@ -153,8 +157,8 @@ Changing passwords Change a password with ``set_password()``:: - >>> from django.models.auth import users - >>> u = users.get_object(username__exact='john') + >>> from django.contrib.auth.models import User + >>> u = User.objects.get(username__exact='john') >>> u.set_password('new password') >>> u.save() @@ -192,8 +196,8 @@ the ``django.models.auth.users.User`` interface, with these differences: * ``id`` is always ``None``. * ``is_anonymous()`` returns ``True`` instead of ``False``. * ``has_perm()`` always returns ``False``. - * ``set_password()``, ``check_password()``, ``set_groups()`` and - ``set_permissions()`` raise ``NotImplementedError``. + * ``set_password()``, ``check_password()``, ``save()``, ``delete()``, + ``set_groups()`` and ``set_permissions()`` raise ``NotImplementedError``. In practice, you probably won't need to use ``AnonymousUser`` objects on your own, but they're used by Web requests, as explained in the next section. @@ -216,8 +220,8 @@ previous section). You can tell them apart with ``is_anonymous()``, like so:: # 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. +``SessionMiddleware`` and ``AuthenticationMiddleware`` 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/ @@ -407,7 +411,7 @@ To create custom permissions for a given model object, use the ``permissions`` This example model creates three custom permissions:: - class USCitizen(meta.Model): + class USCitizen(models.Model): # ... class Meta: permissions = ( @@ -530,7 +534,7 @@ Messages are used by the Django admin after successful actions. For example, The API is simple:: - * To add messages, use ``user.add_message(message_text)``. + * To create a new message, use ``user.message_set.create(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. @@ -541,7 +545,7 @@ a playlist:: def create_playlist(request, songs): # Create the playlist with the given songs. # ... - request.user.add_message("Your playlist was added successfully.") + request.user.message_set.create(message="Your playlist was added successfully.") return render_to_response("playlists/create", context_instance=RequestContext(request)) When you use ``RequestContext``, the currently logged-in user and his/her