The Django Book

Getting and Setting Cookies

存�Cookies

When dealing with persistence in Django, most of the time youll want to use the higher-level session and/or user frameworks discussed a little later in this chapter. However, well pause and look at how to read and write cookies at a low level. This should help you understand how the rest of the tools discussed in the chapter actually work, and it will come in handy if you ever need to play with cookies directly.

在Django中处��久化，大部分时候你会更愿�用高层些的session 和/或 ���讨论的user 框架。但在此之�，我们需��下�在底层看看如何读写cookies。这会帮助你�解本章节���讨论的工具是如何工作的，而且如果你需�自己�作cookies，这也会有所帮助。

Reading cookies that are already set is incredibly simple. Every request object has a COOKIES object that acts like a dictionary; you can use it to read any cookies that the browser has sent to the view:

读�已�设置好的cookies�其简�，�个request对象都有一个 COOKIES 对象，�以象使用字典般使用它，你�以读�任何�览器�给视图(view)的任何cookies:

def show_color(request):
    if "favorite_color" in request.COOKIES:
        return HttpResponse("Your favorite color is %s" % \
            request.COOKIES["favorite_color"])
    else:
        return HttpResponse("You don't have a favorite color.")

Writing cookies is slightly more complicated. You need to use the set_cookie() method on an HttpResponse object. Heres an example that sets the favorite_color cookie based on a GET parameter:

写cookies�微��点，需�用 HttpResponse 对象的 set_cookie() 方法�写。这儿有个基于 GET �数�设置 favorite_color cookie的例�：

def set_color(request):
    if "favorite_color" in request.GET:

        # Create an HttpResponse object...
        response = HttpResponse("Your favorite color is now %s" % \
            request.GET["favorite_color"])

        # ... and set a cookie on the response
        response.set_cookie("favorite_color",
                            request.GET["favorite_color"])

        return response

    else:
        return HttpResponse("You didn't give a favorite color.")

You can also pass a number of optional arguments to response.set_cookie() that control aspects of the cookie, as shown in Table 12-1.

你�以给 response.set_cookie() 传递一些�选的�数�控制cookie的行为，详�表12-1。

The Mixed Blessing of Cookies

好���的Cookies

You might notice a number of potential problems with the way cookies work. Lets look at some of the more important ones:

也许你已�注�到了，cookies的工作方��能导致的问题，一起�看看其中一些��的方�：

Storage of cookies is essentially voluntary; browsers dont guarantee anything. In fact, all browsers enable users to control the policy for accepting cookies. If you want to see just how vital cookies are to the Web, try turning on your browsers prompt to accept every cookie option.

cookies存�完全是�强制性的，�览器���这一点。事实上，所有的�览器都让用户自己控制 是�接�cookies。如果你想知�cookies对于web应用有多��，你�以试�打开这个�览器的 选项：�示我接��次cookie。

Despite their nearly universal use, cookies are still the definition of unreliability. This means that developers should check that a user actually accepts cookies before relying on them.

尽管cookies广为使用，但�被认为是���的的。这�味�，开�者使用cookies之�必须 检查用户是��以接收cookie。

More important, you should never store important data in cookies. The Web is filled with horror stories of developers whove stored unrecoverable information in browser cookies only to have that data purged by the browser for one reason or another.

更��的是，*永远* 也��在cookie中存储��的数�。开�者在cookie中存储了���� 的数�，而�览器�因为��原因将cookie中的数�清得一干二净，这样令人�指的故事在 Web世界中比比皆是。

Cookies (especially those not sent over HTTPS) are not secure. Because HTTP data is sent in cleartext, cookies are extremely vulnerable to snooping attacks. That is, an attacker snooping on the wire can intercept a cookie and read it. This means you should never store sensitive information in a cookie.

Cookie(特别是那些没通过HTTPS传输的)是�常�安全的。因为HTTP数�是以明文��的，所以 特别容易�到嗅探攻击。也就是说，嗅探攻击者�以在网络中拦截并读�cookies，因此你� �对��在cookies中存储�感信�。

Theres an even more insidious attack, known as a man-in-the-middle attack, wherein an attacker intercepts a cookie and uses it to pose as another user. Chapter 19 discusses attacks of this nature in depth, as well as ways to prevent it.

还有一ç§�被称为”中间人”的攻击更阴险，攻击者拦截一个cookie并将其用于å�¦ä¸€ä¸ªç”¨æˆ·ã€‚ 第19章将深入讨论这ç§�攻击的本质以å�Šå¦‚何é�¿å…�。

Cookies arent even secure from their intended recipients. Most browsers provide easy ways to edit the content of individual cookies, and resourceful users can always use tools like mechanize ( http://wwwsearch.sourceforge.net/mechanize/ ) to construct HTTP requests by hand.

�使从预想中的接收者返回的cookie也是�安全的，因为大多数�览器都�供了很方便的方法� 修改cookies的内容，有技术背景的用户甚至�以用�mechanize ( http://wwwsearch.sourceforge.net/mechanize/ ) 这样的工具�手工构造HTTP请求。

So you cant store data in cookies that might be sensitive to tampering. The canonical mistake in this scenario is storing something like IsLoggedIn=1 in a cookie when a user logs in. Youd be amazed at the number of sites that make mistakes of this nature; it takes only a second to fool these sites security systems.

因此�能在cookies中存储�能会被篡改的�感数�，“�典�错误是：在cookies中存储 IsLoggedIn=1 ，以标识用户已�登录。犯这类错误的站点数�多的令人难以置信； 绕过这些网站的安全系统也是易如�掌。

Enabling Sessions

打开 Sessions功能

Sessions are implemented via a piece of middleware (see Chapter 15) and a Django model. To enable sessions, youll need to follow these steps:

Sessions 功能是通过一个中间件(middleware)和一个模型(model)�实现的。�打开sessions功能，需�以下几步�作：

1. Edit your MIDDLEWARE_CLASSES setting and make sure MIDDLEWARE_CLASSES contains 'django.contrib.sessions.middleware.SessionMiddleware' .

1. 编辑 MIDDLEWARE_CLASSES �置，确� MIDDLEWARE_CLASSES 中包� 'django.contrib.sessions.middleware.SessionMiddleware'

2. Make sure 'django.contrib.sessions' is in your INSTALLED_APPS setting (and run manage.py syncdb if you have to add it).

2. 确认 INSTALLED_APPS 中有 'django.contrib.sessions' (如果你是刚打开这个应用，别忘了�行 manage.py syncdb )

The default skeleton settings created by startproject have both of these bits already installed, so unless youve removed them, you probably dont have to change anything to get sessions to work.

如果项目是用 startproject �创建的，�置文件中都已�安装了这些东西，除�你自己删除，正常情况下，你无需任何设置就�以使用session功能。

If you dont want to use sessions, you might want to remove the SessionMiddleware line from MIDDLEWARE_CLASSES and 'django.contrib.sessions' from your INSTALLED_APPS . It will save you only a small amount of overhead, but every little bit counts.

如果�需�session功能，你�以删除 MIDDLEWARE_CLASSES 设置中的 SessionMiddleware 和 INSTALLED_APPS 设置中的 'django.contrib.sessions' 。虽然这�会节�很少的开销，但积少�多啊。

Using Sessions in Views

在视图中使用Session

When SessionMiddleware is activated, each HttpRequest objectthe first argument to any Django view functionwill have a session attribute, which is a dictionary-like object. You can read it and write to it in the same way youd use a normal dictionary. For example, in a view you could do stuff like this:

SessionMiddleware 激活�，�个传给视图(view)函数的第一个�数``HttpRequest`` 对象都有一个 session 属性，这是一个字典型的对象。你�以象用普通字典一样�用它。例如，在视图(view)中你�以这样用：

# Set a session value:
request.session["fav_color"] = "blue"

# Get a session value -- this could be called in a different view,
# or many requests later (or both):
fav_color = request.session["fav_color"]

# Clear an item from the session:
del request.session["fav_color"]

# Check if the session has a given key:
if "fav_color" in request.session:
    ...

You can also use other mapping methods like keys() and items() on request.session .

其他的映射方法，如 keys() 和 items() 对 request.session �样有效：

There are a couple of simple rules for using Djangos sessions effectively:

下�是一些有效使用Django sessions的简�规则：

• Use normal Python strings as dictionary keys on request.session (as opposed to integers, objects, etc.). This is more of a convention than a hard-and-fast rule, but its worth following.

• 用正常的字符串作为keyæ�¥è®¿é—®å­—å…¸ request.session ， 而ä¸�是整数ã€�对象或其它什么的。 è¿™ä¸�是什么强硬的æ�¡è§„，但值得é�µå¾ªã€‚

• Session dictionary keys that begin with an underscore are reserved for internal use by Django. In practice, the framework uses only a small number of underscore-prefixed session variables, but unless you know what they all are (and you are willing to keep up with any changes in Django itself), staying away from underscore prefixes will keep Django from interfering with your application.

• Session字典中以下划线开头的key值是Django内部ä¿�ç•™key值。框架å�ªä¼šç”¨å¾ˆå°‘的几个下划线 开头的sessionå�˜é‡�，除é�žä½ çŸ¥é�“他们的具体å�«ä¹‰ï¼Œè€Œä¸”æ„¿æ„�跟上Djangoçš„å�˜åŒ–，å�¦åˆ™ï¼Œæœ€å¥½ ä¸�è¦�用这些下划线开头的å�˜é‡�，它们会让Djangoæ�…乱你的应用。

• Dont replace request.session with a new object, and dont access or set its attributes. Use it like a Python dictionary.

• ä¸�è¦�用一个新对象æ�¥æ›¿æ�¢æŽ‰ request.session ，也ä¸�è¦�å­˜å�–其属性，象用普通Python字典一样用它。

Lets take a look at a few quick examples. This simplistic view sets a has_commented variable to True after a user posts a comment. Its a simple (but not particularly secure) way of preventing a user from posting more than one comment:

我们�看个简�的例�。这是个简�到�能�简�的例�：在用户�了一次评论�将 has_commented 设置为 True ，这是个简�（但�很安全）的�防止用户多次评论的方法。

def post_comment(request, new_comment):
    if request.session.get('has_commented', False):
        return HttpResponse("You've already commented.")
    c = comments.Comment(comment=new_comment)
    c.save()
    request.session['has_commented'] = True
    return HttpResponse('Thanks for your comment!')

This simplistic view logs in a member of the site:

下�是一个很简�的站点登录视图(view)：

def login(request):
    try:
        m = Member.objects.get(username__exact=request.POST['username'])
        if m.password == request.POST['password']:
            request.session['member_id'] = m.id
            return HttpResponse("You're logged in.")
    except Member.DoesNotExist:
        return HttpResponse("Your username and password didn't match.")

And this one logs out a member, according to login() :

这是退出登录，根� login() :

def logout(request):
    try:
        del request.session['member_id']
    except KeyError:
        pass
    return HttpResponse("You're logged out.")

Note

注�

In practice, this is a lousy way of logging users in. The authentication framework discussed shortly handles this task for you in a much more robust and useful manner. These examples are deliberately simplistic so that you can easily see whats going on.

在实践中，这是很烂的用户登录方�，��讨论的认�(authentication )框架会帮你以更�壮和有利的方��处�这些问题。这些�常简�的例��是想让你知�这一切是如何工作的。

Setting Test Cookies

设置测试Cookies

As just mentioned, you cant rely on every browser accepting cookies. So, as a convenience, Django provides an easy way to test whether a users browser accepts cookies. You just need to call request.session.set_test_cookie() in a view, and check request.session.test_cookie_worked() in a subsequent viewnot in the same view call.

就����到的，你�能指望所有的�览器都�以接�cookie，因此，Django为了方便，也�供了检查用户�览器是�接�cookie的简�方法。你�需在视图(view)中调用 request.session.set_test_cookie() ，并在�续的视图(view)�而�是当�的视图(view)中检查 request.session.test_cookie_worked() 。

This awkward split between set_test_cookie() and test_cookie_worked() is necessary due to the way cookies work. When you set a cookie, you cant actually tell whether a browser accepted it until the browsers next request.

虽然把 set_test_cookie() 和 test_cookie_worked() 分开的�法看起�有些笨拙，但由于cookie的工作方�，这无���。当设置一个cookie时候，�能等�览器下次访问的时候，你�能知��览器是�接�cookie。

Its good practice to use delete_test_cookie() to clean up after yourself. Do this after youve verified that the test cookie worked.

检查cookie是��以正常工作�，你得自己用 delete_test_cookie() �清除它，这是个好习惯。

Heres a typical usage example:

这是个典型例�：

def login(request):

    # If we submitted the form...
    if request.method == 'POST':

        # Check that the test cookie worked (we set it below):
        if request.session.test_cookie_worked():

            # The test cookie worked, so delete it.
            request.session.delete_test_cookie()

            # In practice, we'd need some logic to check username/password
            # here, but since this is an example...
            return HttpResponse("You're logged in.")

        # The test cookie failed, so display an error message. If this
        # was a real site we'd want to display a friendlier message.
        else:
            return HttpResponse("Please enable cookies and try again.")

    # If we didn't post, send the test cookie along with the login form.
    request.session.set_test_cookie()
    return render_to_response('foo/login_form.html')

Note

注�

Again, the built-in authentication functions handle this check for you.

�次强调，内置的认�函数会帮你�检查的。

Using Sessions Outside of Views

在视图(View)外使用Session

Internally, each session is just a normal Django model defined in django.contrib.sessions.models . Each session is identified by a more-or-less random 32-character hash stored in a cookie. Because its a normal model, you can access sessions using the normal Django database API:

从内部�看，�个session都�是一个普通的Django model（在 django.contrib.sessions.models 中定义)。�个session都由一个�机的32字节哈希串�标识，并存储于数�库中。由于这是一个普通的model，你�以用一般的Django 数�库API�读�session。

>>> from django.contrib.sessions.models import Session
>>> s = Session.objects.get(pk='2b1189a188b44ad18c35e113ac6ceead')
>>> s.expire_date
datetime.datetime(2005, 8, 20, 13, 35, 12)

Youll need to call get_decoded() to get the actual session data. This is necessary because the dictionary is stored in an encoded format:

你得用 get_decoded() �读�实际的session数�，因为session字典�过了编�存储。

>>> s.session_data
'KGRwMQpTJ19hdXRoX3VzZXJfaWQnCnAyCkkxCnMuMTExY2ZjODI2Yj...'
>>> s.get_decoded()
{'user_id': 42}

When Sessions Are Saved

何时�存Session

By default, Django only saves to the database if the session has been modified that is, if any of its dictionary values have been assigned or deleted:

缺�的情况下，Django�会在session�生�化的时候�会存入数�库，比如说，字典赋值或删除。

# Session is modified.
request.session['foo'] = 'bar'

# Session is modified.
del request.session['foo']

# Session is modified.
request.session['foo'] = {}

# Gotcha: Session is NOT modified, because this alters
# request.session['foo'] instead of request.session.
request.session['foo']['bar'] = 'baz'

To change this default behavior, set SESSION_SAVE_EVERY_REQUEST to True . If SESSION_SAVE_EVERY_REQUEST is True , Django will save the session to the database on every single request, even if it wasnt changed.

你�以设置 SESSION_SAVE_EVERY_REQUEST 为 True �改�这一缺�行为。如果 SESSION_SAVE_EVERY_REQUEST 设置为 True ，Django 会在�次请求的时候都把session存到数�库中，�使没有任何改�。

Note that the session cookie is sent only when a session has been created or modified. If SESSION_SAVE_EVERY_REQUEST is True , the session cookie will be sent on every request. Similarly, the expires part of a session cookie is updated each time the session cookie is sent.

注�，会�cookie�会在创建和修改的时候�会�出。但如果 SESSION_SAVE_EVERY_REQUEST 设置为 True ，会�cookie会在�次请求的时候都会�出。�时，�次会�cookie�出的时候，其 expires �数都会更新。

Browser-Length Sessions vs. Persistent Sessions

�览器关闭�失效会� vs. �久会�

You might have noticed that the cookie Google sent us contained expires=Sun, 17-Jan-2038 19:14:07 GMT; . Cookies can optionally contain an expiration date that advises the browser on when to remove the cookie. If a cookie doesnt contain an expiration value, the browser will expire it when the user closes his or her browser window. You can control the session frameworks behavior in this regard with the SESSION_EXPIRE_AT_BROWSER_CLOSE setting.

你�能注�到了，Google给我们��的cookie中有 expires=Sun, 17-Jan-2038 19:14:07 GMT; cookie�以有过期时间，这样�览器就知�什么时候�以删除cookie了。如果cookie没有设置过期时间，当用户关闭�览器的时候，cookie就自动过期了。你�以改� SESSION_EXPIRE_AT_BROWSER_CLOSE 的设置�控制session框架的这一行为。

By default, SESSION_EXPIRE_AT_BROWSER_CLOSE is set to False , which means session cookies will be stored in users browsers for SESSION_COOKIE_AGE seconds (which defaults to two weeks, or 1,209,600 seconds). Use this if you dont want people to have to log in every time they open a browser.

缺�情况下， SESSION_EXPIRE_AT_BROWSER_CLOSE 设置为 False ，这样，会�cookie�以在用户�览器中��有效达 SESSION_COOKIE_AGE 秒（缺�设置是两周，�1,209,600 秒）。如果你�想用户�次打开�览器都必须�新登陆的�，用这个�数�帮你。

If SESSION_EXPIRE_AT_BROWSER_CLOSE is set to True , Django will use browser-length cookies.

如果 SESSION_EXPIRE_AT_BROWSER_CLOSE 设置为 True ，当�览器关闭时，Django会使cookie失效。

Other Session Settings

其他的Session设置

Besides the settings already mentioned, a few other settings influence how Djangos session framework uses cookies, as shown in Table 12-2.

除了上��到的设置，还有一些其他的设置�以影�Django session框架如何使用cookie，详�表 12-2.

Technical Details

技术细节

For the curious, here are a few technical notes about the inner workings of the session framework:

如果你还是好奇的�，下�是一些关于session框架内部工作方�的技术细节：

The session dictionary accepts any Python object capable of being pickled. See the documentation for Pythons built-in pickle module for information about how this works.

session 字典和普通Python对象一样，支��列化，详�Python文档中内置 pickle 模�的部分。

Session data is stored in a database table named django_session .

Session 数�存在数�库表 django_session 中

Session data is fetched upon demand. If you never access request.session , Django wont hit that database table.

Session 数�在需�的时候�会读�，如果你从�使用 request.session ， Django�会动相关数�库表的一根毛。

Django only sends a cookie if it needs to. If you dont set any session data, it wont send a session cookie (unless SESSION_SAVE_EVERY_REQUEST is set to True ).

Django �在需�的时候��出cookie。如果你压根儿就没有设置任何会�数�，它�会 �出会�cookie(除� SESSION_SAVE_EVERY_REQUEST 设置为 True )

The Django sessions framework is entirely, and solely, cookie based. It does not fall back to putting session IDs in URLs as a last resort, as some other tools (PHP, JSP) do.

Django session 框架完全而且�能基于cookie，�会�退到把会�ID编�在URL中。（��些工具(PHP,JSP)那样）

This is an intentional design decision. Putting sessions in URLs dont just make URLs ugly, but also make your site vulnerable to a certain form of session ID theft via the Referer header.

这是一个有æ„�而为之的设计，把session放在URL中ä¸�å�ªæ˜¯éš¾çœ‹ï¼Œæ›´é‡�è¦�的是这让你的站点 很容易å�—到攻击——通过 Referer header进行session ID”窃å�¬”而实施的攻击。

If youre still curious, the source is pretty straightforward; look in django.contrib.sessions for more details.

如果你还是好奇，阅读�代�是最直接办法，详� django.contrib.sessions 。

Enabling Authentication Support

打开认�支�

Like the session tools, authentication support is bundled as a Django application in django.contrib , which needs to be installed. Like the session system, its also installed by default, but if youve removed it, youll need to follow these steps to install it:

�session工具一样，认�支�也是一个Django应用，放在 django.contrib 中，所以也需�安装。与session系统相似，它也是缺�安装的，但如果它已�被删除了，通过以下步骤也能�新安装上：

1. Make sure the session framework is installed as described earlier in this chapter. Keeping track of users obviously requires cookies, and thus builds on the session framework.

1. 根�本章早�的部分确认已�安装了session 框架，需�确认用户使用cookie，这样sesson 框架�能正常使用。

2. Put 'django.contrib.auth' in your INSTALLED_APPS setting and run manage.py syncdb .

2. 将 'django.contrib.auth' 放在你的 INSTALLED_APPS 设置中，然��行 manage.py syncdb

3. Make sure that 'django.contrib.auth.middleware.AuthenticationMiddleware' is in your MIDDLEWARE_CLASSES setting*after* SessionMiddleware .

3. 确认 SessionMiddleware ��的 MIDDLEWARE_CLASSES 设置中包� 'django.contrib.auth.middleware.AuthenticationMiddleware'

With that installation out of the way, were ready to deal with users in view functions. The main interface youll use to access users within a view is request.user ; this is an object that represents the currently logged-in user. If the user isnt logged in, this will instead be an AnonymousUser object (see below for more details).

这样安装�，我们就�以在视图(view)的函数中用处�user了。在视图中存�users，主�用 request.user ；这个对象表示当�已登录的用户，如果用户还没登录，这就是一个 匿� 对象(细节�下)

You can easily tell if a user is logged in with the is_authenticated() method:

你�以很容易的通过 is_authenticated() 方法�判断一个用户是�已�登录了

if request.user.is_authenticated():
    # Do something for authenticated users.
else:
    # Do something for anonymous users.

Using Users

使用User对象

Once you have a User often from request.user , but possibly through one of the other methods discussed shortlyyou have a number of fields and methods available on that object. AnonymousUser objects emulate some of this interface, but not all of it, so you should always check user.is_authenticated() before assuming youre dealing with a bona fide user object. Tables 12-3 and 12-4 list the fields and methods, respectively, on User objects.

User 实例一般从 request.user ，或是其他下��将�讨论到的方法�得，它有很多属性和方法。 AnonymousUser 对象模拟了 部分 的接�，但�是全部，在把它当�真正的user对象 使用�，你得检查一下 user.is_authenticated()

Finally, User objects have two many-to-many fields: groups and permissions . User objects can access their related objects in the same way as any other many-to-many field:

最�， User 对象有两个多对多的属性： groups 和 permissions 。 User 对象�以 象使用其他多对多属性的方法一样使用它们。

# Set a user's groups:
myuser.groups = group_list

# Add a user to some groups:
myuser.groups.add(group1, group2,...)

# Remove a user from some groups:
myuser.groups.remove(group1, group2,...)

# Remove a user from all groups:
myuser.groups.clear()

# Permissions work the same way
myuser.permissions = permission_list
myuser.permissions.add(permission1, permission2, ...)
myuser.permissions.remove(permission1, permission2, ...)
myuser.permissions.clear()

Logging In and Out

登录和退出

Django provides built-in view functions for handling logging in and out (and a few other nifty tricks), but before we get to those, lets take a look at how to log users in and out by hand. Django provides two functions to perform these actions in django.contrib.auth : authenticate() and login() .

Django �供内置的视图(view)函数用于处�登录和退出 (以�其他奇技淫巧)，但在开始�，我们�看看如何手工登录和退出，Django 在 django.contrib.auth 中�供了两个函数�处�这些事情—— authenticate() 和 login() 。

To authenticate a given username and password, use authenticate() . It takes two keyword arguments, username and password , and it returns a User object if the password is valid for the given username. If the password is invalid, authenticate() returns None :

认�给出的用户�和密�，使用 authenticate() 函数。它接�两个�数，用户� username 和 密� password ，并在密�对用给出的用户�是�法的情况下返回一个 User 对象。当给出的密���法的时候 authenticate() 函数返回 None ：

>>> from django.contrib import auth
>>> user = auth.authenticate(username='john', password='secret')
>>> if user is not None:
...     print "Correct!"
... else:
...     print "Oops, that's wrong!"

authenticate() only verifies a users credentials. To log in a user, use login() . It takes an HttpRequest object and a User object and saves the users ID in the session, using Djangos session framework.

authenticate() �是验�一个用户的�书而已。而�登录一个用户，使用 login() 。该函数接�一个 HttpRequest 对象和一个 User 对象作为�数并使用Django的会�（ session ）框架把用户的ID�存在该会�中。

This example shows how you might use both authenticate() and login() within a view function:

下�的例�演示了如何在一个视图中�时使用 authenticate() 和 login() 函数：

from django.contrib import auth

def login(request):
    username = request.POST['username']
    password = request.POST['password']
    user = auth.authenticate(username=username, password=password)
    if user is not None and user.is_active:
        # Correct password, and the user is marked "active"
        auth.login(request, user)
        # Redirect to a success page.
        return HttpResponseRedirect("/account/loggedin/")
    else:
        # Show an error page
        return HttpResponseRedirect("/account/invalid/")

To log out a user, use django.contrib.auth.logout() within your view. It takes an HttpRequest object and has no return value:

注销一个用户，在你的视图中使用 django.contrib.auth.logout() 。该函数接�一个 HttpRequest 对象作为�数，没有返回值。

from django.contrib import auth

def logout(request):
    auth.logout(request)
    # Redirect to a success page.
    return HttpResponseRedirect("/account/loggedout/")

Note that logout() doesnt throw any errors if the user wasnt logged in.

注�，�使用户没有登录， logout() 也�会抛出任何异常。

In practice, you usually will not need to write your own login/logout functions; the authentication system comes with a set of views for generically handling logging in and out.

在实际中，你一般�需�自己写登录/登出的函数；认�系统�供了一系例视图用�处�登录和登出。

The first step in using the authentication views is to wire them up in your URLconf. Youll need to add this snippet:

使用认�视图的第一步是把它们写在你的URLconf中。 你需�这样写：

from django.contrib.auth.views import login, logout

urlpatterns = patterns('',
    # existing patterns here...
    (r'^accounts/login/$',  login),
    (r'^accounts/logout/$', logout),
)

/accounts/login/ and /accounts/logout/ are the default URLs that Django uses for these views.

/accounts/login/ 和 /accounts/logout/ 是Django�供的视图的默认URL。

By default, the login view renders a template at registration/login.html (you can change this template name by passing an extra view argument ,``template_name``). This form needs to contain a username and a password field. A simple template might look like this:

缺�情况下， login 视图渲染 registragiton/login.html 模�(�以通过视图的�外�数 template_name 修改这个模��称)。这个表�必须包� username 和 password 域。如下示例：

{% extends "base.html" %}

{% block content %}

  {% if form.errors %}
    <p class="error">Sorry, that's not a valid username or password</p>
  {% endif %}

  <form action='.' method='post'>
    <label for="username">User name:</label>
    <input type="text" name="username" value="" id="username">
    <label for="password">Password:</label>
    <input type="password" name="password" value="" id="password">

    <input type="submit" value="login" />
    <input type="hidden" name="next" value="{{ next|escape }}" />
  <form action='.' method='post'>

{% endblock %}

If the user successfully logs in, he or she will be redirected to /accounts/profile/ by default. You can override this by providing a hidden field called next with the URL to redirect to after logging in. You can also pass this value as a GET parameter to the login view and it will be automatically added to the context as a variable called next that you can insert into that hidden field.

如果用户登录�功，缺�会�定�到 /accounts/profile 。表�中有一个hidden字段� next ，�以用在登录�指定url。也�以把这个值（指定的url）作为 GET �数传递给login视图，这个�数会�为Context中�为 next 的��，你�以把这个��设置给表�中对应的��字段。

The logout view works a little differently. By default it renders a template at registration/logged_out.html (which usually contains a Youve successfully logged out message). However, you can call the view with an extra argument, next_page , which will instruct the view to redirect after a logout.

logout视图有一些��。缺�的它渲染 registration/logged_out.html 模�（这个视图一般包�你已��功退出的信�）。视图中还�以包�一个�数 next_page 用于退出��定�。

Limiting Access to Logged-in Users

�制已登录用户的访问

Of course, the reason were going through all this trouble is so we can limit access to parts of our site.

有很多原因需�控制用户访问站点的�部分。

The simple, raw way to limit access to pages is to check request.user.is_authenticated() and redirect to a login page:

一个简�原始的�制方法是检查 request.user.is_authenticated() ,然��定�到登陆页�：

from django.http import HttpResponseRedirect

def my_view(request):
    if not request.user.is_authenticated():
        return HttpResponseRedirect('/login/?next=%s' % request.path)
    # ...

or perhaps display an error message:

或者显示一个出错信�：

def my_view(request):
    if not request.user.is_authenticated():
        return render_to_response('myapp/login_error.html')
    # ...

As a shortcut, you can use the convenient login_required decorator:

作为一个快�方�, 你�以使用便�的 login_required 修饰符:

from django.contrib.auth.decorators import login_required

@login_required
def my_view(request):
    # ...

login_required does the following:

login_required �下�的事情:

• If the user isnt logged in, redirect to /accounts/login/ , passing the current absolute URL in the query string as next , for example: /accounts/login/?next=/polls/3/ .

• 如果用户没有登录, é‡�定å�‘到 /accounts/login/ , 把当å‰�ç»�对URL作为 next 在查询字符串中传递过去, 例如: /accounts/login/?next=/polls/3/ .

• If the user is logged in, execute the view normally. The view code can then assume that the user is logged in.

• 如果用户已ç»�登录, 正常地执行视图函数. 视图代ç �å°±å�¯ä»¥å�‡å®šç”¨æˆ·å·²ç»�登录了.

Limiting Access to Users Who Pass a Test

对通过测试的用户�制访问

Limiting access based on certain permissions or some other test, or providing a different location for the login view works essentially the same way.

�制访问�以基于����，�些检查或者为login视图�供��的�置，这些实现方�大致相�

The raw 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 permission polls.can_vote (more about how permissions works follows):

一般的方法是直接在视图的 request.user 上�行检查。例如，下�视图检查用户登陆并是�有 polls.can_vote 的��：

def vote(request):
    if request.user.is_authenticated() and request.user.has_perm('polls.can_vote')):
        # vote here
    else:
        return HttpResponse("You can't vote in this poll.")

Again, Django provides a shortcut called user_passes_test . It takes arguments and generates a specialized decorator for your particular situation:

并且Django有一个称为 user_passes_test 的简�方�。它根�情况使用�数并且产生特殊装饰符。

def user_can_vote(user):
    return user.is_authenticated() and user.has_perm("polls.can_vote")

@user_passes_text(user_can_vote, login_url="/login/")
def vote(request):
    # Code here can assume a logged-in user with the correct permission.
    ...

user_passes_test takes one required argument: a callable that takes a User object and returns True if the user is allowed to view the page. Note that user_passes_test does not automatically check that the User is authenticated; you should do that yourself.

user_passes_test 使用一个必需的�数：一个�调用的方法，当存在 User 对象并当此用户�许查看该页�时返回 True 。 注� user_passes_test �会自动检查 User 是�认�，你应该自己�这件事。

In this example were also showing the second optional argument, login_url , which lets you specify the URL for your login page (/accounts/login/ by default).

例�中我们也展示了第二个�选的�数 login_url ，它让你指定你的登录页�的URL（默认为 /accounts/login/ ）。

Since its a relatively common task to check whether a user has a particular permission, Django provides a shortcut for that case: the permission_required() decorator. Using this decorator, the earlier example can be written as follows:

既然检查用户是�有一个特殊��是相对常�的任务，Django为这�情形�供了一个�径： permission_required() 装饰器 使用这个装饰器，��的例��以这样写:

from django.contrib.auth.decorators import permission_required

@permission_required('polls.can_vote', login_url="/login/")
def vote(request):
    # ...

Note that permission_required() also takes an optional login_url parameter, which also defaults to '/accounts/login/' .

注�, permission_required() 也有一个�选的 login_url �数, 这个�数默认为 '/accounts/login/' 。

Limiting Access to Generic Views

�制通用视图的访问

One of the most frequently asked questions on the Django users list deals with limiting access to a generic view. To pull this off, youll need to write a thin wrapper around the view and point your URLconf to your wrapper instead of the generic view itself:

在Django用户邮件列表中问到最多的问题是关于对通用视图的�制性访问。为实现这个功能，你需�自己包装视图，并且在URLconf中，将你自己的版本替�通用视图：

from dango.contrib.auth.decorators import login_required
from django.views.generic.date_based import object_detail

@login_required
def limited_object_detail(*args, **kwargs):
    return object_detail(*args, **kwargs)

You can, of course, replace login_required with any of the other limiting decorators.

当然, 你�以用任何其他�定修饰符�替� login_required 。

Managing Users, Permissions, and Groups

管� Users, Permissions 和 Groups

The easiest way by far to manage the auth system is through the admin interface. Chapter 6 discusses how to use Djangos admin interface to edit users and control their permissions and access, and most of the time youll just use that interface.

管�认�系统最简�的方法是通过管�界�。 第六章讨论了怎样使用Django的管�界��编辑用户和控制他们的��和�访问性，并且大多数时间你都会�使用这个界�。

However, there are low-level APIs you can delve into when you need absolute control, and we discuss these in the sections that follow.

然而，当你需��对的控制�的时候，有一些低层 API 需�深入专研，我们将在下�的章节中讨论它们。

>>> from django.contrib.auth.models import User
>>> user = User.objects.create_user(username='john',
...                                 email='jlennon@beatles.com',
...                                 password='glass onion')

>>> user.is_staff = True
>>> user.save()

>>> user = User.objects.get(username='john')
>>> user.set_password('goo goo goo joob')
>>> user.save()

hashtype$salt$hash

sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4

from django import oldforms as forms
from django.http import HttpResponseRedirect
from django.shortcuts import render_to_response
from django.contrib.auth.forms import UserCreationForm

def register(request):
    form = UserCreationForm()

    if request.method == 'POST':
        data = request.POST.copy()
        errors = form.get_validation_errors(data)
        if not errors:
            new_user = form.save(data)
            return HttpResponseRedirect("/books/")
    else:
        data, errors = {}, {}

    return render_to_response("registration/register.html", {
        'form' : forms.FormWrapper(form, data, errors)
    })

{% extends "base.html" %}

{% block title %}Create an account{% endblock %}

{% block content %}
  <h1>Create an account</h1>
  <form action="." method="post">
    {% if form.error_dict %}
      <p class="error">Please correct the errors below.</p>
    {% endif %}

    {% if form.username.errors %}
      {{ form.username.html_error_list }}
    {% endif %}
    <label for="id_username">Username:</label> {{ form.username }}

    {% if form.password1.errors %}
      {{ form.password1.html_error_list }}
    {% endif %}
    <label for="id_password1">Password: {{ form.password1 }}

    {% if form.password2.errors %}
      {{ form.password2.html_error_list }}
    {% endif %}
    <label for="id_password2">Password (again): {{ form.password2 }}

    <input type="submit" value="Create the account" />
  </label>
{% endblock %}

Using Authentication Data in Templates

在模�中使用认�数�

The current logged-in user and his or her permissions are made available in the template context when you use RequestContext (see Chapter 10).

当�登入的用户以�他（她）的���以通过 RequestContext 在模�的context中使用（详�第10章）。

Note

备注

Technically, these variables are only made available in the template context if you use RequestContext and your TEMPLATE_CONTEXT_PROCESSORS setting contains "django.core.context_processors.auth" , which is the default. Again, see Chapter 10 for more information.

从技术上�说，�有当你使用了 RequestContext 并且 TEMPLATE_CONTEXT_PROCESSORS 设置包�了 "django.core.context_processors.auth" （默认情况就是如此）时，这些���能在模�context中使用。更详细的内容，也请�考第10章。

When using RequestContext , the current user (either a User instance or an AnonymousUser instance) is stored in the template variable {{ user }} :

当使用 RequestContext 时, 当�用户 (是一个 User 实例或一个 AnonymousUser 实例) 存储在模��� {{ user }} 中:

{% if user.is_authenticated %}
  <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
{% else %}
  <p>Welcome, new user. Please log in.</p>
{% endif %}

This users permissions are stored in the template variable {{ perms }} . This is a template-friendly proxy to a couple of permission methods described shortly.

这些用户的��信�存储在 {{ perms }} 模���中。这是一个在模�中使用很方便的代�，其中包�一些��相关函数的简写。

There are two ways you can use this perms object. You can use something like {{ perms.polls }} to check if the user has any permissions for some given application, or you can use something like {{ perms.polls.can_vote }} to check if the user has a specific permission.

你有两�方��使用 perms 对象。你�以使用类似于 {{ perms.polls }} 的形��检查，对于�个特定的应用，一个用户是�具有 任� ��；你也�以使用 {{ perms.polls.can_vote }} 这样的形�，�检查一个用户是�拥有特定的��。

Thus, you can check permissions in template {% if %} statements:

这样你就�以在模�中的 {% if %} 语�中检查��:

{% if perms.polls %}
  <p>You have permission to do something in the polls app.</p>
  {% if perms.polls.can_vote %}
    <p>You can vote!</p>
  {% endif %}
{% else %}
  <p>You don't have permission to do anything in the polls app.</p>
{% endif %}

Permissions

��

Permissions are a simple way to mark users and groups as being able to perform some action. They are usually used by the Django admin site, but you can easily use them in your own code.

���以很方便地标识用户和用户组�以执行的�作。它们被Django的admin管�站点所使用，你也�以在你自己的代�中使用它们。

The Django admin site uses permissions as follows:

Django的admin站点如下使用��：

• Access to view the add form, and add an object is limited to users with the add permission for that type of object.

• å�ªæœ‰è®¾ç½®äº† add æ�ƒé™�的用户æ‰�能使用添加表å�•ï¼Œæ·»åŠ å¯¹è±¡çš„视图。

• 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.

• å�ªæœ‰è®¾ç½®äº† change æ�ƒé™�的用户æ‰�能使用å�˜æ›´åˆ—表，å�˜æ›´è¡¨æ ¼ï¼Œå�˜æ›´å¯¹è±¡çš„视图。

• Access to delete an object is limited to users with the delete permission for that type of object.

• å�ªæœ‰è®¾ç½®äº† delete æ�ƒé™�的用户æ‰�能删除一个对象。

Permissions are set globally per type of object, not per specific object instance. For example, its possible to say Mary may change news stories, but its 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, publication date, or ID.

��是根��一个类型的对象而设置的，并�具体到对象的特定实例。例如，我们�以�许Mary改�新故事，但是目�还��许设置Mary�能改�自己创建的新故事，或者根�给定的状�，出版日期或者ID��选择��。

These three basic permissionsadd, change, and deleteare automatically created for each Django model that has a class Admin . Behind the scenes, these permissions are added to the auth_permission database table when you run manage.py syncdb .

这三个基本��：添加，�更和删除，会被自动添加到所有的Django模型中，��该模型包� class Admin 。当你执行 manage.py syncdb 的时候，这些就被自动添加到 auth_permission 数�表中。

These permissions will be of the form "<app>.<action>_<object_name>" . That is, if you have a polls application with a Choice model, youll get permissions named "polls.add_choice" , "polls.change_choice" , and "polls.delete_choice" .

��以 "<app>.<action>_<object_name>" 的形�出现。如果你有一个 polls 的应用，包�一个 Choice 模型，你就有以下三个��，分别�� "polls.add_choice" ， "polls.change_choice" ，和 "polls.delete_choice" 。

Note that if your model doesnt have class Admin set when you run syncdb , the permissions wont be created. If you initialize your database and add class Admin to models after the fact, youll need to run syncdb again to create any missing permissions for your installed applications.

注�，如果当你�行 syncdb 时，模型中没有包� class Admin ，该模型对应的��就�会被创建。如果你在�始化数�库以�，�在自己的模型中加入了 class Admin ，你就需��新�行 syncdb �为应用加入��。

You can also create custom permissions for a given model object using the permissions attribute on Meta . This example model creates three custom permissions:

你也�以通过设置 Meta 中的 permissions 属性，�为给定的模型定制��。下�的例�创建了三个自定义的��：

class USCitizen(models.Model):
    # ...
    class Meta:
        permissions = (
            # Permission identifier     human-readable permission name
            ("can_drive",               "Can drive"),
            ("can_vote",                "Can vote in elections"),
            ("can_drink",               "Can drink alcohol"),
        )

This only creates those extra permissions when you run syncdb ; its up to you to check for these permissions in your views.

当你�行 syncdb 时，�外的���会被加入；你需�自己在视图中添加��相关的代�。

Just like users, permissions are implemented in a Django model that lives in django.contrib.auth.models . This means that you can use Djangos database API to interact directly with permissions if you like.

就跟用户一样，��也就是Django模型中的 django.contrib.auth.models 。因此如果你愿�，你也�以通过Django的数�库API直接�作��。

Groups

组

Groups are a generic way of categorizing users so you can 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.

在一个组中的用户自动获得了赋予该组的��。例如， Site editors 组拥有 can_edit_home_page ��，任何在该组中的用户都拥有这个��。

Groups are also a convenient way to categorize users to give them some label, or extended functionality. For example, you could create a group 'Special users' , and you could write code that could, say, give those users access to a members-only portion of your site, or send them members-only email messages.

组也�以通过给定一些用户特殊的标记，�扩展功能。例如，你创建了一个 'Special users' 组，并且�许组中的用户访问站点的一些VIP部分，或者��VIP的邮件消�。

Like users, the easiest way to manage groups is through the admin interface. However, groups are also just Django models that live in django.contrib.auth.models , so once again you can always use Djangos database APIs to deal with groups at a low level.

和用户管�一样，admin接�是管�组的最简�的方法。然而，组也就是Django模型 django.contrib.auth.models ，因此你�以使用Django的数�库API，在底层访问这些组。

Messages

消�

The message system is a lightweight way to queue messages for given users. A message is associated with a User . Theres no concept of expiration or timestamps.

消�系统会为给定的用户接收消�。�个消�都和一个 User 相关�。其中没有超时或者时间戳的概念。

Messages are used by the Django admin interface after successful actions. For example, when you create an object, youll notice a The object was created successfully message at the top of the admin page.

在�个�功的�作以�，Django的admin管�接�就会使用消�机制。例如，当你创建了一个对象，你会在admin页�的顶上看到 The object was created successfully 的消�。

You can use the same API to queue and display messages in your own application. The API is simple:

你也�以使用相�的API在你自己的应用中排队接收和显示消�。API�常地简�：

• To create a new message, use user.message_set.create(message='message_text') .

• è¦�创建一æ�¡æ–°çš„消æ�¯ï¼Œä½¿ç”¨ 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 users queue (if any) and deletes the messages from the queue.

• è¦�获得/删除消æ�¯ï¼Œä½¿ç”¨ user.get_and_delete_messages() ，这会返回一个 Message 对象的列表，并且从队列中删除返回的项。

In this example view, the system saves a message for the user after creating a playlist:

在例�视图中，系统在创建了播放�（playlist）以�，为用户�存了一�消�。

def create_playlist(request, songs):
    # Create the playlist with the given songs.
    # ...
    request.user.message_set.create(
        message="Your playlist was added successfully."
    )
    return render_to_response("playlists/create.html",
        context_instance=RequestContext(request))

When you use RequestContext , the current logged-in user and his or her messages are made available in the template context as the template variable {{ messages }} . Heres an example of template code that displays messages:

当使用 RequestContext ，当�登录的用户以�他（她）的消�，就会以模��� {{ messages }} 出现在模�的context中。下�是显示消�的一个例�模�代�：

{% if messages %}
<ul>
    {% for message in messages %}
    <li>{{ message }}</li>
    {% endfor %}
</ul>
{% endif %}

Note that RequestContext calls get_and_delete_messages behind the scenes, so any messages will be deleted even if you dont display them.

需�注�的是 RequestContext 会在��调用 get_and_delete_messages ，因此�使你没有显示它们，它们也会被删除掉。

Finally, note that this messages framework only works with users in the user database. To send messages to anonymous users, use the session framework directly.

最�注�，这个消�框架�能�务于在用户数�库中存在的用户。如果��匿�用户��消�，请直接使用会�框架。

Profiles

档案

The final piece of the puzzle is the profile system. To understand what profiles are all about, lets first look at the problem.

最�一个难题是档案系统.为了�解什么是档案,让我们先看看问题.

In a nutshell, many sites need to store more user information than is available on the standard User object. To compound the problem, most sites will have different extra fields. Thus, Django provides a lightweight way of defining a profile object thats linked to a given user. This profile object can differ from project to project, and it can even handle different profiles for different sites served from the same database.

简��说，许多网站需�存储比标准 User 对象更多的用户信�。为了解决这个问题，大多数网站都会有��的�外字段。所以，Django�供一个轻�级的方�定义档案对象链接到指定的用户。这个档案对象在�个项目中�以是��的，甚至�以为�一数�库�务的��的站点处���的档案。

The first step in creating a profile is to define a model that holds the profile information. The only requirement Django places on this model is that it have a unique ForeignKey to the User model; this field must be named user . Other that that, you can use any other fields you like. Heres a strictly arbitrary profile model:

创建档案的第一步是定义一个模型（model）�存储档案信�。Django对这个模型所�的唯一的�制是，必须�包�唯一的一个对 User 模型的 ForeignKey ，而且这个字段必须��� user 。其他的字段�以由你自己掌控。下�是一个档案模型的例�：

from django.db import models
from django.contrib.auth.models import User

class MySiteProfile(models.Model):
    # This is the only required field
    user = models.ForeignKey(User, unique=True)

    # The rest is completely up to you...
    favorite_band = models.CharField(maxlength=100, blank=True)
    favorite_cheese = models.CharField(maxlength=100, blank=True)
    lucky_number = models.IntegerField()

Next, youll need to tell Django where to look for this profile object. You do that by setting the AUTH_PROFILE_MODULE setting to the identifier for your model. So, if your model lives in an application called myapp , youd put this in your settings file:

下一步，你需�告诉Django去哪里查找档案对象。你�以通过设置模型中的 AUTH_PROFILE_MODULE ��达到这个目的。因此，如果你的模型包�在 myapp 这个应用中，你就需�如下编写你的设置文件：

AUTH_PROFILE_MODULE = "myapp.mysiteprofile"

Once thats done, you can access a users profile by calling user.get_profile() . This function could raise a SiteProfileNotAvailable exception if AUTH_PROFILE_MODULE isnt defined, or it could raise a DoesNotExist exception if the user doesnt have a profile already (youll usually catch that exception and create a new profile at that time).

一旦完�，你就�以通过调用 user.get_profile() 函数�获得用户档案。如果 AUTH_PROFILE_MODULE ��没有设置，这个函数�能会抛出 SiteProfileNotAvailable 异常；如果这个用户�存在档案，也�能会抛出 DoesNotExist 异常（通常情况下，你会�获这个异常并在当时创建一个新的档案）。