4.9 `psp` - Python Server Pages

psp モジュールでは、特別なブラケット表記中に Python コードを埋め込んだテキストドキュメント (HTMLも含みますが、それだけではありません) を変換して、 mod_python ハンドラ内で実行できるような適切な形式の pure Python コードにします。これにより、ASP や JSP などといった動的なコンテンツを配信するための融通のきくメカニズムを実現しています。

psp の使っているパーザは (flex で生成した) C で書かれているため、非常に高速に動作します。

PSP の詳細については6.2 節「PSP ハンドラ」を参照してください。

ドキュメント中の Python のコード (code) は"<%" と "%>"で囲わねばなりません。Python の式 (expression) は"<%=" と "%>" で囲みます。ディレクティブ (directive) は"<%@"と "%>" で囲みます。コメント(処理後のコード中には入りません) は "<%--" と "--%>" で囲います。

コードと式の両方をを HTML ドキュメントに埋め込んでいる簡単な PSP ページを以下に示します:

  <html>
  <%
  import time
  %>
  Hello world, the time is: <%=time.strftime("%Y-%m-%d, %H:%M:%S")%>
  </html>

内部では、PSP パーザが上のページを以下の Python コードに翻訳します:

  req.write("""<html>
  """)
  import time
  req.write("""
  Hello world, the time is: """); req.write(str(time.strftime("%Y-%m-%d, %H:%M:%S"))); req.write("""
  </html>
  """)

このコードをハンドラ内で実行すると、"Hello world, the time is:" の後ろに現在の時刻が入ったページになります。

Python コードを使って、条件やループでページの一部分を表示できます。 Python コード内のブロックはインデントで表現されます。ある Python コードブロックの最後の行のインデントは (コメント文であっても) ドキュメントの末尾か、次の Python コードブロックまで持続します。

例を示します:

  <html>
  <%
  for n in range(3):
      # This indent will persist
  %>
  <p>This paragraph will be 
  repeated 3 times.</p>
  <%
  # This line will cause the block to end
  %>
  This line will only be shown once.<br>
  </html>

上の例は、内部的には以下の Python コードになります:

  req.write("""<html>
  """)
  for n in range(3):
      # This indent will persist
      req.write("""
  <p>This paragraph will be
  repeated 3 times.</p>
  """)
  # This line will cause the block to end
  req.write("""
  This line will only be shown once.<br>
  </html>
  """)

パーザは賢くて、Python コードブロックの最後の行が ":" (コロン) で終っている場合にも正しくインデントを推測します。このことと、 "<% %>" の中で改行に到達するとインデントはリセットされることを考慮すると、上のページは以下のようにも書けます:

  <html>
  <%
  for n in range(3):
  %>
  <p>This paragraph will be 
  repeated 3 times.</p>
  <%
  %>
  This line will only be shown once.<br>
  </html>

とはいえ、このコードには困惑させられるでしょう。ですから、行儀として、ブロック間で説明用のコメントを入れておくよう強く勧めます。

現時点でサポートしているディレクティブは include だけで、以下のようにして使います:

<%@ include file="/file/to/include"%>

parse() 関数を dir 引数つきで呼び出す場合には、 "file" は相対パスで指定できます。それ以外の場合には絶対パスでなければなりません。

クラス PSP( req, [, filename, string, vars])

PSP オブジェクトを表すクラスです。

req はリクエストオブジェクトです; filename およびstring はオプションのキーワード引数で、 PSP コードのソースを表します。これらの変数はいずれか一つだけを指定できます。両方とも指定しなかった場合、 filename にreq.filename を使います。

vars はグローバル変数の辞書です。run() メソッドに変数を渡すと、ここで渡したvars の内容をオーバライドします。

このクラスは PSP ハンドラが内部で利用しますが、汎用のテンプレートツールとしても使えます。

ファイルをソースに使う場合、特定のファイルから得られるコードオブジェクトはファイル名と更新時刻をキーにしてメモリキャッシュ上に保存されます。キャッシュは Python インタプリタ上のグローバルな値です。従って、ファイル更新時刻が変わらない限り、ファイルのパーズとコードオブジェクトのコンパイルはインタプリタごとに一度しか行いません。

キャッシュされたページのサイズが時としてかなりのメモリを消費することがあるため、キャッシュのサイズは 512 ページに制限されています。メモリの消費量が問題になる場合は dbm によるファイルキャッシュに切替えられます。bsd db を使った簡単なテストでは、速度はわずか 20% しか低下しませんでした。dbm ライブラリによってはレコードエントリのサイズに制限を課しているために利用できないことがあります。そのため、自分のシステムでの anydbmのデフォルトの実装が何かを調べておく必要があるでしょう。 dbm によるキャッシュは"PythonOption"ディレクティブに PSPDbmCache を指定して有効にします:

PythonOption PSPDbmCache ``/tmp/pspcache.dbm''

dbm キャッシュファイルはサーバの再起動時に削除されないので注意してください。

ファイルと違い、文字列から生成したコードオブジェクトはメモリ上にしかキャッシュされません。現時点では、dbm ファイル上にキャッシュするという選択肢はありません。

run( [vars])

このメソッドは(初期化時にPSPソースを解析／コンパイルしてできた)コードを実行します。オプションの引数 vars は文字列をキーにした辞書で、グローバル変数の辞書として渡されます。

さらに、PSP コードには req, psp, session および form といったグローバル変数が渡されます。コード中でsession を参照している場合に限り、セッション情報が生成され、変数session に代入されます (PSP ハンドラはコードオブジェクトの co_names を調べてsession への参照の有無を判定します)。 session を一度でも参照すると、好むと好まざるとにかかわらず session はクッキーを生成してセッションのロックを開始するということを覚えておいてください。同様に、form がコード中で参照されていると、mod_python クラスの FieldStorage オブジェクトがインスタンス化されます。

psp には PSPInstance のインスタンスが渡されます。

display_code( ): 元の PSP コードと PSP パーザが生成した Python コードのリストを横に並べたような形に HTML でフォーマットし、文字列にして返します。

PSP をテンプレートメカニズムとして使う例を以下に示します:

テンプレートファイルは以下のようになります:

<html>
  <!-- This is a simple psp template called template.html -->
  <h1>Hello, <%=what%>!</h1>
</html>

ハンドラコードは以下のようになります:

from mod_python import apache, psp

def handler(req):
    template = psp.PSP(req, filename='template.html')
    template.run({'what':'world'})
    return apache.OK

クラス PSPInstance( )

グローバル変数 psp として PSP コードに渡されるオブジェクトのクラスです。このクラスのインスタンスは内部的にインスタンス化されることになっています。__init__ のインタフェースはわざとドキュメント化していません。

set_error_page( filename): 例外が生じたときに処理される psp ページを設定するために使います。 filename が絶対パス表記の場合、ドキュメントルートの後ろに追加されます。それ以外の場合は現在のページと同じディレクトリにあるものとみなします。エラーページはsys.exc_info() の返す三要素のタプルを引数exception で受け取ります。

apply_data( object[, **kw]): このメソッドはフォームデータをキーワード引数にして呼び出し可能オブジェクト object を呼び出し、その結果を返します。

redirect( location[, permanent=0])

このメソッドはブラウザをlocation にリダイレクトさせます。permanent が真の場合、MOVED_PERMANENTLY を送信します(そうでない場合にはMOVED_TEMPORARILY を送信します)。

注意: リダイレクトを起こせるのはクライアントにデータを送信する前だけです。従って、このメソッドを呼び出す Python コードブロックはページの先頭になければなりません。そうでない場合、IOError が送出されます。

例:

<%

# note that the '<' above is the first byte of the page!
psp.redirect('http://www.modpython.org')
%>

この他に、 psp では以下の低水準関数を提供しています:

parse( filename[, dir])

この関数はfilename という名前のファイルを開き、内容を読み出して解析し、得られた Python コードの入った文字列を返します。

dir を指定すると、解析対象となるファイルの完全な名前を dir とfilename を使って決め、include ディレクティブの引数を相対パスとして指定できるようになります。(ファイル名は単に二つの変数をつなげて作成するため、dir の末尾にパス区切り文字が入っていなくても補完されないので注意してください)。

parsestring( string)

この関数は string の内容を解析し、得られた Python コードを文字列で返します。

4.9 psp - Python Server Pages

4.9 `psp` - Python Server Pages