============================
Request对象和response 对象
============================

:作者: Django 团队
:译者: weizhong2004@gmail.com
:翻译开始日期: 2006-03-30
:翻译结束日期: 2006-03-30
:最后修订日期: 2006-05-11
:原文版本: 2786

概述
==============

Django 使用 request 和 response 对象表示系统状态数据..

当请求一个页面时,Django创建一个 ``HttpRequest`` 对象.该对象包含 request 的元数据. 然后 Django 调用相应的 view 函数(``HttpRequest`` 对象自动传递给该view函数<作为第一个参数>), 每一个 view 负责返回一个 ``HttpResponse`` 对象.

本文档解释了 ``HttpRequest`` 和 ``HttpResponse`` 对象的 API.

HttpRequest 对象
===================

属性
----------

除了 session 以外的其它属性都应该被看作是只读的.

``path``
    一个字符串表示请求页的路径全名(不包括域名).

    Example: ``"/music/bands/the_beatles/"``

``GET``
    可以认为是一个字典对象,包括所有的 HTTP GET 参数,参见下面的 ``QueryDict`` 文档.

``POST``
    可以认为是一个字典对象,包括所有的 HTTP POST 参数,参见下面的 ``QueryDict`` 文档.
 
    **注意:** ``POST``  *不* 包括文件上载信息, 参阅 ``FILES``.

``REQUEST``
    为了使用方便,该对象也可以认为是一个字典对象,它包括所有 POST 和 GET 数据(先POST,后GET). (灵感来自PHP中的 $_REQUEST 全局变量).

    举例: 如果 ``GET={"name":"john"}``, ``POST={"AGE":"34"}`` 则 ``REQUEST["name"]="john"``, ``REQUEST["age"]="34"``.

    强烈建议你使用 GET 或 POST 而不是 REQUEST,因为前者更清晰.

``COOKIES``
    是一个标准的Python字典,包括所有的cookie. 键和值都是字符串.

``FILES``
    可以看作是一个字典对象,它包含所有的上载文件. FILES中的每个键是 <input type="file" name="" /> 中name 的值,每个值是一个标准的Python字典,该字典有以下三个键:
        * filename -- 上传文件的文件名,一个python 字符串
        * content-type 上传文件的 content type
        * content 上传文件的原始内容

        注意 FILES 只有在请求方式为 POST 并且表单包括 enctype="multipart/form-data" 属性时才会有数据,否则 FILES 就是一个空的类似字典的对象.

``META``
    META是一个标准的Python字典,包含所有可能的 HTTP 头.
        可用的 header 依赖客户机和服务器,下面是某些可能的值:

        * CONTENT_LENGTH
        * CONTENT_TYPE
        * HTTP_ACCEPT_ENCODING
        * HTTP_ACCEPT_LANGUAGE
        * HTTP_REFERER  引用页,如果有的话
        * HTTP_USER_AGENT  客户机用户代理字符串
        * QUERY_STRING  查询字符串,单一的未解析的字符串
        * REMOTE_ADDR  客户机IP地址
        * REMOTE_HOST  客户机hostname
        * REQUEST_METHOD  请求方式,比如 GET 或 POST
        * SERVER_NAME  服务器 hostname
        * SERVER_PORT  服务器端口

``user``
    一个 django.contrib.auth.users.User 对象, 表示当前登录用户.如果当前没有用户登录, user 被设置成 `django.contrib.auth.models.AnonymousUser` 的一个实例.你可以用 is_anonymous() 来区分登录用户和未登录用户.就象下面这样::
        if request.user.is_anonymous():
            # Do something for anonymous users.
        else:
            # Do something for logged-in users.

    只有你的 Django 激活了 ``AuthenticationMiddleware`` 之后 ``user`` 对象才可用. 参阅 `Authentication in Web requests`_.
    .. Authentication in Web requests: http://www.djangoproject.com/documentation/authentication/#authentication-in-web-requests

``session``
    一个可读写的,类似字典的对象,表示当前的 session. 当有你的django 安装包括session支持并且被激活,该对象才存在.要了解关于session的更多细节,阅读session文档: http://www.djangoproject.com/documentation/sessions/

``raw_post_data``
    原始 HTTP POST 数据. 该属性仅用于POST数据的高级处理. 更多时候你只需要 POST 对象.

方法
-------

``__getitem__(key)``
    根据给定的键,返回一个 GET/POST 值. 该方法首先检查 POST,然后是 GET. 若给定的键未找到,引发 ``KeyError`` 异常

    这使得你能够使用访问字典的语法来存取 ``HttpRequest`` 实例. 举例来说: 无论 ``request.POST`` 有一个 ``"foo"`` 键还是 ``request.GET`` 有一个 ``"foo"`` 键,``request["foo"]`` 都会返回相应的值.

``has_key()``
    返回 ``True`` 或 ``False`` .

``get_full_path()``
    返回一个路径,包括query字符串.

    Example: ``"/music/bands/the_beatles/?print=true"``

QueryDict 对象
-----------------
在一个 HttpRequest 对象中, GET和POST属性都是 ``django.http.QueryDict`` 的实例. ``QueryDict`` 是一个类似字典的类,被设计成可以处理同一个键有多个值的情况.这是很必要的,因为有些 HTML 表单元素,特别是``<select multiple="multiple">``,使用一个键来传递多个值

``QueryDict`` 实例是不可变对象,除非你创建他们的一个拷贝.这意味着你不能直接改变 ``request.POST`` 和 ``request.GET`` 的值.

``QueryDict`` 实现了所有的标准字典方法,因为它就是 dictionary 的一个子类.下文中对与标准字典不一致的地方做了标注:


    * ``__getitem__(key)`` -- 返加给定键的值. 如果该键有多个值, ``__getitem__`` 返回最后一个值.

    * ``__setitem__(key, value)`` -- 将 key 的值设置为 ``[value]`` (一个Python 列表,只有一个元素 value).注意,这个方法象其它字典方法一个拥有副作用,只能被一个可变的 ``QueryDict`` 对象调用.(一个通过`` copy()``创建的副本).

    * ``__contains__(key)`` -- 如果给定键存在,返回 ``True``. 它允许你这么干: ``if "foo" in request.GET``.

    * ``get(key, default)`` --类似 ``__getitem__()`` ,如果该键不存在,返回一个默认值.

    * ``has_key(key)``

    * ``setdefault(key, default)`` -- 类似标准字典的 ``setdefault()``,不同之处在于它内部使用的是 ``__setitem__()``.

    * ``update(other_dict)`` -- 类似标准字典的 ``update()``, 唯一的不同是它将 ``other_dict`` 的元素追加到(而不是替换到)当前字典中.
      示例::

          >>> q = QueryDict('a=1')
          >>> q = q.copy() # to make it mutable
          >>> q.update({'a': '2'})
          >>> q.getlist('a')
          ['1', '2']
          >>> q['a'] # returns the last
          ['2']

    * ``items()`` -- 类似标准字典的 ``items()`` 方法, 类似 ``__getitem__()`` 的逻辑,它使用最后一个值. 示例::

           >>> q = QueryDict('a=1&a=2&a=3')
           >>> q.items()
           [('a', '3')]

    * ``values()`` -- 类似标准字典的 ``values()`` 方法,类似 ``__getitem__()`` 的逻辑,它使用最后一个值.示例::

           >>> q = QueryDict('a=1&a=2&a=3')
           >>> q.values()
           ['3']

除了这些之外,``QueryDict`` 还拥有下列方法:

    * ``copy()`` -- 返回当前对象的一个拷贝,它使用标准库中的 深拷贝 方法. 这个拷贝是可变的,也就是说你可以改变这个拷贝的值.

    * ``getlist(key)`` -- 以一个Python列表的形式返回指定键的值.若该键不存在,返回一个空的列表.该列表是以某种方式排序的.

    * ``setlist(key, list_)`` -- 不同于 ``__setitem__()`` ,将给定的键的值设置为一个列表.

    * ``appendlist(key, item)`` -- 将给定键对应的值(别忘了,它是一个列表)追加一个 item.

    * ``setlistdefault(key, default_list)`` -- 就象 ``setdefault`` ,不过它接受一个列表作为值而不是一个单一的值.

    * ``lists()`` -- 就象 ``items()``,不过它包含所有的值(以列表的方式)::

           >>> q = QueryDict('a=1&a=2&a=3')
           >>> q.lists()
           [('a', ['1', '2', '3'])]

    * ``urlencode()`` -- 以一个查询字符串的形式返回一个字符串.
      Example: ``"a=2&b=3&b=5"``.

示例
--------

下面是一个例子演示了 Django 如何对待输入::

    <form action="/foo/bar/" method="post">
    <input type="text" name="your_name" />
    <select multiple="multiple" name="bands">
        <option value="beatles">The Beatles</option>
        <option value="who">The Who</option>
        <option value="zombies">The Zombies</option>
    </select>
    <input type="submit" />
    </form>

若用户输入了 "John Smith" 在 your_name 框并且选择在多选框中同时选中了 The Beatles 和 The Zombies, 然后点击 Submit, Django的request对象将拥有::

    >>> request.GET
    {}
    >>> request.POST
    {'your_name': ['John Smith'], 'bands': ['beatles', 'zombies']}
    >>> request.POST['your_name']
    'John Smith'
    >>> request.POST['bands']
    'zombies'
    >>> request.POST.getlist('bands')
    ['beatles', 'zombies']
    >>> request.POST.get('your_name', 'Adrian')
    'John Smith'
    >>> request.POST.get('nonexistent_field', 'Nowhere Man')
    'Nowhere Man'

实现备注
--------------------

``GET``, ``POST``, ``COOKIES``, ``FILES``, ``META``, ``REQUEST``,``raw_post_data`` 及 ``user`` 属性都是惰性的.也就是说在你要求得到他们的值之前,django并不花费时间计算他们的值.只有你需要时,才实时计算出你要的值给你.简单来说,就象 xrange 函数.

HttpResponse 对象
====================

对应着 ``HttpRequest`` 对象, ``HttpResponse`` 对象也是 Django自动生成的. 该对象包含你的响应. 你写的每一个view都是可响应的并且返回一个 ``HttpResponse`` 对象.

``HttpResponse`` 类定义在 ``django.http`` 中.

用法
-----

传递字符串
~~~~~~~~~~~~

典型的用法就是将页面的内容作为字符串传递给 ``HpptResponse`` 构造函数::

    >>> response = HttpResponse("Here's the text of the Web page.")
    >>> response = HttpResponse("Text only, please.", mimetype="text/plain")

如果你需要随时增加内容,你可以象使用一个文件一样来使用 response 对象::

    >>> response = HttpResponse()
    >>> response.write("<p>Here's the text of the Web page.</p>")
    >>> response.write("<p>Here's another paragraph.</p>")

你可以使用字典语法添加或删除headers::

    >>> response = HttpResponse()
    >>> response['X-DJANGO'] = "It's the best."
    >>> del response['X-PHP']
    >>> response['X-DJANGO']
    "It's the best."

注意:即使该header 不存在, del 也不会引发 ``KeyError`` 异常.

传递迭代器
~~~~~~~~~~~~~~~~~

最后一点,允许将一个迭代器传递给 ``HttpResponse`` 对象. 如果打算使用这一技术, 只需要遵守以下规则:

    * 迭代器必须返回字符串
    * 如果一个 ``HttpResponse`` 实例使用一个迭代器进行了初始化, 该实例就不允许再以类似文件操作的方式来访问.否则就会引发异常.

方法
-------

``__init__(content='', mimetype=DEFAULT_MIME_TYPE)``
    根据你提供的页面内容(一个字符串)和MIME类型，初始化一个 ``HttpResponse`` 对象.默认的MIME类型是 ``'text/html'``.
    ``content`` 可以是一个迭代对象或者是一个字符串. 如果它是一个迭代对象, 它应该返回字符串, 并且这些字符串连接起来能够形成 response 的内容.

``__setitem__(header, value)``
    ``header`` 和 ``value`` 都是字符串，将给定的header设置为给定的 ``value``.

``__delitem__(header)``
    删除给定名字的header 如果header不存在，则静默．header是大小写敏感的．.

``__getitem__(header)``
    返回给定header的值，大小写敏感.

``has_header(header)``
    检查给定header是否存在(大小写敏感),返回 ``True ``或``False``.

``set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=None)``
    设置一个cookie 参数与Python标准库中的 cookie Morsel 对象一样
        *  max_age是一个秒数, None表示只要浏览器不关就一直存在.
        *  expires 是一个这种格式的字符串: "Wdy, DD-Mon-YY HH:MM:SS GMT".
        *  如果你要设置一个跨域名的cookie,使用 domain . 举例来说: domain=".lawrence.com" 将设置一个cookie 可以被 www.lawrence.com blogs.lawrence.com 和calendars.lawrence.com 等类似的域名读取. 否则,一个cookie 只能被当前域名读取.

    .. _`cookie Morsel`: http://www.python.org/doc/current/lib/morsel-objects.html

``delete_cookie(key)``
    删除给定key的cookie,若该key不存在,静默.

``content``
    以一个Python字符串的形式返回页面内容,如果需要,将其改造为unicode对象返回.注意它是一个 property ,不是一个方法. 使用 ``r.content`` 而不是 ``r.content()``.

``write(content)``, ``flush()`` and ``tell()``
    这几个方法将HttpResponse实例改造成为一个类似文件的对象.

HttpResponse 子类
-----------------------

Django包括一系列 ``HttpResponse`` 子类处理不同的HTTP请求.象 ``HttpResponse`` 一样,这些子类都在 ``django.http`` 中定义.

``HttpResponseRedirect``
    该类的构造函数只接受一个参数--要重定向的路径. 该路径可以是一个 URL 全称(如 ``'http://www.google.com'`` ) 也可以是一个不包括域名的绝对 URL (如 ``'/search/'`` ). 注意它返回一个 HTTP 状态码 302.

``HttpResponsePermanentRedirect``
    类似 ``HttpResponseRedirect``, 不过它返回一个持久化重定向(HTTP状态码301),而不是一个 found 重定向(状态码302).

``HttpResponseNotModified``
    该类的构造函数不接受任何参数,表示一个页面从用户最后一次请示以来未做任何改动.

``HttpResponseNotFound``
    类似 ``HttpResponse`` 不过使用 404 状态码.

``HttpResponseForbidden``
    类似 ``HttpResponse`` 不过使用 403 状态码.

``HttpResponseGone``
    类似 ``HttpResponse`` 不过使用 410 状态码.

``HttpResponseServerError``
    类似 ``HttpResponse`` 不过使用 500 状态码.