tkFormData.py ライブラリドキュメント

このドキュメントは、Python言語で記述された tkFormData.py ライブラリの技術的な詳細について説明します。

ライブラリの機能や目的

tkFormData.py は、CGI (Common Gateway Interface) 環境下で動作するPythonスクリプトが、HTTPリクエストによって送信されるフォームデータを効率的に解析するためのライブラリです。特に、GETリクエストのクエリ文字列と、POSTリクエストの application/x-www-form-urlencoded 形式、そしてファイルアップロードを含む multipart/form-data 形式の両方に対応しています。

主な機能は以下の通りです。

GETリクエストのクエリパラメータ解析: QUERY_STRING 環境変数からURLエンコードされたパラメータを解析し、辞書形式で提供します。
POSTリクエストのフォームデータ解析:
- 通常のフォームデータ（application/x-www-form-urlencoded 形式に類似）を解析し、辞書形式で提供します。
- ファイルアップロードを含む multipart/form-data 形式のデータを解析し、フォームフィールドとアップロードされたファイルの両方を分離して提供します。
ファイルアップロードの処理: multipart/form-data で送信されたファイルは、ファイル名とバイナリコンテンツとして取得できます。

このライブラリは、CGIアプリケーション開発者がHTTPリクエストの複雑なデータ解析ロジックを自前で実装する手間を省き、ビジネスロジックに集中できるようにすることを目的としています。

importする方法

tkFormData.py ライブラリを他のPythonプログラムから利用するには、以下の手順に従います。

tkFormData.py ファイルを、使用するPythonスクリプトと同じディレクトリ、またはPythonのパスが通っているディレクトリに配置します。

Pythonスクリプトの冒頭で、以下のいずれかの方法でクラスや関数をインポートします。

# tkFormData クラスと get_params 関数を個別にインポートする場合
from tkFormData import tkFormData, get_params

# ライブラリ全体をインポートし、tkFormData.tkFormData や tkFormData.get_params のように参照する場合
import tkFormData

必要な非標準ライブラリとインストール方法

tkFormData.py ライブラリは、Pythonの標準ライブラリのみを使用しており、非標準ライブラリを必要としません。

したがって、pip コマンドなどを使った追加のインストール作業は不要です。Pythonが動作する環境であれば、すぐに利用可能です。

使用している標準ライブラリは以下の通りです。

os: 環境変数へのアクセス
sys: 標準入力ストリームへのアクセス
urllib.parse: URLクエリ文字列の解析

importできる変数と関数

tkFormData.py ライブラリから import できる主要な要素は、tkFormData クラスと get_params 関数です。

クラス: `tkFormData`

CGI環境から受け取った生データ（環境変数と入力ストリーム）を解析し、フォームデータとアップロードファイルを格納するためのクラスです。主に multipart/form-data の解析を担当しますが、クエリ文字列の解析も初期化時に行います。

初期化

tkFormData(environ, input_stream)

説明: tkFormData クラスのインスタンスを生成し、提供されたCGI環境変数と入力ストリームからフォームデータおよびファイルデータを解析します。

引数:

environ (dict): CGI環境変数を含む辞書です。典型的には os.environ が渡されます。QUERY_STRING や CONTENT_TYPE などのキーが含まれていることを期待します。
input_stream (file-like object): リクエストボディの生データを提供するファイルライクオブジェクトです。POSTリクエストの場合、典型的には sys.stdin.buffer が渡されます。

属性

form_data (dict): 解析されたフォームフィールドのデータを格納する辞書です。キーはフォームフィールド名、値は対応するデータ（文字列）です。
files (dict): アップロードされたファイルの情報を格納する辞書です。キーはフォームフィールド名、値は以下の構造を持つ辞書です。
- filename (str): アップロードされたファイルの元のファイル名。
- content (bytes): アップロードされたファイルのバイナリコンテンツ。
query_string (bytes): _parse_multipart_data メソッドで読み込まれた生のHTTPリクエストボディデータ。この属性は multipart/form-data の場合にのみ有効です。

メソッド

`get_form_data()`

説明: 解析されたすべてのフォームフィールドデータを辞書として返します。

引数: なし

戻り値: form_data 属性のコピー (dict)

`get_file(name)`

説明: 指定された名前のアップロードファイルの情報を返します。

引数:

name (str): 取得したいファイルのフォームフィールド名。

戻り値: 指定されたファイルの情報を含む辞書 (dict)。ファイルが見つからない場合は None。

関数: `get_params()`

CGI環境変数 REQUEST_METHOD に応じて、GETまたはPOSTリクエストのパラメータを包括的に解析し、結果を返します。この関数は、CGIスクリプトでフォームデータを取得する際のエントリポイントとして設計されています。

get_params()

説明: CGI環境変数 os.environ を参照し、REQUEST_METHOD に基づいてGETまたはPOSTリクエストのフォームデータを解析します。POSTリクエストで multipart/form-data が検出された場合、内部で tkFormData クラスを使用して解析を行います。

引数: なし (内部で os.environ と sys.stdin.buffer を参照します)

戻り値: 以下の4つの要素を含むタプルを返します。

request_method (str): HTTPリクエストメソッド（例: "GET", "POST"）。
query_string (str or bytes):
- GETリクエストの場合: QUERY_STRING 環境変数の値（文字列）。
- POSTリクエストかつ multipart/form-data の場合: リクエストボディの生データ（bytes）。
- その他のPOSTリクエストの場合: 空文字列。
query_params (dict):
- GETリクエストの場合: urllib.parse.parse_qs によって解析されたクエリパラメータの辞書。各キーの値はリスト形式（例: {'key': ['value']}）。
- POSTリクエストの場合: tkFormData クラスによって解析されたフォームデータ（self.form_data）の辞書。各キーの値は単一の文字列。
form_storage (tkFormData or None):
- POSTリクエストかつ multipart/form-data の場合: tkFormData クラスのインスタンス。
- それ以外の場合: None。

main scriptとして実行したときの動作

tkFormData.py は、if __name__ == "__main__": ブロックを持たないため、直接メインスクリプトとして実行された場合でも、特定の動作は定義されていません。

しかし、このコードには get_params() 関数内にコメントアウトされた print 文が多数含まれており、これらのコメントから、CGI環境下での動作をテストまたはデバッグする目的で設計されたことが推測できます。もしこれらのコメントを解除してCGI環境で実行した場合、以下のような情報が標準出力（Webサーバーを介してブラウザ）に出力されることが期待されます。

リクエストメソッド (REQUEST_METHOD)
GETリクエストの場合のクエリ文字列 (QUERY_STRING) と解析されたパラメータ (query_params)
POSTリクエストの場合のコンテントタイプ (CONTENT_TYPE)
multipart/form-data の場合に tkFormData クラスによって解析されたフォームデータ (query_params)
アップロードされたファイル情報（ファイル名など）

これらの出力は、通常HTMLタグ (<br>, <hr>) を含んでおり、CGIスクリプトが生成するHTMLの一部として整形されることを意図しています。

tkFormData.py ライブラリ ドキュメント