ゲートウェイインタフェース規格 (CGI) に準拠したスクリプトをサポートするためのモジュールです。
このモジュールでは、 Python で CGI スクリプトを書く際に使える様々なユーティリティを定義しています。
CGI スクリプトは、HTTP サーバによって起動され、通常は HTML の <FORM> または <ISINDEX> エレメントを 通じてユーザが入力した内容を処理します。
ほとんどの場合、CGI スクリプトはサーバ上の特殊なディレクトリ cgi-bin の下に置きます。HTTP サーバは、まずスクリプトを 駆動するためのシェルの環境変数に、リクエストの全ての情報 (クライアントのホスト名、リクエストされている URL、クエリ文字列、その他諸々) を設定し、スクリプトを実行した後、スクリプトの出力をクライアントに送信します。
スクリプトの入力端もクライアントに接続されていて、この経路を通じてフォームデータを読み込むこともあります。それ以外の場合には、フォームデータは URL の一部分である「クエリ文字列」を介して渡されます。このモジュールでは、上記のケースの違いに注意しつつ、 Python スクリプトに対しては単純なインタフェースを提供しています。このモジュールではまた、スクリプトをデバッグするための ユーティリティも多数提供しています。また、最近はフォームを経由したファイルのアップロードをサポートしています (ブラウザ側がサポートしていればです)。
CGI スクリプトの出力は 2 つのセクションからなり、空行で分割されています。最初のセクションは複数のヘッダからなり、 後続するデータがどのようなものかをクライアントに通知します。最小のヘッダセクションを生成するための Python のコードは以下のようなものです:
print "Content-Type: text/html" # 以降のデータが HTML であることを示す行
print # ヘッダ部の終了を示す空行
二つ目のセクションは通常、ヘッダやインラインイメージ等の付属したテキストをうまくフォーマットして表示できるようにした HTML です。以下に単純な HTML を出力する Python コードを示します:
print "<TITLE>CGI script output</TITLE>"
print "<H1>This is my first CGI script</H1>"
print "Hello, world!"
先頭には import cgi と書いてください。 from cgi import * と書いてはなりません — このモジュールでは、以前のバージョンとの互換性を持たせるため、内部で呼び出す名前を多数定義しており、それらをユーザの名前空間に存在させる必要はないからです。
新たにスクリプトを書く際には、以下の行を付加するかどうか検討してください:
import cgitb
cgitb.enable()
これによって、特別な例外処理が有効にされ、エラーが発生した際にブラウザ上に詳細なレポートを出力するようになります。ユーザにスクリプトの内部を 見せたくないのなら、以下のようにしてレポートをファイルに保存できます:
import cgitb
cgitb.enable(display=0, logdir="/tmp")
スクリプトを開発する際には、この機能はとても役に立ちます。 cgitb が生成する報告はバグを追跡するためにかかる 時間を大幅に減らせるような情報を提供してくれます。スクリプトをテストし終わり、正確に動作することを確認したら、いつでも cgitb の行を削除できます。
入力されたフォームデータを取得するには、 FieldStorage クラス を使うのが最良の方法です。このモジュールで定義されている他のクラスのほとんどは以前のバージョンとの互換性のためのものです。インスタンス生成は引数なしで必ず 1 度だけ行います。これにより、標準入力または環境変数からフォームの内容を読み出します (どちらから読み出すかは、複数の環境変数の値が CGI 標準に従って どう設定されているかで決まります)。インスタンスが標準入力を使うかもしれないので、インスタンス生成を行うのは一度だけにしなければなりません。
FieldStorage のインスタンスは Python の辞書のようにインデクスを使って参照でき、標準の辞書に対するメソッド has_key() と keys() をサポートしています。組み込みの関数 len() もサポートしています。空の文字列を含むフォームのフィールドは無視され、辞書には入りません; そういった値を保持するには、 FieldStorage のインスタンスを生成する時にオプションの keep_blank_values キーワード引数を true に設定してください。
例えば、以下のコード (Content-Type ヘッダと空行はすでに出力された後とします) は name および addr フィールドが両方とも空の文字列に設定されていないか調べます:
form = cgi.FieldStorage()
if not (form.has_key("name") and form.has_key("addr")):
print "<H1>Error</H1>"
print "Please fill in the name and addr fields."
return
print "<p>name:", form["name"].value
print "<p>addr:", form["addr"].value
...further form processing here...
ここで、 form[key] で参照される各フィールドはそれ自体が FieldStorage (または MiniFieldStorage 。フォームのエンコードによって変わります) のインスタンスです。インスタンスの属性 value の内容は対応するフィールドの値で、文字列になります。 getvalue() メソッドはこの文字列値を直接返します。 getvalue() の 2 つめの引数にオプションの値を与えると、リクエストされたキーが存在しない場合に返すデフォルトの値になります。
入力されたフォームデータに同じ名前のフィールドが二つ以上あれば、 form[key] で得られるオブジェクトは FieldStorage や MiniFieldStorage のインスタンスではなく、そうしたインスタンスの リストになります。この場合、 form.getvalue(key) も同様に、文字列からなるリストを返します。もしこうした状況が起きうると思うなら (HTML のフォームに同じ名前をもったフィールドが複数含まれているのなら) 、組み込み関数 isinstance() を使って、返された値が単一のインスタンスかインスタンスのリストかどうか調べてください。例えば、以下のコードは任意の数のユーザ名フィールドを 結合し、コンマで分割された文字列にします:
value = form.getvalue("username", "")
if isinstance(value, list):
# Multiple username fields specified
usernames = ",".join(value)
else:
# Single or no username field specified
usernames = value
フィールドがアップロードされたファイルを表している場合、 value 属性や getvalue() メソッドを使ってフィールドの値にアクセスすると、ファイルの内容を全て文字列としてメモリ上に読み込んでしまいます。 これは望ましくない機能かもしれません。アップロードされたファイルがあるかどうかは filename 属性および file 属性のいずれかで調べられます。その後、以下のようにして file 属性から落ち着いてデータを読み出せます:
fileitem = form["userfile"]
if fileitem.file:
# It's an uploaded file; count lines
linecount = 0
while 1:
line = fileitem.file.readline()
if not line: break
linecount = linecount + 1
アップロードされたファイルの内容を取得している間にエラーが発生した場合 (例えば、ユーザーがバックやキャンセルボタンでsubmitを中断した場合)、 そのフィールドのオブジェクトの done 属性には -1 が設定されます。
現在ドラフトとなっているファイルアップロードの標準仕様では、一つのフィールドから (再帰的な multipart/* エンコーディングを使って) 複数のファイルがアップロードされる可能性を受け入れています。この場合、アイテムは辞書形式の FieldStorage アイテムとなります。複数ファイルかどうかは type 属性が multipart/form-data (または multipart/* にマッチする他の MIME 型) になっているかどうかを調べれば判別できます。この場合、トップレベルのフォームオブジェクトと同様にして再帰的に個別処理できます。
フォームが「古い」形式で入力された場合 (クエリ文字列または単一の:mimetype:application/x-www-form- urlencoded データで入力された場合)、データ要素の実体は MiniFieldStorage クラスの インスタンスになります。この場合、 list 、 file 、および filename 属性は常に None になります。
フォームがPOSTによって送信され、クエリー文字列も持っていた場合、 FieldStorage と MiniFieldStorage の両方が含まれます。
バージョン 2.2 で追加.
前節では CGI フォームデータを FieldStorage クラスを使って読み出す方法について解説しました。この節では、フォームデータを 分かりやすく直感的な方法で読み出せるようにするために追加された、より高水準のインタフェースについて記述します。 このインタフェースは前節で説明した技術を撤廃するものではありません — 例えば、前節の技術は依然としてファイルのアップロードを効率的に行う上で便利です。
このインタフェースは 2 つの単純なメソッドからなります。このメソッドを使えば、一般的な方法でフォームデータを処理でき、ある名前のフィールドに 入力された値が一つなのかそれ以上なのかを心配する必要がなくなります。
前節では、一つのフィールド名に対して二つ以上の値が入力されるかもしれない場合には、常に以下のようなコードを書くよう学びました:
item = form.getvalue("item")
if isinstance(item, list):
# The user is requesting more than one item.
else:
# The user is requesting only one item.
こういった状況は、例えば以下のように、同じ名前を持った複数のチェックボックスからなるグループがフォームに入っているような場合によく起きます:
<input type="checkbox" name="item" value="1" />
<input type="checkbox" name="item" value="2" />
しかしながら、ほとんどの場合、あるフォーム中で特定の名前を持ったコントロールはただ一つしかないので、その名前に関連付けられた値は ただ一つしかないはずだと考えるでしょう。そこで、スクリプトには例えば以下のようなコードを書くでしょう:
user = form.getvalue("user").upper()
このコードの問題点は、クライアント側がスクリプトにとって常に有効な入力を提供するとは期待できないところにあります。例えば、もし好奇心旺盛なユーザがもう一つの user=foo ペアをクエリ文字列に追加したら、 getvalue('user') メソッドは 文字列ではなくリストを返すため、このスクリプトはクラッシュするでしょう。リストに対して upper() メソッドを呼び出すと、引数が 有効でない (リスト型はその名前のメソッドを持っていない) ため、例外 AttributeError を送出します。
従って、フォームデータの値を読み出しには、得られた値が単一の値なのか値のリストなのかを常に調べるコードを使うのが適切 でした。これでは煩わしく、より読みにくいスクリプトになってしまいます。
ここで述べる高水準のインタフェースで提供している getfirst() や getlist() メソッドを使うと、もっと便利にアプローチできます。
フォームフィールド name に関連付けられた値をつねに一つだけ返す軽量メソッドです。同じ名前で 1 つ以上の値がポストされている場合、 このメソッドは最初の値だけを返します。フォームから値を受信する際の値の並び順はブラウザ間で異なる可能性があり、特定の順番であるとは 期待できないので注意してください。 [1]
指定したフォームフィールドや値がない場合、このメソッドはオプションの引数 default を返します。このパラメタを指定しない場合、標準の値は None に設定されます。
このメソッドはフォームフィールド name に関連付けられた値を常にリストにして返します。 name に指定したフォームフィールドや値が 存在しない場合、このメソッドは空のリストを返します。値が一つだけ存在する場合、要素を一つだけ含むリストを返します。
これらのメソッドを使うことで、以下のようにナイスでコンパクトにコードを書けます:
import cgi
form = cgi.FieldStorage()
user = form.getfirst("user", "").upper() # This way it's safe.
for item in form.getlist("item"):
do_something(item)
バージョン 2.6 で撤廃: これらのクラスは、 cgi モジュールの以前のバージョンに入っており、以前のバージョンとの互換性のために現在もサポートされています。 新しいアプリケーションでは FieldStorage クラスを使うべきです。
SvFormContentDict は単一の値しか持たないフォームデータの内容を辞書として記憶します; このクラスでは、各フィールド名はフォーム中に一度しか現れないと仮定しています。
FormContentDict は複数の値を持つフォームデータの内容を辞書として記憶します (フォーム要素は値のリストです); フォームが同じ名前を持ったフィールドを複数含む場合に便利です。
他のクラス (FormContent 、 InterpFormContentDict) は 非常に古いアプリケーションとの後方互換性のために存在します。
+.. _functions-in-cgi-module:
より細かく CGI をコントロールしたり、このモジュールで実装されているアルゴリズムを他の状況で利用したい場合には、以下の関数が便利です。
環境変数、またはファイルからからクエリを解釈します (ファイルは標準で sys.stdin になります) keep_blank_values および strict_parsing パラメタはそのまま urlparse.parse_qs() に渡されます。
この関数はこのモジュールでは廃止予定です。 代わりに urlparse.parse_qs() を利用してください。 この関数は後方互換性のためだけに残されています。
この関数はこのモジュールでは廃止予定です。 代わりに urlparse.parse_qsl() を利用してください。 この関数は後方互換性のためだけに残されています。
(ファイル入力のための) multipart/form-data 型の入力を解釈します。引数は入力ファイルを示す fp と Content-Type ヘッダ内の他のパラメタを含む辞書 pdict です。
urlparse.parse_qs() と同じく辞書を返します。辞書のキーはフィールド名で、対応する値は各フィールドの値でできたリストです。 この関数は簡単に使えますが、数メガバイトのデータがアップロードされると考えられる場合にはあまり適していません — その場合、より柔軟性のある FieldStorage を代りに使ってください。
マルチパートデータがネストしている場合、各パートを解釈できないので注意してください — 代りに FieldStorage を使ってください。
(Content-Type のような) MIME ヘッダを解釈し、ヘッダの主要値と各パラメタからなる辞書にします。
メインプログラムから利用できる堅牢性テストを行う CGI スクリプトです。最小の HTTP ヘッダと、HTML フォームからスクリプトに供給された全ての 情報を書式化して出力します。
シェル変数を HTML に書式化して出力します。
フォームを HTML に初期化して出力します。
現在のディレクトリを HTML に書式化して出力します。 Format the current directory in HTML.
意味のある (CGI の使う) 環境変数を HTML で出力します。
文字列 s 中の文字 '&' 、 '<' 、および '>' を HTML で正しく表示できる文字列に変換します。 それらの文字が中に入っているかもしれないようなテキストを出力する必要があるときに使ってください。オプションの引数 quote の値が真であれば、二重引用符文字 ('"') も変換します; この機能は、例えば <A HREF="..."> といったような HTML の属性値を出力に含めるのに役立ちます。クオートされる値が単引用符か二重引用符、またはその両方を含む可能性がある場合は、代りに xml.sax.saxutils の quoteattr() 関数を検討してください。
重要なルールが一つあります: ( 関数 os.system() または os.popen() 、またはその他の同様の機能によって ) 外部プログラムを呼び出すなら、クライアントから受信した任意の文字列をシェルに渡していないことをよく確かめてください。 これはよく知られているセキュリティホールであり、これによって Web のどこかにいる悪賢いハッカーが、だまされやすい CGI スクリプトに任意の シェルコマンドを実行させてしまえます。URL の一部やフィールド名でさえも信用してはいけません。CGI へのリクエストは あなたの作ったフォームから送信されるとは限らないからです!
安全な方法をとるために、フォームから入力された文字をシェルに渡す場合、文字列に入っているのが英数文字、ダッシュ、アンダースコア、 およびピリオドだけかどうかを確認してください。
あなたの使っている HTTP サーバのドキュメントを読んでください。そしてローカルシステムの管理者と一緒にどのディレクトリに CGI スクリプト をインストールすべきかを調べてください; 通常これはサーバのファイルシステムツリー内の cgi-bin ディレクトリです。
あなたのスクリプトが “others” によって読み取り可能および実行可能であることを確認してください; Unix ファイルモードは 8 進表記で 0755 です (chmod 0755 filename を使ってください)。スクリプトの最初の行の 1 カラム目が、 #! で開始し、その後に Python インタプリタへのパス名が続いていることを確認してください。例えば:
#!/usr/local/bin/python
Python インタプリタが存在し、”others” によって実行可能であることを確かめてください。
あなたのスクリプトが読み書きしなければならないファイルが全て “others” によって読み出しや書き込み可能であることを確かめてください — 読み出し可能のファイルモードは 0644 で、書き込み可能のファイルモードは 0666 になるはずです。これは、セキュリティ上の理由から、 HTTP サーバがあなたのスクリプトを特権を全く持たないユーザ “nobody” の権限で実行するからです。この権限下では、誰でもが読める (書ける、実行できる) ファイルしか読み出し (書き込み、実行) できません。スクリプト実行時のディレクトリや環境変数のセットもあなたがログイン したときの設定と異なります。特に、実行ファイルに対するシェルの検索パス (PATH) や Python のモジュール検索パス (PYTHONPATH)が何らかの値に設定されていると期待してはいけません。
モジュールを Python の標準設定におけるモジュール検索パス上にないディレクトリからロードする必要がある場合、他のモジュールを取り込む 前にスクリプト内で検索パスを変更できます。例えば:
import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")
(この方法では、最後に挿入されたディレクトリが最初に検索されます!)
非 Unix システムにおける説明は変わるでしょう; あなたの使っている HTTP サーバのドキュメントを調べてください (普通は CGI スクリプトに 関する節があります)。
残念ながら、 CGI スクリプトは普通、コマンドラインから起動しようとしても動きません。また、コマンドラインから起動した場合には完璧に 動作するスクリプトが、不思議なことにサーバからの起動では失敗することがあります。しかし、スクリプトをコマンドラインから実行してみなければ ならない理由が一つあります: もしスクリプトが文法エラーを含んでいれば、Python インタプリタはそのプログラムを全く実行しないため、 HTTP サーバはほとんどの場合クライアントに謎めいたエラーを送信するからです。
スクリプトが構文エラーを含まないのにうまく動作しないなら、次の節に読み進むしかありません。
何よりもまず、些細なインストール関連のエラーでないか確認してください — 上の CGI スクリプトのインストールに関する節を注意深く読めば 時間を大いに節約できます。もしインストールの手続きを正しく理解しているか不安なら、このモジュールのファイル (cgi.py) をコピーして、CGI スクリプトとしてインストールしてみてください。このファイルはスクリプトとして呼び出すと、スクリプトの実行環境とフォームの内容を HTML フォームに出力します。正しいモードなどをフォームに与えて、リクエストを送ってみてください。標準的な cgi-bin ディレクトリにインストールされていれば、以下のような URL をブラウザに入力してリクエストを送信できるはずです:
http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
もしタイプ 404 のエラーになるなら、サーバはスクリプトを発見できないでいます – おそらくあなたはスクリプトを別のディレクトリ に入れる必要があるのでしょう。他のエラーになるなら、先に進む前に解決しなければならないインストール上の問題があります。もし実行環境の情報とフォーム内容 (この例では、各フィールドはフィールド名 “addr” に対して値 “At Home”、およびフィールド名 “name” に対して “Joe Blow” ) が綺麗にフォーマットされて表示されるなら、 cgi.py スクリプトは正しくインストールされています。 同じ操作をあなたの自作スクリプトに対して行えば、スクリプトをデバッグできるようになるはずです。
次のステップでは cgi モジュールの test() 関数を呼び出すことになります: メインプログラムコードを以下の 1 行、
cgi.test()
と置き換えてください。この操作で cgi.py ファイル自体をインストールした時と同じ結果を出力するはずです。
通常の Python スクリプトが例外を処理しきれずに送出した場合 (様々な理由: モジュール名のタイプミス、ファイルが開けなかった、など)、 Python インタプリタはナイスなトレースバックを出力して終了します。 Python インタプリタはあなたの CGI スクリプトが例外を送出した場合 にも同様に振舞うので、トレースバックは大抵HTTP サーバのいずれかのログファイルに残るかまったく無視されるかです。
幸運なことに、あなたが自作のスクリプトで 何らかの コードを実行できるようになったら、 cgitb モジュールを使って 簡単にトレースバックをブラウザに送信できます。まだそうでないなら、以下の2行:
import cgitb;
cgitb.enable()
をスクリプトの先頭に追加してください。そしてスクリプトを再度走らせます; 問題が発生すれば、クラッシュの原因を見出せるような詳細な報告を読めます。
cgitb モジュールのインポートに問題がありそうだと思うなら、(組み込みモジュールだけを使った) もっと堅牢なアプローチを取れます:
import sys
sys.stderr = sys.stdout
print "Content-Type: text/plain"
print
...your code here...
このコードは Python インタプリタがトレースバックを出力することに依存しています。出力のコンテント型はプレーンテキストに設定されており、全ての HTML 処理を無効にしています。スクリプトがうまく動作する場合、生の HTML コードがクライアントに表示されます。スクリプトが例外を送出する場合、最初の 2 行が出力された後、トレースバックが表示されます。HTML の解釈は行われないので、トレースバックを読めるはずです。
Footnotes
[1] | 最近のバージョンの HTML 仕様ではフィールドの値を供給する順番を取り決めてはいますが、ある HTTP リクエストがその取り決めに 準拠したブラウザから受信したものかどうか、そもそもブラウザから送信されたものかどうかの判別は退屈で間違いやすいので注意してください。 |