4.5.3.1 メソッド

add_common_vars( ): Apache の ap_add_common_vars() 関数を呼び出します。このメソッドを呼び出すと、req.subprocess_env には CGI に関する多くの情報が入ります。

add_handler( htype, handler[, dir])

この関数を使うと動的にハンドラを追加できます。htype は、たとえば "PythonHandler" のように、任意の (ただしフィルタハンドラや接続ハンドラは除きます) Apache リクエストハンドラのディレクティブ名が入った文字列です。 handler はモジュールやハンドラ関数の名前が入った文字列です。 dir はオプションで、sys.path に追加するディレクトリ名の入った文字列です。ディレクトリ名を指定しない場合、もしすでに同じタイプのハンドラが登録されていれば、その設定を継承します。PythonPath ディレクティブが有効であるばあい、sys.path はPythonPath の設定だけに従います (ディレクトリの追加は行わず、dir は無視されます)。

この関数を使って追加したハンドラは、リクエストの終了までしか存続しません。あるハンドラの内部で同じタイプのハンドラをさらに追加してもかまいませんが、その場合は無限ループを形成しないように気を付けねばなりません。

動的なハンドラ登録はコードの次の振舞いを動的に変更できる便利なテクニックです。典型的な例は、認証のレベルに応じて異なるPythonHandler を切替えるような PythonAuthenHandler でしょう:

if manager:
    req.add_handler("PythonHandler", "menu::admin")
else:
    req.add_handler("PythonHandler", "menu::basic")

注意: この関数は、正しいハンドラ名を使っているかどうかをチェックしません。不正なハンドラ名を渡した場合には無視されます。

allow_methods( methods[, reset]): methods を req.allowed_methods リストに追加します。このリストはHTTP_METHOD_NOT_ALLOWED や HTTP_NOT_IMPLEMENTED がクライアントに返される時に Allowed: ヘッダに渡されます。Apache は何らメソッド制限に対する操作を行わず。リストはただ単にヘッダの構築に使われるだけです。実際にメソッドを制限するロジックはハンドラコードで書かねばなりません。
methods は文字列からなる配列です。reset が 1 の場合、最初にメソッドのリストを消去します。

document_root( ): DocumentRoot の設定を返します。

get_basic_auth_pw( ): Basic 認証で使われるパスワードの入った文字列を返します。

get_config( ): 現在有効になっているmod_python の設定から Python*Handler および PythonOption の設定を除いた内容の入ったテーブルオブジェクトへの参照を返します (PythonOption の設定はreq.get_options() で取得できます)。テーブルのキーはディレクティブ名になり、テーブルの値はディレクティブの値 (あれば) になります。

get_remote_host( [type, str_is_ip])

遠隔のクライアントの DNS 名および IP アドレスを決定するためのメソッドです。この関数は最初の呼び出し時にDNSへの参照を伴うことがありますが、それ以降の呼び出しでは結果をキャッシュして使います。

type 引数は以下のような値に指定できます:

apache.REMOTE_HOST DNS を参照します。Apache の HostNameLookups がoff の場合や、ホスト名を特定できなかった場合には None を返します。
apache.REMOTE_NAME (デフォルト) DNS 名があれば返し、なければ IP アドレスを (10進ドット表記の文字列で) 返します。
apache.REMOTE_NOLOOKUP DNS 名の参照を行わず、IP アドレスを返します。注意: 以前の呼び出しで DNS を参照した場合、その結果としてキャッシュされたホスト名を返します。
apache.REMOTE_DOUBLE_REV 二重逆引きを強制的に行います。失敗すると None を返します。

str_is_ip をNone にしたり省略したりすると、戻り値は DNS 名または IP アドレスのいずれかを表現した文字列になります。

str_is_ip 引数を None 以外の値にすると、戻り値は(address, str_is_ip) からなるタプルになります。このとき、address が IP アドレスを示す文字列であれば、タプルの str_is_ip はゼロ以外の値になります。それ以外の場合には None を返します。

get_options( ): PythonOption ディレクティブで設定したオプションの入ったテーブルオブジェクトへの参照を返します。

internal_redirect( new_uri)

リクエストを new_uri に内部的にリダイレクトします。 new_uri は文字列でなければなりません。

httpd サーバは、新たなリクエストオブジェクトと全てのリクエストフェイズを生成して内部的なリダイレクションを実現します。内部リダイレクションの中では、req.prev にリダイレクト元のリクエストオブジェクトへの参照が入ります。

log_error( message[, level])

Apache の ap_log_rerror 関数へのインタフェースです。 message はエラーメッセージの入った文字列で、level は以下のフラグ定数のいずれかでなければなりません:

    APLOG_EMERG
    APLOG_ALERT
    APLOG_CRIT
    APLOG_ERR
    APLOG_WARNING
    APLOG_NOTICE
    APLOG_INFO
    APLOG_DEBUG
    APLOG_NOERRNO

リクエストオブジェクトへの参照がない状態でログを記録したければ、 apache.log_error 関数を使ってください。

requires( )

require ディレクティブの引数に指定した文字列からなるタプルを返します。

例えば、Apache の設定が以下のようになっているとすると:

AuthType Basic
require user joe
require valid-user

requires() は('user joe', 'valid-user') を返します。

read( [len])

クライアントから最大len バイトのデータを直接読み出し、読み出したデータを文字列にして返します。len 引数を省略するか、負の値に指定すると、クライアントから提供される全てのデータを読み出します。

この関数はApacheの Timeput 設定ディレクティブの影響を受けます。クライアントからデータを読み出す際にTimeout に指定した時刻を超過すると、読み出し操作を中断してIOError を送出します。

この関数ではクライアントが Content-length ヘッダを提供するものと想定しています。Content-length ヘッダがなければ、 Content-length: 0 であるかのように扱います。

Content-length が誤った値である場合、この関数はクライアントが提供できる以上のデータを読みだそうとして、その結果 Timeout に到達するまで処理をブロックさせる可能性があります。

readline( [len])

read() に似ていますが、行末までデータを読み込みます。

注意: HTTP の仕様により、ほとんどのクライアントは行末を "\n" ではなく"\r\n" で終端します。

readlines( [sizehint]): readline を使って sizehint バイトまでの全てのデータを読み出し、その結果をリストで返します。

register_cleanup( callable[, data])

後処理 (cleanup) 用の関数を登録します。 callable は任意の呼び出し可能オブジェクトにできます。オプションの引数 data は任意のオブジェクトにできます (デフォルトではNone です)。callable は、リクエストが終了した直後でかつApache が実際のリクエストレコードを破壊する直前に、data を引数にして呼び出されます。

リクエストオブジェクトを data に渡しても問題はありませんが、後処理を実行している時にはリクエスト処理はほとんど完結しており、クライアントへの書き込みのような操作には全く意味がないということを心に留めておいてください。

後処理中にエラーが生じた場合、そのことを必ずエラーログに記録せねばなりません。後処理におけるエラーはリクエストの処理に何ら影響を及ぼさないため、後処理におけるバグを追求しにくくなるからです。

後処理の実行に入る前にサーバがシャットダウンを始めると、後処理が実行されない可能性があります。

sendfile( path[, offset, len]): ファイル path のオフセットoffset 以降のlen バイトをサーバの内部 API を使ってクライアントに送信します。 offset のデフォルトは 0 で、 len のデフォルトは -1 (ファイル全体を送信する) です。
この関数はクライアントにファイルを送信する最も効率的な方法です。

write( string[, flush=1]): string をクライアントに直接書き出します。flush が 0 でない限り、書き出し後にバッファをフラッシュします。

flush( ): 出力バッファをフラッシュします。

set_content_length( len): req.clength および"Content-Length" ヘッダの値を len にsっ定します。ヘッダが送信されてしまった後 (req.write() などを呼び出してデータ本体の最初のバイトが書き出してしまった後) では、この関数を呼び出しても無意味なので注意してください。