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

16.1. 概要

Kay は、WSGI に準拠した Werkzeug のリクエストオブジェクト、および、レスポンスオブジェクトを採用しています。Kay は、ブラウザからアクセスされるとリクエストオブジェクトを生成し、URL マッピングによって特定した view 関数に渡します。 view 関数は第1引数にリクエストオブジェクトをとり、レスポンスオブジェクトを生成して返す必要があります。ここでは、リクエストオブジェクト、および、レスポンスオブジェクトの構成について説明します。

16.2. リクエストオブジェクト

  • view は、リクエストオブジェクトを引数にとります。
  • リクエストオブジェクトは読み込み専用です。変更は許可されていません。
  • デフォルトでは、リクエストオブジェクトのテキストデータはすべて UTF-8 でエンコードされています。

16.2.1. 属性とメソッド

リクエストオブジェクトは以下の属性を持っています。

class werkzeug.Request
accept_charsets
クライアントがサポートしている文字セットのリストです。 CharsetAccept オブジェクトとして提供されます。
accept_encodings
クライアントが許容しているエンコーディングのリストです。HTTP の用語において、gzipのようなエンコーディングの圧縮です。 文字セットについては accept_charsets を参照して下さい。
accept_languages
クライアントが許容している言語のリストです。 LanguageAccept オブジェクトとして提供されます。
accept_mimetypes
クライアントがサポートしている mimetype のリストです。 MIMEAccept オブジェクトとして提供されます。
access_route
フォワードヘッダがある場合、クライアントのIPからサーバの直前のプロキシサーバまでのIPアドレスのリストが格納されます。
args
パースされたURLパラメータです。 ImmutableMultiDict に格納されます。
authorization
パースされたフォームの中の Authorization オブジェクトです。
base_url
url と似ていますが、クエリ文字列が省かれています。
cache_control
受信したキャッシュコントロールヘッダを RequestCacheControl オブジェクトとして提供します。
charset
リクエストの文字セットです。デフォルト値は UTF-8 です。
content_length
Content-Length エンティティヘッダフィールドは、受信者に送信されるエンティティボディのサイズを示します。HEAD メソッドの場合は GET リクエストされた場合に送信されるエンティティボディのサイズを示します。
content_type
Content-Type エンティティヘッダフィールドは、受信者に送信されるエンティティボディのメディアタイプを示します。HEADメソッドの場合、GET リクエストされた場合に送信されるエンティティボディのメディアタイプを示します。
cookies
ディクショナリとして、cookieの値を扱うことができます。
data

バッファリングされたクライアントからの入力データを文字列に読み込みます。普通は data にアクセスする方法としてはよくない方法です。クライアントが、サーバのメモリを浪費させるために、何十メガバイトものデータを送ることができてしまうためです。

これを避けるには、 content_length を先にチェックしてください。

date
Date ジェネラルヘッダフィールドは、メッセージが生成された日付と時間を表します。RFC 822の orig-date と同じセマンティクスをもっています。
encoding_errors
エラーハンドリングプロシージャです。デフォルト値は ignore です。
environ
リクエストオブジェクトがデータを取り扱うための WSGI env です。
files

アップロードされたすべてのファイルを格納した MultiDict オブジェクトです。 files のそれぞれのキーは <input type="file" name=""> のnameです。それぞれの値は Werkzeug の FileStorage オブジェクトです。

files は、リクエストメソッドが POSTPUT で、ポストされた <form>enctype="multipart/form-data" を持つ場合のみデータを持ちます。そうでない場合は空です。

form

フォームのパラメータです。現状、この関数が返すディクショナリの中身がサブミットされたフォームデータと同じ順序かどうかは保証されていません。

classmethod from_values(*args, **kwargs)
提供された値をもとに、リクエストオブジェクトを新たに生成します。も し environ が与えられていれば、不足している値はそこから提供され ます。URL からのリクエストをシミュレートする必要がある場合、簡単な スクリプトを書くのにはこのメソッドは便利です。ただし、このメソッド をユニットテストには使用しないでください。フル機能のクライアントオ ブジェクト( Client )があり、マルチパートのリクエストの生成、 cookie のサポートなどが可能です。
headers
WSGI env 由来のヘッダです。変更不可の EnvironHeaders です。
host
ホストです。取得可能であればポートも含みます。
host_url
スキーム名つきのホストです。
if_match
If-Match ヘッダ中のすべてのetags を格納したオブジェクトです。
if_modified_since
パースされた If-Modified_Since ヘッダが datetime オブジェクトして格納されています。
if_none_match
If-None-Match ヘッダ中のすべてのetagsを格納したオブジェクトです。
if_unmodified_since
パースされた If-Unmodified_Since ヘッダが datetime オブジェクトして格納されています。
is_behind_proxy
HTTP プロキシの後ろでアプリケーションが起動している場合に True となります。
is_multiprocess
複数のプロセスを生成している WSGI サーバによってアプリケーションが提供されている場合に True となるブール値です。
is_multithread
マルチスレッドの WSGI サーバによってアプリケーションが提供されている場合に True となるブール値です。
is_run_once
アプリケーションがプロセスの生存期間中に一度だけ実行であろう場合は True になるブール値です。例えば CGI のような場合にあたりますが、一度だけ実行されることは保証されていません。
is_secure
セキュアなリクエストの場合 True となります。
is_xhr
リクエストが JavaScript XMLHttpRequest を介して発行された場合、 True になります。ライブラリが X-Requested-With ヘッダをサポートし、 XMLHttpRequest をセットしている場合のみ機能します。prototype, jQuery, Mochikitなどが上記をサポートしています。
lang
リクエストから Kay が推測した結果の使用言語が格納されています。
max_content_length
コンテント長の最大値です。この値はフォームデータをパースする関数( parse_form_data() )に渡されます。値がセットされていて、 formfile 属性にアクセスされ、指定した値を超える転送があってパースが失敗する場合、 RequestEntityTooLarge エクセプションがあがります。
max_form_memory_size
フォームフィールドの最大サイズです。この値はフォームデータをパースする関数( parse_form_data() )に渡されます。値がセットされていて、 formfile 属性にアクセスされ、ポストデータ用のメモリーデータが指定した値を超えると、 RequestEntityTooLarge エクセプションがあがります。
max_forwards
Max-Forwards リクエストヘッダフィールドは、 TRACE と OPTIONS メソッドに、リクエストを別のサーバへフォワードするプロキシやゲートウェイの数を制限する仕組みを提供します。
method
HTTPメソッドです。 GET POST などです。
mimetype
content-type と似ていますが、パラメータ(例:文字セット、型など)がありません。例えば、コンテントタイプが text/html; charset=utf-8 の場合、mimetypeは 'text/html' となります。
mimetype_params
mimetypeパラメータがディクショナリで格納されています。例えば、コンテントタイプが text/html; charset=utf-8 の場合、パラメータは {'charset': 'utf-8'} のようになっています。
path
リクエストされたパスがUnicodeで格納されます。WSGI env のパスと同じようなものですが、常にスラッシュが含まれます。ルートへの対するアクセスでも同様です。
pragma
Pragma ジェネラルヘッダフィールドは、リクエスト/レスポンス連鎖中のあらゆる受信者にも適用されるであろう実装の特別な指示を示すために使われます。全ての pragma 指示子は、プロトコルの視点から見ればオプショナルな振る舞いを指定しますが、その振る舞いが指示子と一致していることを要求するシステムがあるかもしれません。
query_string
URL パラメータです。バイトストリングで格納されています。
referrer
Referrer です。
remote_addr
クライアントのリモートアドレスです。
remote_user
ユーザ認証を有効にしている場合、ユーザ名が格納されます。
script_root
末尾のスラッシュを取り除いた、スクリプトのルートパスです。
session

セッションデータが格納されています。セッション機能を有効にすると使用できます。

shallow
リクエストがenvironのshallow copyである場合、 True が格納されています。
stream
もしサブミットされたデータがマルチパートでないか、 url エンコードされたフォームデータでない場合、パースされたストリームが格納されます。このストリームはフォームデータパーサモジュールがパース後に残したストリームです。これは、 WSGI インプットストリームそのものではなく、呼び出し元が Content-Length を読み込まない危険性を避けるため、ストリームのラッパを返します。
url
URL です。
url_charset
URL に使われる文字セットです。デフォルトは charset の値になっています。
url_root
ホストネームのついた完全な URL です。これはアプリケーションルートです。
user

ユーザ認証を有効にしている場合、 settings.pyAUTH_USER_MODEL で指定したユーザオブジェクトが格納されます。

user_agent
現在のユーザエージェントです。
values
args form 両方を結合したディクショナリと考えてください。

16.3. レスポンスオブジェクト

  • view は、必ずレスポンスオブジェクトを返す必要があります。
  • レスポンスオブジェクトはに対して、 freeze() を呼び出すと、pickleや、コピーができます。
  • copy.deepcopy によって、コピーを作成することはできません。

16.3.1. 属性とメソッド

レスポンスオブジェクトは以下の属性、および、メソッドを持っています。

class werkzeug.Response
add_etag(overwrite=False, weak=False)
現在のオブジェクトに etag を追加します。
age

Age レスポンスヘッダは、オリジンサーバにおいてレスポンス(または、その再検証が) が生成されてからの、送信者の推定経過時間を示します。

Age の値は、負値でない10進数の整数で、秒で時間を表します。

allow
Allow エンティティヘッダフィールドは、 Request-URI によって識別されたリソースによってサポートされているメソッドのセットを示します。このフィールドの目的は、リソースに関する有効なメソッドを受信者に厳密に知らせることです。Allow ヘッダは 405 (Method Not Allowed) レスポンス中に存在しなければなりません。
cache_control
Cache-Control ジェネラルヘッダフィールドは、リクエスト/レスポンス連鎖の間のすべてのキャッシングメカニズムが従わなければならない指示を記述するために使用されます。
charset
レスポンスの文字セットです。
close()
レスポンスオブジェクトを pickle する際に、呼び出します。
content_encoding
Content-Encoding エンティティヘッダフィールドは、メディアタイプの修飾子として使用されます。その値はどのコンテンツエンコーディングが追加で、エンティティボディに適用されているか、そしてその結果、 Content-Type ヘッダフィールドによって参照されるメディアタイプを取得するのためには、どのデコーディングメカニズムが適用されなければならないのかを示します。
content_language
Content-Language エンティティヘッダフィールドは、付随するエンティティの読者の自然言語を表します。ただし、エンティティボディで使われている言語全部とは一致しないかもしれないので気をつけてください。
content_length
Content-Length エンティティヘッダフィールドは、受信者に送信されるエンティティボディのサイズを8ビットの10進数で示します。HEAD メソッドの場合は GET リクエストされた場合に送信されるエンティティボディのサイズを示します。
content_location
Content-Location エンティティヘッダフィールドは、エンティティがリクエストされたリソースの URI とは別の場所から取得可能な場合に、そのメッセージに含まれるエンティティに対するリソースの場所を与えるために使うことができます。
content_md5
Content-MD5 エンティティヘッダフィールド (RFC 1864 に定義) は、エンティティボディのエンド・トゥ・エンドメッセージインテグリティチェック (MIC) を提供するためのエンティティボディの MD5 ダイジェストです。(注意: MIC は転送中のエンティティボディの偶発的な書き換えを発見するのには適していますが、悪意ある攻撃への対抗手段にはなりません)
content_type
Content-Type エンティティヘッダフィールドは、受信者に送信されるエンティティボディのメディアタイプを示します。HEAD メソッドの場合、GET リクエストされた場合に送信されるエンティティボディのメディアタイプを示します。
data
リクエスト本文の文字列を表します。この属性にアクセスするときはいつでもリクエストイテラブルはエンコードされフラット化されています。ストリームが巨大なデータである場合に、不測の振る舞いを引き起こす可能性があります。
date
Date ジェネラルヘッダフィールドは、メッセージが生成された日付と時間を表します。RFC 822の orig-date と同じセマンティクスをもっています。
default_mimetype
mimetype が設定されていない場合のデフォルトの mimetype です。
default_status
status が設定されていない場合のデフォルトの status です。

cookie を削除します。キーがない場合は、フェールサイレントです。

パラメタ:
  • key – 削除される cookie のキー(名称)です。
  • path – もし削除されるべき cookie があるパスに限定されている場合、そのパスを指定しなければなりません。
  • domain – もし削除されるべき cookie があるドメインに限定されている場合、そのドメインを指定しなければなりません。
direct_passthrough
もし、レスポンスオブジェクトが WSGI アプリケーションとして使用される前に direct_passthrough=True がレスポンスオブジェクトに渡されるか、あるいは、この属性が True にセットされるかした場合、ラップされたイテレータは変更なしで返されます。これによって、特別な wsgi.file_wrapper をレスポンスオブジェクトに渡すことができます。詳しくは wrap_file() を参照してください。
expires
Expire エンティティヘッダフィールドはレスポンスが古くなると見なされる時点の日付と時間を表します。通常、キャッシュは、古いキャッシュエントリを返さないでしょう。
fix_headers(environ)

レスポンスの開始の直前に自動的に呼び出され、ヘッダのよくある間違いを修正します。例えば、ロケーションヘッダはルートURLと結合されます。

Parameter:envirion – 修正の適用に使われるリクエストのWSGI env
classmethod force_type(response, environ=None)

WSGI レスポンスが現在の型のレスポンスオブジェクトであることを強制します。Werkzeug はエクセプションのような多くのシチュエーションで内部的には BaseResponse を使います。もしエクセプションに get_response を呼ぶのであれば、たとえ、カスタムサブクラスを使っていたとしても、通常の BaseResponse オブジェクトを返されるでしょう。

このメソッドは与えられるレスポンスの型を強制できます。また、 envrion が与えると、WSGI 呼び出し可能オブジェクトを任意のレスポンスオブジェクトにコンバートします。

これは、メインディスパッチャでレスポンスをポストプロセスし、サブクラスによって提供される機能を使いたい場合に特に有用です。

可能な限り適切にレスポンスオブジェクトを変更することを覚えておいてください。

パラメタ:
  • response – レスポンスオブジェクト、または、WSGI アプリケーション
  • environ – WSGI env オブジェクト
classmethod from_app(app, environ, buffered=False)

アプリケーションの出力から新しいレスポンスオブジェクトを作成します。これは、常にジェネレータを返すアプリケーションで呼び出すとうまくいきます。アプリケーションは start_response 関数が返す write() 呼び出し可能オブジェクトを使うかもしれません。このメソッドはそのようなケースを自動的に解決しようとします。しかし、期待した出力を得られない場合は、 bufferedTrue をセットしバッファリングを強制すべきです。

パラメタ:
  • app – 実行される WSGI アプリケーションです。
  • environ – 再実行される WSGI env です。
  • buffered – バッファリングを強制するには True をセットします。
戻り値の型:

レスポンスオブジェクト

get_app_iter(environ)

与えられた environ に対するアプリケーションイテレータを返します。リクエストメソッドと現在のステータスコード次第で、戻り値は空のレスポンスになるでしょう。

もし、リクエストメソッドが HEAD であるか、または、ステータスコードが HTTP の仕様が空のレスポンスを要求する範囲である場合は、空のイテラブルが返されます。

Parameter:environ – リクエストの WSGI env です。
戻り値の型:レスポンスイテラブルです。
get_etag()
(etag, is_weak) の形式のタプルを返します。 ETag がない場合は、戻り値は (None, None) です。
get_wsgi_headers(environ)

このメソッドは、レスポンスが開始される直前に自動的に呼び出され、与えられた環境用に修正したヘッダを返します。必要であれば、いくつかの修正を適用してレスポンスからヘッダのコピーを返します。

例えば、ロケーションヘッダ(もしあれば)は環境のルートURLと結合されます。また、ステータスコードによってはコンテンツ長は自動的に0がセットされます。

Parameter:envrion – リクエストの WSGI env です。
戻り値の型:新しいヘッダオブジェクトを返します。
get_wsgi_response(environ)

最終的な WSGI レスポンスをタプルで返します。タプルの最初の項目はアプリケーションイテレータです。2番目はステータスで、3番目はリストのヘッダです。返されたレスポンスは与えられた環境向けに作られます。例えば、 WSGI envのリクエストメソッドが HEAD である場合、レスポンスは空になり、ヘッダとステータスコードだけがあるでしょう。

Parameter:environ – リクエストの WSGI env です。
戻り値の型:アプリケーションイテレータ、ステータス、ヘッダのタプルです。
headers
レスポンスヘッダを表す Headers オブジェクトです。
is_streamed
もし、レスポンスがストリームの場合(レスポンスが長さの情報をもったイテラブルでない場合)、この属性は True になります。この場合、streamd はイテレーションの数についての情報を持たないということを意味します。ジェネレータがレスポンスオブジェクトに引き継がれる場合、通常 True になります。
iter_encoded(charset=None)
指定されたエンコーディングでエンコードされたレスポンスのイテレータを返します。エンコーディングが指定されていない場合、クラスのエンコーディングが使われます。バイトストリングデータはエンコードされないことに注意してください。もしレスポンスオブジェクトが WSGI アプリケーションとして呼び出される場合、このメソッドの戻り値は direct_passthrough が有効な場合をのぞき、アプリケーションイテレータとして使用されます。
last_modified
Last-Modified エンティティヘッダフィールドは、オリジンサーバーがバリアントが最後に更新されたと考える日付と時間を表します。
location
Location レスポンスヘッダフィールドは、リクエストの完了、または、新しいリソースの識別のために、受信者を Request-URI 以外の場所にリダイレクトするのに使われます。
make_conditional(request_or_envrion)

リクエストに対するレスポンスコンディショナルを生成します。このメソッドはレスポンス用の etag が既に定義されている場合に機能します。 add_etag メソッドを使って etag を追加できます。 etag なしで呼び出された場合、date ヘッダをセットするだけです。

このメソッドは、リクエストか envrion 中のリクエストメソッドが GETHEAD 以外の場合、何もしません。

return resp.make_conditional(req) と書くと自分自身を返しますが、配置済みのオブジェクトは書き換えられます。

Parameter:request_or_environ – レスポンスコンディショナルを再度作成するのに使うリクエストオブジェクトか WSGI env。
mimetype
content-type と似ていますが、パラメータ(例:文字セット、型など)がありません。例えばコンテントタイプが text/html; charset=utf-8 の場合 mimetype は 'text/html' となります。
mimetype_params
mimetype パラメータがディクショナリで格納されています。例えば、コンテントタイプが text/html; charset=utf-8 の場合、パラメータは {'charset': 'utf-8'} のようになっています。
response
アプリケーションイテレータです。文字列で構成されていればリストになり、それ以外では、アプリケーションイテレータとして提供されます。
retry_after
Retry-After レスポンスヘッダフィールドは、リクエストしているクライアントにサービスがどのくらいの時間利用できないかを示すために 503 (Service Unavailable) レスポンスとともに使われます。

cookie をセットします。パラメータは、Python スタンダードライブラリの cookie Morsel オブジェクトと同じですが、 unicode のデータも可です。

パラメタ:
  • key – セットされる cookie のキーです。
  • value – cookie の値です。
  • max_age – 秒数で指定します。cookie の保存期間がクライアントのブラウザセッションと同じでよければ None (デフォルト値) にします。
  • domain – クロスドメインcookieをセットしたい場合に使います。例えば、 domain=".exmaple.com" だと、 “www.example.com” と “foo.example.com” ドメインから読み込める cookie がセットされます。指定がなければ、セットしたドメインからのみ読み込める cookie がセットされます。
  • path – cookie のパスを制限します。デフォルトではドメイン全体です。
set_etag(etag, weak=False)
etag をセットします。もし、古いのがあれば上書きします。
status
文字列のステータスか、整数値のステータスコードを渡します。
status_code
レスポンスステータスです。整数値です。
stream
書き込み専用のレスポンスイテラブルです。
vary
Vary フィールドは、レスポンスが新しいものである間、キャッシュがそのレスポンスをリヴァリデーションなしに後続のリクエストへの応答に使うことを許可されているか否かを完全に決定するリクエストヘッダフィールドの集合を示します。
www_authenticate
パースされたフォームの www-authenticate ヘッダです。

16.3.2. 生成方法

レスポンスオブジェクトは、 werkzeug.Response クラスのインスタンスです。Kay には、レスポンスを生成するための関数が用意されています。 kay.utils.render_to_response()

16.3.3. HTTP エラー

:mod:werkzeug.exceptions には沢山の例外が定義されています。これらのクラス名は HTTP エラーの種類を表しています。HTTP エラーを返したい場合は、これらの例外を raise してください。

HTTP エラーのリストです。

class werkzeug.exceptions.HTTPException
class werkzeug.exceptions.BadRequest
class werkzeug.exceptions.Unauthorized
class werkzeug.exceptions.Forbidden
class werkzeug.exceptions.NotFound
class werkzeug.exceptions.MethodNotAllowed
class werkzeug.exceptions.NotAcceptable
class werkzeug.exceptions.RequestTimeout
class werkzeug.exceptions.Gone
class werkzeug.exceptions.LengthRequired
class werkzeug.exceptions.PreconditionFailed
class werkzeug.exceptions.RequestEntityTooLarge
class werkzeug.exceptions.RequestURITooLarge
class werkzeug.exceptions.UnsupportedMediaType
class werkzeug.exceptions.InternalServerError
class werkzeug.exceptions.NotImplemented
class werkzeug.exceptions.BadGateway
class werkzeug.exceptions.ServiceUnavailable