==============================================
リクエストオブジェクトとレスポンスオブジェクト
==============================================

:revision-up-to: 17812 (1.4)

.. module:: django.http
   :synopsis: HTTP のリクエストとレスポンスを扱うためのクラスです。

簡単な概要
==========

Django は、システム全体にわたって、リクエストとレスポンスオブジェクトを使っ
て処理状態を受け渡します。

あるページへのリクエストを受け取ると、Django は
:class:`~django.http.HttpRequest` オブジェクトを生成します。このオブジェク
トにはリクエストのメタデータが入っています。次に Django は適切なビューをロー
ドして、 :class:`~django.http.HttpRequest` をビュー関数の最初の引数に渡しま
す。各ビューは :class:`~django.http.HttpResponse` オブジェクトを返さねばな
りません。

このドキュメントでは  :class:`~django.http.HttpRequest` および
:class:`~django.http.HttpResponse` オブジェクトの API について説明します。

HttpRequest オブジェクト
========================

.. class:: HttpRequest

.. _httprequest-attributes:

属性
----

``session`` 以外の属性は全て読み出し専用です。

.. attribute:: HttpRequest.body

    .. versionchanged:: 1.4

    .. Before Django 1.4, ``HttpRequest.body`` was named
        ``HttpRequest.raw_post_data``.

    Django 1.4 以前では、``HttpRequest.body`` は
    ``HttpRequest.raw_post_data`` でした．

    .. The raw HTTP request body as a byte string. This is useful for processing
        data in different ways than conventional HTML forms: binary images,
        XML payload etc. For processing conventional form data, use ``HttpRequest.POST``.

    生の HTTP リクエストのバイト文字列です。これは従来の HTML フォームと
    異なる、バイナリ画像や XML ペイロードのデータを処理するのに便利です。
    従来のフォームのデータを処理するためには ``HttpRequest.POST`` を
    使って下さい。

    .. versionadded:: 1.3

    .. You can also read from an HttpRequest using a file-like interface. See
        :meth:`HttpRequest.read()`.

    HttpRequest をファイルのようなインターフェースで読むことも出来ます。
    後述の :meth:`HttpRequest.read()` も参照して下さい。

.. attribute:: HttpRequest.path

    リクエストしているページのフルパスを表す、ドメインを含まない文字列です。

    例: ``"/music/bands/the_beatles/"``

.. attribute:: HttpRequest.path_info

    .. Under some Web server configurations, the portion of the URL after the host
        name is split up into a script prefix portion and a path info portion
        (this happens, for example, when using the ``django.root`` option
        with the :doc:`modpython handler from Apache </howto/deployment/modpython>`).
        The ``path_info`` attribute always contains the path info portion of the
        path, no matter what Web server is being used. Using this instead of
        attr:`~HttpRequest.path` can make your code much easier to move between test
        and deployment servers.

    いくつかの Web サーバーの設定において、ホストネーム以降の URL の一部が
    スクリプトプレフィックスの部分と PATH_INFO の部分に分割されます。
    ( 例えば、これが発生するのは、 ``django.root`` オプションを
    :doc:`Apache と mod_python で Django を動かす </howto/deployment/modpython>`
    で使っている場合 ) ``path_info`` 属性には、どの Web サーバーが使われている
    かに関わらず、常にパスの PATH_INFO の部分が入ります。
    :attr:`~HttpRequest.path` の代わりに使うことで、テストサーバーから本番
    サーバーへの移行が簡単なコードにすることが出来ます。

    ..  For example, if the ``WSGIScriptAlias`` for your application is set to
        ``"/minfo"``, then ``path`` might be ``"/minfo/music/bands/the_beatles/"``
        and ``path_info`` would be ``"/music/bands/the_beatles/"``.

    例えば、もしアプリケーションの ``WSGIScriptAlias`` が ``"/minfo"`` に
    設定されていた場合、 ``path`` は
    ``"/minfo/music/bands/the_beatles/"`` に ``path_info`` は
    ``"/music/bands/the_beatles/"`` になるでしょう。

.. attribute:: HttpRequest.method

    リクエストに使われた HTTP メソッドを表す文字列です。必ず大文字になります。
    例::

        if request.method == 'GET':
            do_something()
        elif request.method == 'POST':
            do_something_else()

.. attribute:: HttpRequest.encoding

    提出されたフォームデータのデコードに使われる、現在のエンコーディングを
    表す文字列です (``None`` の場合もありますが、この場合は
    :setting:`DEFAULT_CHARSET` を使います)。この属性を変更すれば、フォーム
    データにアクセスする際に使われるエンコーディングを指定できます。一度エ
    ンコーディングを変更すると、変更後に (``GET`` や ``POST`` の) 属性への
    アクセスはすべて新しい ``encoding`` の値に従って行われます。フォームデー
    タが :setting:`DEFAULT_CHARSET` 以外の特定のエンコーディングと分かって
    いる場合に便利です。

.. attribute:: HttpRequest.GET

    全ての HTTP GET パラメタが入った辞書ライクなオブジェクトです。後述の
    :class:`QueryDict` も参照してください。

.. attribute:: HttpRequest.POST

    全ての HTTP POST パラメタが入った辞書ライクなオブジェクトです。後述の
    :class:`QueryDict` も参照してください。

    フォームを POST HTTP メソッドで要求し、その際に何らフォームデータを伴わ
    ないような場合には、リクエストが POST で送られていながらも ``POST`` 辞
    書が空になることがあります。従って、リクエストが POST メソッドであるか
    どうかを調べるために ``if request.POST`` を使うべきではありません。代わ
    りに ``if request.method == "POST"`` を使ってください (上参照)。

    ``POST`` にはファイルアップロードに関する情報は *入っていない* ので注意
    してください。 ``FILES`` を参照してください。

.. attribute:: HttpRequest.REQUEST

    便宜的な辞書オブジェクトで、 ``POST`` パラメタをまず検索してから、次に
    ``GET`` パラメタを検索します。 PHP の ``$_REQUEST`` にインスパイアされ
    た機能です。

    例えば、 ``GET = {"name": "john"}`` で ``POST = {"age": '34'}`` の場合、
    ``REQUEST["name"]`` は ``"john"`` になり、 ``REQUEST["age"]`` は
    ``"34"`` になります。

    通常は ``GET`` および ``POST`` を使うように強く勧めます。その方が明示的
    だからです。

.. attribute:: HttpRequest.COOKIES

    全てのクッキーが入った標準の Python 辞書オブジェクトです。キーと値は文
    字列です。

.. attribute:: HttpRequest.FILES

    アップロードされた全てのファイルが入っている辞書ライクオブジェクトです。
    ``FILES`` の各キーは ``<input type="file" name="" />`` の ``name`` 
    に対応しています。 ``FILES`` の各値は後述の :class:`UploadedFile` オブジ
    ェクトです．

    詳しくは :doc:`/topics/files` を参照してください。

    ``FILES`` にデータが入るのは、リクエストが ``POST`` であり、かつリクエ
    ストをポストした ``<form>`` に ``enctype="multipart/form-data`` がある
    場合だけです。それ以外の場合、 ``FILES`` は空の辞書ライクオブジェクトに
    なります。

.. attribute:: HttpRequest.META

    標準の Python 辞書オブジェクトで、利用できる全ての HTTP ヘッダが入って
    います。利用可能なヘッダはクライアントとサーバごとに違いますが、例えば
    以下のようなヘッダを利用できます:

    .. * ``CONTENT_LENGTH`` -- the length of the request body (as a string).
        * ``CONTENT_TYPE`` -- the MIME type of the request body.
        * ``HTTP_ACCEPT_ENCODING`` -- Acceptable encodings for the response.
        * ``HTTP_ACCEPT_LANGUAGE`` -- Acceptable languages for the response.
        * ``HTTP_HOST`` -- The HTTP Host header sent by the client.
        * ``HTTP_REFERER`` -- The referring page, if any.
        * ``HTTP_USER_AGENT`` -- The client's user-agent string.
        * ``QUERY_STRING`` -- The query string, as a single (unparsed) string.
        * ``REMOTE_ADDR`` -- The IP address of the client.
        * ``REMOTE_HOST`` -- The hostname of the client.
        * ``REMOTE_USER`` -- The user authenticated by the Web server, if any.
        * ``REQUEST_METHOD`` -- A string such as ``"GET"`` or ``"POST"``.
        * ``SERVER_NAME`` -- The hostname of the server.
        * ``SERVER_PORT`` -- The port of the server (as a string).

    * ``CONTENT_LENGTH`` -- リクエストのボディの長さ（文字列）です。
    * ``CONTENT_TYPE`` -- リクエストのボディの MIME タイプです。
    * ``HTTP_ACCEPT_ENCODING`` -- レスポンスとして利用可能な文字コードです。
    * ``HTTP_ACCEPT_LANGUAGE`` -- レスポンスとして利用可能な言語です。
    * ``HTTP_HOST`` -- クライアントによって送信された HTTP Host ヘッダです。
    * ``HTTP_REFERER`` -- リクエスト対象のページを参照しているページが
      ある場合、そのページの URL です。
    * ``HTTP_USER_AGENT`` -- クライアントのユーザエージェントの文字列です。
    * ``QUERY_STRING`` -- パース前の単一のクエリ文字列です。
    * ``REMOTE_ADDR`` -- クライアントの IP アドレスです。
    * ``REMOTE_HOST`` -- クライアントのホスト名です。
    * ``REMOTE_USER`` -- Web サーバーによって認証されたユーザがある場合、
      そのユーザです。
    * ``REQUEST_METHOD`` -- ``"GET"`` や ``"POST"`` のような文字列です。
    * ``SERVER_NAME`` -- サーバのホスト名です。
    * ``SERVER_PORT`` -- サーバのポート番号（文字列）です。

    .. With the exception of ``CONTENT_LENGTH`` and ``CONTENT_TYPE``, as given
        above, any HTTP headers in the request are converted to ``META`` keys by
        converting all characters to uppercase, replacing any hyphens with
        underscores and adding an ``HTTP_`` prefix to the name. So, for example, a
        header called ``X-Bender`` would be mapped to the ``META`` key
        ``HTTP_X_BENDER``.

    ``CONTENT_LENGTH`` と ``CONTENT_TYPE`` の例外を含め、上に示されたように、
    リクエストのどの HTTP ヘッダも、すべての文字を大文字に変換し、すべての
    ハイフンをアンダーバーに置き換え、 名前に ``HTTP_`` のプレフィックスを
    付加して ``META`` のキーに変換されます。よって、例えば、 ``X-Bender``
    というヘッダは ``META`` で ``HTTP_X_BENDER`` のキーに割り当てられます。

.. attribute:: HttpRequest.user

    現在ログインしているユーザを表す ``django.models.auth.models.User`` オブ
    ジェクトです。ユーザが現在ログインしていない場合には、 ``user`` は 
    ``django.contrib.auth.models.AnonymousUser`` のインスタンスになります。
    ``is_authenticated()`` を使うと、これら二種類のユーザを区別できます::

        if request.user.is_authenticated():
            # Do something for logged-in users.
        else:
            # Do something for anonymous users.

    ``user`` を利用できるのは、 インストールした Django で
    ``AuthenticationMiddleware`` を有効にした場合だけです。詳しくは
    :doc:`/topics/auth` を参照してください。

.. attribute:: HttpRequest.session

    読み書き可能な辞書ライクオブジェクトで、現在のセッションを表現しています。
    この辞書はインストールされている Django でセッションが有効な場合にのみ
    利用できます。
    詳しくは :doc:`セッションのドキュメント </topics/http/sessions>` を
    参照してください。

.. attribute:: HttpRequest.urlconf

    Django 自体はこの属性を設定しませんが、他のコード（自作のミドルウェアな
    ど）でこの属性を設定した場合、Djangoはその値を :setting:`ROOT_URLCONF`
    の代わりにルート URLconf モジュール名として使います。
    詳しくは 「 :ref:`how-django-processes-a-request` 」を参照してください。

メソッド
--------

.. method:: HttpRequest.get_host()

    .. Returns the originating host of the request using information from the
        ``HTTP_X_FORWARDED_HOST`` (if :setting:`USE_X_FORWARDED_HOST` is enabled)
        and ``HTTP_HOST`` headers, in that order. If they don't provide a value,
        the method uses a combination of ``SERVER_NAME`` and ``SERVER_PORT`` as
        detailed in :pep:`3333`.

    ``HTTP_X_FORWARDED_HOST`` ヘッダ（:setting:`USE_X_FORWARDED_HOST` が
    有効化されている場合）と ``HTTP_HOST`` ヘッダを順に調べて、リクエストの
    送信元を返します。クライアントがそれらの値を提供していない場合は
    :pep:`3333` に従って、``SERVER_NAME`` と ``SERVER_PORT`` の組み合わせを
    返します。

    .. Example: ``"127.0.0.1:8000"``

    例: ``"127.0.0.1:8000"``

    .. .. note:: The :meth:`~HttpRequest.get_host()` method fails when the host is
            behind multiple proxies. One solution is to use middleware to rewrite
            the proxy headers, as in the following example::

    .. note:: ホストが複数のプロキシを通しているとき、
        :meth:`~HttpRequest.get_host()` は失敗します。一つの解決策は
        ロキシヘッダを書き換えるミドルウェアを利用することです。
        以下に例を示します::

            class MultipleProxyMiddleware(object):
                FORWARDED_FOR_FIELDS = [
                    'HTTP_X_FORWARDED_FOR',
                    'HTTP_X_FORWARDED_HOST',
                    'HTTP_X_FORWARDED_SERVER',
                ]

                def process_request(self, request):
                    """
                    Rewrites the proxy headers so that only the most
                    recent proxy is used.
                    """
                    for field in self.FORWARDED_FOR_FIELDS:
                        if field in request.META:
                            if ',' in request.META[field]:
                                parts = request.META[field].split(',')
                                request.META[field] = parts[-1].strip()

        .. This middleware should be positioned before any other middleware that
            relies on the value of :meth:`~HttpRequest.get_host()` -- for instance,
            :class:`~django.middleware.common.CommonMiddleware` or
            :class:`~django.middleware.csrf.CsrfViewMiddleware`.

        このミドルウェアは :meth:`~HttpRequest.get_host()` の値を利用する
        :class:`~django.middleware.common.CommonMiddleware` や
        :class:`~django.middleware.csrf.CsrfViewMiddleware` のような
        他のミドルウェアの前に置かなければなりません。

.. method:: HttpRequest.get_full_path()

    ``path`` と、そのあとに続くクエリ文字列があれば返します。

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

.. method:: HttpRequest.build_absolute_uri(location)

   ``location`` の絶対 URI を計算して返します。引数 ``location`` を省略する
   と、 ``location`` の値として ``request.get_full_path()`` を使います。

   ``location`` の値がすでに絶対 URI であれば、値を変更しません。そうでない
   場合、リクエスト中のサーバに関する変数を使って URI を構築します。

   例: ``"http://example.com/music/bands/the_beatles/?print=true"``

.. method:: HttpRequest.get_signed_cookie(key, default=RAISE_ERROR, salt='', max_age=None)

    .. versionadded:: 1.4

    .. Returns a cookie value for a signed cookie, or raises a
        :class:`~django.core.signing.BadSignature` exception if the signature is
        no longer valid. If you provide the ``default`` argument the exception
        will be suppressed and that default value will be returned instead.

    署名付きクッキーのクッキーの値を返すか、署名が有効でない場合は
    :class:`~django.core.signing.BadSignature` 例外を発生します。
    ``default`` 引数を与えた場合は、例外は抑制され、代わりにデフォルトの
    値が返されます。

    .. The optional ``salt`` argument can be used to provide extra protection
        against brute force attacks on your secret key. If supplied, the
        ``max_age`` argument will be checked against the signed timestamp
        attached to the cookie value to ensure the cookie is not older than
        ``max_age`` seconds.

    オプションの ``salt`` 引数はシークレットキーへのブルートフォース攻撃に
    対する追加の防御を与えるために利用されます。引数が与えられた場合、
    ``max_age`` 引数は、 ``max_age`` 秒よりクッキーが古くないかを確認する
    ために、クッキーの署名されたタイムスタンプに対してチェックされます。

    .. For example::

    例::

         >>> request.get_signed_cookie('name')
         'Tony'
         >>> request.get_signed_cookie('name', salt='name-salt')
         'Tony' # assuming cookie was set using the same salt
         >>> request.get_signed_cookie('non-existing-cookie')
         ...
         KeyError: 'non-existing-cookie'
         >>> request.get_signed_cookie('non-existing-cookie', False)
         False
         >>> request.get_signed_cookie('cookie-that-was-tampered-with')
         ...
          BadSignature: ...
          >>> request.get_signed_cookie('name', max_age=60)
          ...
          SignatureExpired: Signature age 1677.3839159 > 60 seconds
          >>> request.get_signed_cookie('name', False, max_age=60)
          False

    .. See :doc:`cryptographic signing </topics/signing>` for more information.

    詳細は :doc:`暗号による署名 </topics/signing>` を参照して下さい。

.. method:: HttpRequest.is_secure()

    リクエストがセキュアである、すなわち HTTPS を介したリクエストのときに
    ``True`` を返します。

.. method:: HttpRequest.is_ajax()

   リクエストが ``XMLHttpRequest`` である場合には ``True`` に設定されます。
   リクエストが ``XMLHttpRequest`` であるかどうかは、 
   ``HTTP_X_REQUESTED_WITH`` ヘッダに文字列 ``XMLHttpRequest`` があるかどう
   かで判別します。このヘッダは、ほとんどのモダンな主要 JavaScript ライブ
   ラリでサポートされています。
   ブラウザ側で XMLHttpRequest を呼び出す独自のコードを書いている場合、
   ``is_ajax()`` を正しく機能させたいなら、 ``HTTP_X_REQUESTED_WITH`` ヘッ
   ダを適切に設定してください。

.. method:: HttpRequest.read(size=None)
.. method:: HttpRequest.readline()
.. method:: HttpRequest.readlines()
.. method:: HttpRequest.xreadlines()
.. method:: HttpRequest.__iter__()

    .. versionadded:: 1.3

    .. Methods implementing a file-like interface for reading from an
        HttpRequest instance. This makes it possible to consume an incoming
        request in a streaming fashion. A common use-case would be to process a
        big XML payload with iterative parser without constructing a whole
        XML tree in memory.

    HTTPRequest のインスタンスからファイルのようなインターフェースで
    読むメソッドです。このメソッドはやってくるリクエストをストリーミング
    のやり方で消費することを可能にします。一般的な利用事例は大きな
    XML ペイロードを、反復パーサでメモリ上にすべての XML ツリーを
    構築することなく、処理することです。

    .. Given this standard interface, an HttpRequest instance can be
        passed directly to an XML parser such as ElementTree::

    この標準的なインターフェースを使って、直接 ElementTree のような
    XML パーサに HTTPRequest インスタンスを渡すことが出来ます::

        import xml.etree.ElementTree as ET
        for element in ET.iterparse(request):
            process(element)


UploadedFile オブジェクト
=========================

.. class:: UploadedFile


属性
----

.. attribute::  UploadedFile.name

    .. The name of the uploaded file.

    アップロードされたファイルの名前。

.. attribute:: UploadedFile.size

    .. The size, in bytes, of the uploaded file.

    バイト単位でのアップロードされたファイルのサイズ。

メソッド
--------

.. method:: UploadedFile.chunks(chunk_size=None)

    .. Returns a generator that yields sequential chunks of data.

    データの連続したチャンクを生成するジェネレータを返します。

.. method:: UploadedFile.read(num_bytes=None)

    .. Read a number of bytes from the file.

    引数のバイト数分ファイルを読みます。


QueryDict オブジェクト
======================

:class:`~django.http.HttpRequest` オブジェクト内では、 ``GET`` と ``POST``
属性は :class:`django.http.QueryDict` のインスタンスです。
:class:`~django.http.QueryDict` は辞書ライクなクラスで、同じキーに対して複
数の値を取り得るようにカスタマイズされています。これは、 HTML のフォーム要
素には、例えば ``<select multiple="multiple">`` のように、同じキーに対して
複数の値を渡すものがあるからです。

:class:`~django.http.QueryDict` インスタンスは、 ``copy()`` を作らないかぎ
り変更できません。これは、 ``request.POST`` や ``request.GET`` の属性を直接
変更できないということです。

メソッド
---------

:class:`~django.http.QueryDict` は辞書型のサブクラスなので、全ての標準的な
辞書型のメソッドを実装しています。ただし、以下の点が異なります:

.. method:: QueryDict.__getitem__(key)

    指定のキーに対する値を返します。一つのキーに複数の値が存在する場合、
    ``__getitem__()`` はリストの末尾の値を返します。キーに対応する値がなけ
    れば、 :exc:`django.utils.datastructures.MultiValueDictKeyError` を送出
    します。 (この例外は :exc:`KeyError` のサブクラスなので、
    :exc:`KeyError`` を見張っていれば捕捉できます。)

.. method:: QueryDict.__setitem__(key, value)

    指定のキーに対する値を ``[value]`` (``value`` という値が一つだけ入った
    リスト) にします。副作用をともなう他の関数と同じく、このメソッドを呼び
    出せるのは (``copy()`` を使って生成したオブジェクトのような) 変更可能な
    :class:`~django.http.QueryDict` だけです。

.. method:: QueryDict.__contains__(key)

    指定のキーが設定されている場合に ``True`` を返します。
    ``if "foo" in request.GET`` のような書き方を実現します。

.. method:: QueryDict.get(key, default)

    上の ``__getitem__()`` と同じロジックですが、キーに対応する値がないとき
    にデフォルト値を返すフックがあります。

.. method:: QueryDict.setdefault(key, default)

    標準の辞書型の ``setdefault()`` と同じですが、内部的に ``__setitem__()``
    を使います。

.. method:: QueryDict.update(other_dict) 

    :class:`~django.http.QueryDict` または標準の辞書型を引数にとります。標
    準の辞書型の ``update()`` メソッドと同じですが、現在の値を置き換えるの
    ではなく、現在の値のリストに *追加* します。例えば::

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

.. method:: QueryDict.items()

    標準の辞書型の :meth:`items()`` メソッドと同じですが、 
    ``__getitem__()`` と同じ、最後の値を返すロジックを使います。例えば::

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

.. method:: QueryDict.iteritems()

    標準の辞書型の ``iteritems()`` によく似ています。
    :meth:`QueryDict.items()` と同じく、
    :meth:`QueryDict.__getitem__()` で最後の値を返します。

.. method:: QueryDict.iterlists()

    :meth:`QueryDict.iteritems()` に似ていますが、各辞書のメンバの値を全て
    リストとして返します。

.. method:: QueryDict.values()

    ``values()`` -- 標準の辞書型の ``values()`` メソッドと同じですが、
    ``__getitem__()`` と同じ、最後の値を返すロジックを使います。例えば::

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

.. method:: QueryDict.itervalues()

    :meth:`QueryDict.values()` と同じですが、イテレータです。

加えて、 :class:`~django.http.QueryDict` には以下のメソッドがあります:

.. method:: QueryDict.copy()

    Python 標準ライブラリの ``copy.deepcopy()`` を使ってオブジェクトのコピー
    を生成して返します。コピーは変更可能になり、値を変更できます。


.. method:: QueryDict.getlist(key, default)

    .. Returns the data with the requested key, as a Python list. Returns an
        empty list if the key doesn't exist and no default value was provided.
        It's guaranteed to return a list of some sort unless the default value
        was no list.

    要求されたキーに対して、 Python のリスト型を返します。キーに対応する値
    がなく、デフォルトの値が与えられていなければ、空のリストを返します。
    このメソッドは、デフォルトの値がリストでない場合を除き、確実に何らかの
    リストを返します。

    .. versionchanged:: 1.4
        ``default`` パラメタが追加されました。

.. method:: QueryDict.setlist(key, list_)

    キーに対して ``list_`` を対応づけます (``__setitem__()`` と違います)。

.. method:: QueryDict.appendlist(key, item)

    キーに関連づけられている内部的なリストに要素を追加します。

.. method:: QueryDict.setlistdefault(key, default_list)

    ``setdefault`` に似ていますが、単一の値ではなく値のリストを引数にとりま
    す。

.. method:: QueryDict.lists()

    動作は :meth:`items()` に似ていますが、全ての値をリストで返します。例え
    ば::

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

.. method:: QueryDict.dict()

    .. versionadded:: 1.4

    .. Returns ``dict`` representation of ``QueryDict``. For every (key, list)
        pair in ``QueryDict``, ``dict`` will have (key, item), where item is one
        element of the list, using same logic as :meth:`QueryDict.__getitem__()`::

     ``QueryDict`` の ``dict`` 表現を返します。 ``QueryDict`` のすべての
    (キー, リスト) の表現に対し、 ``dict`` は (キー, アイテム)を持ちます。
    アイテムとなるのはリストのうち、ひとつの要素で、
    :meth:`QueryDict.__getitem__()` と同じロジックを用いています。

        >>> q = QueryDict('a=1&a=3&a=5')
        >>> q.dict()
        {u'a': u'5'}

.. method:: QueryDict.urlencode([safe])

    .. Returns a string of the data in query-string format. Example::

    データをクエリ文字列形式にフォーマットした文字列を返します。例えば:

        >>> q = QueryDict('a=2&b=3&b=5')
        >>> q.urlencode()
        'a=2&b=3&b=5'

    .. versionchanged:: 1.3
       ``safe`` パラメタが追加されました。

    .. Optionally, urlencode can be passed characters which
        do not require encoding. For example::

    オプションで、urlencodeにエンコードする必要がない文字列を渡すことが
    出来ます。例えば::

        >>> q = QueryDict('', mutable=True)
        >>> q['next'] = '/a&b/'
        >>> q.urlencode(safe='/')
        'next=/a%26b/'


HttpResponse オブジェクト
=========================

.. class:: HttpResponse

Django によって自動生成される :class:`~django.http.HttpRequest` オブジェク
トとは対象的に、 :class:`~django.http.HttpResponse` オブジェクトは自分で生
成せねばなりません。ビューを書くときにはいつでも、
:class:`~django.http.HttpResponse` インスタンスを生成して、値を設定し、戻り
値として返さねばなりません。

:class:`~django.http.HttpResponse` クラスは :mod:`django.http` モジュールで
定義されています。

使いかた
--------

文字列を渡す
~~~~~~~~~~~~

:class:`~django.http.HttpResponse` の典型的な使い方は、ページの内容を文字列
としてコンストラクタに渡すというものです::

    >>> response = HttpResponse("Here's the text of the Web page.")
    >>> response = HttpResponse("Text only, please.", content_type="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>")

イテレータを渡す
~~~~~~~~~~~~~~~~

最後に、ハードコードされた文字列ではなくイテレータも
:class:`~django.http.HttpResponse` に渡せます。このテクニックを使う場合は以
下のガイドラインに従って下さい:

* イテレータは文字列を返さねばなりません。
* イテレータをコンテンツに指定して :class:`~django.http.HttpResponse`
  を初期化した場合、 :class:`~django.http.HttpResponse` インスタンスは
  ファイルライクオブジェクトとして扱えず、ファイルライクオブジェクトと
  して操作すると ``Exception`` を送出します。

ヘッダ情報をセットする
~~~~~~~~~~~~~~~~~~~~~~~

.. To set or remove a header in your response, treat it like a dictionary::

レスポンスのヘッダをセットしたり削除したりするには、レスポンスを辞書の
ように扱います::

    >>> response = HttpResponse()
    >>> response['Cache-Control'] = 'no-cache'
    >>> del response['Cache-Control']

辞書と異なり、 もしヘッダーが存在しない場合も、``del`` は ``KeyError`` を
発生させません。

..  Note that unlike a dictionary, ``del`` doesn't raise ``KeyError`` if the header
    doesn't exist.

HTTP ヘッダには改行を含めてはなりません。改行文字 (CR や LF) の入ったヘッダ
をセットしようとすると、 ``BadHeaderError`` を送出します。

レスポンスをブラウザにファイルアタッチメントとして扱わせる
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

レスポンスをブラウザにファイルアタッチメントとして扱わせるには、
``content_type`` 引数を使い、 ``Content-Disposition`` ヘッダをセットして
ください。例えば、 Microsoft Excel のスプレッドシートを返すには、以下の
ようにします::

    >>> response = HttpResponse(my_data, content_type='application/vnd.ms-excel')
    >>> response['Content-Disposition'] = 'attachment; filename=foo.xls'

``Content-Disposition`` ヘッダの利用は Django 固有の仕様ではありませんが、
記法を忘れやすいのでここに示しておきます。

属性
----

.. attribute:: HttpResponse.content

    .. A string representing the content, encoded from a Unicode
        object if necessary.

    コンテンツを表現する文字列表現です。必要に応じて Unicode オブジェクト
    からエンコードされます。

.. attribute:: HttpResponse.status_code

    .. The `HTTP Status code`_ for the response.

    レスポンスの `HTTP Status code`_ です。

メソッド
--------

.. method:: HttpResponse.__init__(content='', mimetype=None, status=200, content_type=DEFAULT_CONTENT_TYPE)

    指定のページコンテンツ (文字列) と MIME タイプで
    :class:`~django.http.HttpResponse` オブジェクトをインスタンス化します。
    :setting:`DEFAULT_CONTENT_TYPE` は ``'text/html'`` です。

    .. ``content`` should be an iterator or a string. If it's an
        iterator, it should return strings, and those strings will be
        joined together to form the content of the response. If it is not
        an iterator or a string, it will be converted to a string when
        accessed.

    ``content`` はイタレータまたは文字列でなければなりません。イタレータに
    する場合、イタレータは文字列を返さねばなりません。イテレータを指定した
    場合、レスポンスの内容はイテレータの返す文字列を結合して生成されます。
    イタレータまたは文字列でない場合、アクセスした際に文字列に変換される
    でしょう。

    ``status`` はレスポンスの  `HTTP 状態コード`_ です。

    ``content_type`` は ``mimetype`` の別名にすぎません。以前、このパラメタ
    には ``mimetype`` という名前しかありませんでしたが、実際のところ、この
    パラメタに指定する値は HTTP の ``Content-Type`` ヘッダに入る内容であり、
    MIME タイプ仕様にはない文字セットエンコーディングの指定を含んでいました。
    そこで、 ``mimetype`` が指定されている (``None`` でない) 場合にはその値
    を使い、それ以外の場合には ``content_type`` を使うように変更しました。
    どちらのパラメタも省略すると、 :setting:`DEFAULT_CONTENT_TYPE` 設定を使
    います。

.. method:: HttpResponse.__setitem__(header, value)

    ヘッダ名と値を設定します。 ``header`` と ``value`` は文字列にせねばなり
    ません。

.. method:: HttpResponse.__delitem__(header)

    指定の名前のヘッダを削除します。ヘッダが存在しなければ、暗黙のうちに失
    敗します。大小文字を区別しません。

.. method:: HttpResponse.__getitem__(header)

    指定のヘッダ名に対応する値を返します。大小文字を区別しません。

.. method:: HttpResponse.has_header(header)

    大小文字を区別せずに指定の名前のヘッダがあるか調べ、 ``True`` または
    ``False`` を返します。

.. method:: HttpResponse.set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=True)

    .. versionchanged:: 1.3

    .. The possibility of specifying a ``datetime.datetime`` object in
        ``expires``, and the auto-calculation of ``max_age`` in such case
        was added. The ``httponly`` argument was also added.

    ``expires`` に ``datetime.datetime`` オブジェクトを指定すると、
    ``max_age`` が自動的に計算されます。 ``httponly`` 引数も追加されました。

    .. versionchanged:: 1.4

    .. The default value for httponly was changed from ``False`` to ``True``.

    httponly のデフォルトの値が ``False`` から ``True`` に変わりました。

    .. Sets a cookie. The parameters are the same as in the :class:`Cookie.Morsel`
        object in the Python standard library.

    クッキーを設定します。パラメタは Python 標準ライブラリの
    :class:`Cookie.Morsel` オブジェクトと同じ形式です。

    .. * ``max_age`` should be a number of seconds, or ``None`` (default) if
          the cookie should last only as long as the client's browser session.
          If ``expires`` is not specified, it will be calculated.
        * ``expires`` should either be a string in the format
          ``"Wdy, DD-Mon-YY HH:MM:SS GMT"`` or a ``datetime.datetime`` object
          in UTC. If ``expires`` is a ``datetime`` object, the ``max_age``
          will be calculated.
        * Use ``domain`` if you want to set a cross-domain cookie. For example,
          ``domain=".lawrence.com"`` will set a cookie that is readable by
          the domains www.lawrence.com, blogs.lawrence.com and
          calendars.lawrence.com. Otherwise, a cookie will only be readable by
          the domain that set it.
        * Use ``httponly=True`` if you want to prevent client-side
          JavaScript from having access to the cookie.
    * ``max_age`` には秒数または ``None`` (デフォルト値) を指定します。
      デフォルト値の場合、クッキーはクライアントのブラウザのセッションの
      間だけ持続します。 ``expires`` が明示されていない場合、
      ``expires`` は計算されます。
    * ``expires`` には ``"Wdy, DD-Mon-YY HH:MM:SS GMT"`` の形式の文字列か
      UTC での ``datetime.datetime`` オブジェクトを指定します。
      ``expires`` が ``datetime`` オブジェクトの場合、 ``max_age`` は
      自動的に計算されます。
    * 別のドメインのクッキー (cross-domain cookie) を設定したい場合には、
      ``domain`` を使います。例えば、 ``domain=".lawrence.com"`` にする
      と、 www.lawrence.com, blogs.lawrence.com, calendars.lawrence.com
      といったサイトでだけ読めるようになります。それ以外の場合、クッキー
      はクッキーを設定したドメインでしか読めません。
    * クライアントサイドの JavaScript がクッキーへアクセスすることを
      妨げたい場合、 ``httponly=True`` を使います。

      .. HTTPOnly_ is a flag included in a Set-Cookie HTTP response
          header. It is not part of the :rfc:`2109` standard for cookies,
          and it isn't honored consistently by all browsers. However,
          when it is honored, it can be a useful way to mitigate the
          risk of client side script accessing the protected cookie
          data.

      HTTPOnly_ は HTTP レスポンスヘッダの Set-Cookie に含まれるフラグです。
      これはクッキーの標準の :rfc:`2109` の一部ではなく、全てのブラウザに
      よって常に守られません。しかし守られた場合、これはクライアントサイド
      スクリプトが、保護されたクッキーのデータにアクセスする危険を緩和す
      る有用な方法です。

    .. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly

.. method:: HttpResponse.set_signed_cookie(key, value='', salt='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=True)

    .. versionadded:: 1.4

    .. Like :meth:`~HttpResponse.set_cookie()`, but
        :doc:`cryptographic signing </topics/signing>` the cookie before setting
        it. Use in conjunction with :meth:`HttpRequest.get_signed_cookie`.
        You can use the optional ``salt`` argument for added key strength, but
        you will need to remember to pass it to the corresponding
        :meth:`HttpRequest.get_signed_cookie` call.

    :meth:`~HttpResponse.set_cookie()` と同様のメソッドです。しかし、
    セットする前に :doc:`暗号による署名 </topics/signing>` を行って下さい。
    :meth:`HttpRequest.get_signed_cookie` と併せて使って下さい。オプションで
    鍵の強化のために ``salt`` 引数を使うことが出来ますが、対応する
    :meth:`HttpRequest.get_signed_cookie` の呼び出しでも、 ``salt`` 引数を
    渡す必要があります。

.. method:: HttpResponse.delete_cookie(key, path='/', domain=None)

    指定のキーに対するクッキーを削除します。キーが存在しなければ、暗黙のう
    ちに失敗します。

    cookie の動作原理上、 ``path`` と ``domain`` を ``set_cookie()`` に指定
    した値と同じにしないと、クッキーを削除できなくなります。

.. method:: HttpResponse.write(content)

    :class:`~django.http.HttpResponse` インスタンスをファイルライクオブジェ
    クトのように扱うためのメソッドです。

.. method:: HttpResponse.flush()

    :class:`~django.http.HttpResponse` インスタンスをファイルライクオブジェ
    クトのように扱うためのメソッドです。

.. method:: HttpResponse.tell()

    :class:`~django.http.HttpResponse` インスタンスをファイルライクオブジェ
    クトのように扱うためのメソッドです。

.. _HTTP Status code: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
.. _`HTTP 状態コード`: `HTTP Status code`_

.. _ref-httpresponse-subclasses:

HttpResponse のサブクラス
-------------------------

Django には、様々なタイプの HTTP レスポンスを扱うための
:class:`~django.http.HttpResponse` のサブクラスがあります。これらのサブクラ
スは :class:`~django.http.HttpResponse` と同じく :mod:`django.http` モジュー
ルにあります。

.. class:: HttpResponseRedirect

    コンストラクタはリダイレクト先のパスを示す引数を一つだけ取ります。リダ
    イレクト先は完全指定の URL (例えば ``"http://www.yahoo.com/search/"``) 
    でも、ドメイン名のない絶対 URL ( ``"/search/"``) でもかまいません。この
    レスポンスオブジェクトは HTTP 状態コード 302 を返します。

.. class:: HttpResponsePermanentRedirect

    ``HttpResponseRedirect`` と同じですが、"found" リダイレクト (HTTP 状態
    コード 302) ではなく永続リダイレクト (状態コード 301) を使います。

.. class:: HttpResponseNotModified

    コンストラクタは引数をとりません。ユーザが最後にリクエストしたときから
    ページが変更されていないこと  (状態コード 304) を知らせるために使います。

.. class:: HttpResponseBadRequest

    :class:`~django.http.HttpResponse` と同じように振舞いますが、状態コード
    400 を使います。

.. class:: HttpResponseNotFound

    :class:`~django.http.HttpResponse` と同じですが、状態コード 404 を使い
    ます。

.. class:: HttpResponseForbidden

    :class:`~django.http.HttpResponse` と同じですが、状態コード 403 を使い
    ます。

.. class:: HttpResponseNotAllowed

    :class:`~django.http.HttpResponse` と同じですが、状態コード 405 を使い
    ます。許可されている HTTP メソッドのリスト (例えば ``['GET', 'POST']``)
    を必須の引数としてとります。

.. class:: HttpResponseGone

    :class:`~django.http.HttpResponse` と同じですが、状態コード 410 を使い
    ます。

.. class:: HttpResponseServerError

    :class:`~django.http.HttpResponse` と同じですが、状態コード 500 を使います。

.. note::

    .. If a custom subclass of :class:`HttpResponse` implements a ``render``
        method, Django will treat it as emulating a
        :class:`~django.template.response.SimpleTemplateResponse`, and the
        ``render`` method must itself return a valid response object.

    もし、 :class:`HttpResponse` のカスタムサブクラスが ``render`` メソッドを
    実装している場合は、 Django はそれを
    :class:`~django.template.response.SimpleTemplateResponse` を真似たもの
    として扱うでしょう、また ``render`` メソッドは有効なレスポンスオブジェクトを
    返さなければなりません。