tkapplication_cgi.py 技術ドキュメント

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

tkapplication_cgi.py は、CGI (Common Gateway Interface) 環境下で動作するWebアプリケーションをPythonで開発する際に利用されるユーティリティライブラリです。既存の tkApplication クラスを継承し、CGI特有の機能（HTTPリクエスト処理、HTML出力、フォームデータ解析、基本的なセキュリティチェック）を追加することで、サーバーサイドスクリプトの作成を簡素化することを目的としています。

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

HTML生成の補助: Webブラウザへ送信するHTMLの基本的な構造（DOCTYPE, head, bodyタグなど）を簡単に生成・出力できます。
CGIリクエストの判定: 現在のリクエストがGETメソッドかPOSTメソッドかを判別する機能を提供します。
フォームデータの取得: GETまたはPOSTメソッドで送信されたフォームデータやクエリ文字列パラメータを簡単に取得できます。
パスの簡易検証: ファイルパスやディレクトリパスに含まれる可能性のある不適切な文字列（例: ../, //, 特殊文字）を検出し、セキュリティ上のリスクを軽減するための簡易的な検証機能を提供します。

このライブラリを使用することで、PythonによるCGIスクリプト開発において、低レベルなHTTPヘッダーの操作やフォームデータのパースといった共通タスクから開発者を解放し、アプリケーションのビジネスロジックに集中できるようになります。

importする方法

このライブラリを他のPythonプログラムから利用するには、以下のように tkApplication_CGI クラスをインポートします。

from tkapplication_cgi import tkApplication_CGI

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

tkapplication_cgi.py は以下の非標準ライブラリに依存しています。

requests: HTTPリクエストを送信するためのライブラリですが、このライブラリのソースコード内では直接使用されていません（import requests はありますが、requests オブジェクトがどこでも使われていません）。しかし、もし将来的にHTTPクライアント機能が必要になった場合のために、インストールしておくことを推奨します。インストール方法:
```
pip install requests
```
tklib: このライブラリは tklib.tkapplication.tkApplication クラスを継承しています。tklib は通常、カスタムライブラリまたは特定のプロジェクトに付属するライブラリである可能性が高いです。インストール方法: 一般的なPythonパッケージと同様に pip でインストールできる場合は以下のコマンドでインストールできます。
```
pip install tklib
```
もし pip でインストールできない場合、このライブラリが利用されているプロジェクトの指示に従って tklib を入手し、Pythonのインポートパスが通る場所に配置してください。

importできる変数と関数

tkapplication_cgi.py からimportできる主要な要素は tkApplication_CGI クラスです。このクラスは tkApplication を継承しており、CGI環境特有のメソッドを提供します。

クラス: `tkApplication_CGI`

tkApplication クラスを継承し、CGIアプリケーション開発のための機能を提供します。

インスタンス変数

form: cgi.FieldStorage オブジェクトを保持します。これにより、GETやPOSTで送信されたフォームデータを効率的に扱うことができます。

メソッド

__init__(self, **args) tkApplication_CGI クラスのコンストラクタです。親クラスのコンストラクタを呼び出し、CGIフォームデータを格納するための cgi.FieldStorage オブジェクトを初期化します。
- 引数:
  - **args (任意): 親クラス tkApplication のコンストラクタに渡される任意のキーワード引数。
- 戻り値: なし
__del__(self) オブジェクトが破棄される際に呼び出されるデストラクタです。親クラス tkApplication のデストラクタを呼び出します。
- 引数: なし
- 戻り値: なし
__str__(self) オブジェクトの文字列表現を返します。親クラスの ClassPath() メソッドの結果を返します。
- 引数: なし
- 戻り値: str - クラスのパスを示す文字列。
init_html(self, charset='utf-8', lang='ja', extra_headers=None, header_only=False) HTMLページの開始部分を出力します。HTTPヘッダーとHTMLの <head> セクション（DOCTYPE, html, head, metaタグを含む）を生成します。
- 引数:
  - charset (str, 省略可能): HTMLの文字セット。デフォルトは 'utf-8'。
  - lang (str, 省略可能): HTMLの言語。デフォルトは 'ja'。
  - extra_headers (str, 省略可能): <head> セクションに追加する追加のHTMLヘッダー。
  - header_only (bool, 省略可能): True の場合、<body> タグは出力せず、ヘッダー部分のみを出力します。デフォルトは False。
- 戻り値: なし (標準出力にHTMLを出力します)
end_html(self) HTMLページの終了部分を出力します。</body> および </html> タグを出力します。
- 引数: なし
- 戻り値: なし (標準出力にHTMLを出力します)
get_cgi_mode(self) 現在のCGIリクエストのHTTPメソッドを文字列で返します。
- 引数: なし
- 戻り値: str - リクエストメソッドが GET の場合は 'get'、POST の場合は 'post'、それ以外の場合は空文字列 '' を返します。
get_args(self) GETリクエストのクエリ文字列 (QUERY_STRING) を解析し、キーと値のペアを辞書として返します。
- 引数: なし
- 戻り値: dict - クエリ文字列パラメータをキーと値として持つ辞書。
is_get(self) 現在のCGIリクエストがGETメソッドであるかを判定します。
- 引数: なし
- 戻り値: bool - リクエストメソッドが GET の場合は True、それ以外の場合は False。
is_post(self) 現在のCGIリクエストがPOSTメソッドであるかを判定します。
- 引数: なし
- 戻り値: bool - リクエストメソッドが POST の場合は True、それ以外の場合は False。
getvalue(self, key, defval=None) フォームデータ (self.form) から指定されたキーの値を取得します。キーが存在しない場合は、defval を返します。
- 引数:
  - key (str): 取得したいフォームデータのキー。
  - defval (任意, 省略可能): キーが見つからなかった場合に返すデフォルト値。デフォルトは None。
- 戻り値: str または None または defval - 指定されたキーの値。
getfirst(self, key, defval=None) フォームデータ (self.form) から指定されたキーの最初の値を取得します。cgi.FieldStorage の getfirst メソッドと同様の動作です。
- 引数:
  - key (str): 取得したいフォームデータのキー。
  - defval (任意, 省略可能): キーが見つからなかった場合に返すデフォルト値。デフォルトは None。
- 戻り値: str または None または defval - 指定されたキーの最初の値。
validate_path(self, path, keys='all') 提供されたパス文字列に対して、セキュリティ上の問題となる可能性のあるパターン（例: トップディレクトリへのアクセス、親ディレクトリへの移動、不正な文字）が含まれていないかを検証します。
- 引数:
  - path (str): 検証するパス文字列。
  - keys (str または list of str, 省略可能): 実行する検証のタイプを指定します。
    - 'all' (デフォルト): 全ての検証を実行します。
    - 'top_dir': トップディレクトリへの不正アクセス (/, \, C:, // など) をチェックします。
    - 'upper_dir': 親ディレクトリへの移動 (..) をチェックします。
    - 'invalid_char': 不正な文字 (<, >, |) をチェックします。
- 戻り値: str - 問題が検出された場合はエラーメッセージ文字列を、問題がない場合は空文字列 '' を返します。

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

tkapplication_cgi.py には if __name__ == "__main__": ブロックが存在しません。したがって、このファイルを直接Pythonインタプリタで実行 (python tkapplication_cgi.py) しても、何らかの特別な処理が実行されることはありません。このライブラリは、他のCGIアプリケーションスクリプトから tkApplication_CGI クラスをインポートし、利用されることを想定して設計されています。