Django v1.0 documentation

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

revision-up-to:8961 (1.0)

簡単な概要

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

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

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

HttpRequest オブジェクト

class HttpRequest

属性

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

HttpRequest.path

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

例: "/music/bands/the_beatles/"

HttpRequest.method

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

if request.method == 'GET':
    do_something()
elif request.method == 'POST':
    do_something_else()
HttpRequest.encoding
Django 1.0 で新たに登場しました.

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

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

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

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

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

HttpRequest.REQUEST

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

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

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

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

開発版の Django で変更された仕様

以前のバージョンの Django では、 request.FILES に通常の辞書が入っ ていて、その辞書がアップロードされたファイルを表していました。この 仕様は変更され、ファイルは後述の UploadedFile オブジェクトで表 現されるようになりました。

UploadedFile オブジェクトは、以前の辞書インタフェースをエミュレー トしていますが、これは撤廃されたインタフェースであり、次の Django のリリースでは除去される予定です。

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

  • read(num_bytes=None) -- ファイルから最大 num_bytes 読み出 します。
  • name -- アップロードされたファイルの名前です。
  • size -- アップロードされたファイルのサイズ (単位はバイト) です。
  • chunks(chunk_size=None) -- ファイルから一定サイズのチャンクを 順に取り出して返すジェネレータです。

詳しくは ファイルの管理 を参照してください。

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

HttpRequest.META

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

  • CONTENT_LENGTH
  • CONTENT_TYPE
  • HTTP_ACCEPT_ENCODING
  • HTTP_ACCEPT_LANGUAGE
  • HTTP_HOST -- クライアントから送信された HTTP Host ヘッダです。
  • HTTP_REFERER -- リクエスト対象のページを参照しているページが ある場合、そのページの URL です。
  • HTTP_USER_AGENT -- クライアントのユーザエージェントを表す文字 列です。
  • QUERY_STRING -- パース前の単一のクエリ文字列です。
  • REMOTE_ADDR -- クライアントの IP アドレスです。
  • REMOTE_HOST -- クライアントのホスト名です。
  • REQUEST_METHOD -- "GET""POST" のような文字列です。
  • SERVER_NAME -- サーバのホスト名です。
  • SERVER_PORT -- サーバのポート番号です。
HttpRequest.user

現在ログインしているユーザを表す django.models.auth.models.User オブ ジェクトです。ユーザが現在ログインしていない場合には、 userdjango.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 を有効にした場合だけです。詳しくは Django でのユーザ認証 を参照してください。

HttpRequest.session
読み書き可能な辞書ライクオブジェクトで、現在のセッションを表現しています。 この辞書はインストールされている Django でセッションが有効な場合にのみ 利用できます。詳しくは セッションのドキュメント を参照してくださ い。
HttpRequest.raw_post_data
HTTP POST データそのものです。高度な処理を行いたいときに便利です。普段 は POST を使ってください。
HttpRequest.urlconf
Django 自体はこの属性を設定しませんが、他のコード(自作のミドルウェアな ど)でこの属性を設定した場合、Djangoはその値を ROOT_URLCONF の代わ りにルート URLconf モジュール名として使います。 詳しくは 「 Django のリクエスト処理 」を参照してください。

メソッド

HttpRequest.get_host()
Django 1.0 で新たに登場しました.

リクエストの送信元を HTTP_X_FORWARDED_HOST または HTTP_HOST ヘッ ダを (順に) 調べて返します。クライアントがこれらの値を提供していない場合、 PEP 333 に従って、 SERVER_NAMESERVER_PORT の組み合わせを 返します。

Example: "127.0.0.1:8000"

HttpRequest.get_full_path()

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

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

HttpRequest.build_absolute_uri(location)
Django 1.0 で新たに登場しました.

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

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

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

HttpRequest.is_secure()
リクエストがセキュアである、すなわち HTTPS を介したリクエストのときに True を返します。
HttpRequest.is_ajax()
Django 1.0 で新たに登場しました.

リクエストが XMLHttpRequest である場合には True に設定されます。 リクエストが XMLHttpRequest であるかどうかは、 HTTP_X_REQUESTED_WITH ヘッダに文字列 XMLHttpRequest があるかどう かで判別します。このヘッダは、以下のような主要 JavaScript ライブラリでサ ポートされています:

  • jQuery
  • Dojo
  • MochiKit
  • MooTools
  • Prototype
  • YUI

ブラウザ側で XMLHttpRequest を呼び出す独自のコードを書いている場合、 is_ajax() を正しく機能させたいなら、 HTTP_X_REQUESTED_WITH ヘッ ダを適切に設定してください。

QueryDict オブジェクト

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

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

メソッド

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

QueryDict.__getitem__(key)
指定のキーに対する値を返します。一つのキーに複数の値が存在する場合、 __getitem__() はリストの末尾の値を返します。キーに対応する値がなけ れば、 django.utils.datastructure.MultiValueDictKeyError を送出 します。 (この例外は KeyError のサブクラスなので、 KeyError` を見張っていれば捕捉できます。)
QueryDict.__setitem__(key, value)
指定のキーに対する値を [value] (value という値が一つだけ入った リスト) にします。副作用をともなう他の関数と同じく、このメソッドを呼び 出せるのは (copy() を使って生成したオブジェクトのような) 変更可能な QueryDict だけです。
QueryDict.__contains__(key)
指定のキーが設定されている場合に True を返します。 if "foo" in request.GET のような書き方を実現します。
QueryDict.get(key, default)
上の __getitem__() と同じロジックですが、キーに対応する値がないとき にデフォルト値を返すフックがあります。
QueryDict.setdefault(key, default)
標準の辞書型の setdefault() と同じですが、内部的に __setitem__ を使います。
QueryDict.update(other_dict)

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

>>> 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']
QueryDict.items()

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

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

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

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

加えて、 QueryDict には以下のメソッドがあります:

QueryDict.copy()
Python 標準ライブラリの copy.deepcopy() を使ってオブジェクトのコピー を生成して返します。コピーは変更可能になり、値を変更できます。
QueryDict.getlist(key)
要求されたキーに対して、 Python のリスト型を返します。キーに対応する値 がなければ空のリストを返します。このメソッドは確実に何らかのリストを返 します。
QueryDict.setlist(key, list_)
キーに対して list_ を対応づけます (__setitem__() と違います)。
QueryDict.appendlist(key, item)
キーに関連づけられている内部的なリストに要素を追加します。
QueryDict.setlistdefault(key, default_list)
setdefault に似ていますが、単一の値ではなく値のリストを引数にとりま す。
QueryDict.lists()
``items()`` に似ていますが、全ての値をリストで返します。例えば::
>>> q = QueryDict('a=1&a=2&a=3')
>>> q.lists()
[('a', ['1', '2', '3'])]
QueryDict.urlencode()
データをクエリ文字列形式にフォーマットした文字列を返します。例えば: "a=2&b=3&b=5" のようになります。

実装に関する注意

GET, POST, COOKIES, FILES, META, REQUEST, raw_post_data および user といった属性はすべて遅延読み込み (lazily load) されます。すなわち、 Django はコード中で要求されるまで、これらの値を 計算するためにリソースを消費しません。

HttpResponse オブジェクト

class HttpResponse

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

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

使いかた

文字列を渡す

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

>>> 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>")

ヘッダの追加や削除は辞書とおなじ書法で書けます:

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

該当するヘッダがなくても、 delKeyError を送出しないので気をつけ てください。

イテレータを渡す

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

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

ヘッダ情報をセットする

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

>>> response = HttpResponse()
>>> response['Pragma'] = 'no-cache'

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

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

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

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

メソッド

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

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

content はイテレータまたは文字列にできます。イテレータにする場合、 イテレータは文字列を返さねばなりません。イテレータを指定した場合、レス ポンスの内容はイテレータの返す文字列を結合して生成されます。

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

Django 1.0 で新たに登場しました.

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

HttpResponse.__setitem__(header, value)
ヘッダ名と値を設定します。 headervalue は文字列にせねばなり ません。
HttpResponse.__delitem__(header)
指定の名前のヘッダを削除します。ヘッダが存在しなければ、暗黙のうちに失 敗します。大小文字を区別します。
HttpResponse.__getitem__(header)
指定のヘッダ名に対応する値を返します。大小文字を区別します。
HttpResponse.has_header(header)
大小文字を区別せずに指定の名前のヘッダがあるか調べ、 True または False を返します。

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

  • max_age には秒数または None (デフォルト値) を指定します。 デフォルト値では、クッキーはクライアントブラウザとのセッションの 間だけ持続します。
  • expires"Wdy, DD-Mon-YY HH:MM:SS GMT" の形式の文字列で す。
  • 別のドメインのクッキー (cross-domain cookie) を設定したい場合には、 domain を使います。例えば、 domain=".lawrence.com" にする と、 www.lawrence.com, blogs.lawrence.com, calendars.lawrence.com といったサイトでだけ読めるようになります。それ以外の場合、クッキー はクッキーを設定したドメインでしか読めません。

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

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

HttpResponse.content()
Python 文字列の内容を返します。必要ならば Unicode オブジェクトにエンコー ドします。メソッドではなくプロパティなので、 r.content() ではなく r.content になることに注意して下さい。
HttpResponse.write(content)
HttpResponse インスタンスをファイルライクオブジェ クトのように扱うためのメソッドです。
HttpResponse.flush()
HttpResponse インスタンスをファイルライクオブジェ クトのように扱うためのメソッドです。
HttpResponse.tell()
HttpResponse インスタンスをファイルライクオブジェ クトのように扱うためのメソッドです。

HttpResponse のサブクラス

Django には、様々なタイプの HTTP レスポンスを扱うための HttpResponse のサブクラスがあります。これらのサブクラ スは HttpResponse と同じく 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
Django 1.0 で新たに登場しました.

HttpResponse と同じように振舞いますが、状態コード 400 を使います。

class HttpResponseNotFound
HttpResponse と同じですが、状態コード 404 を使い ます。
class HttpResponseForbidden
HttpResponse と同じですが、状態コード 403 を使い ます。
class HttpResponseNotAllowed
HttpResponse と同じですが、状態コード 405 を使い ます。許可されている HTTP メソッドのリスト (例えば ['GET', 'POST']) を必須の引数としてとります。
class HttpResponseGone
HttpResponse と同じですが、状態コード 410 を使い ます。
class HttpResponseServerError
HttpResponse と同じですが、状態コード 500 を使います。