tkBase.py ライブラリ技術ドキュメント

ライブラリの機能や目的

tkBase.py は、主にCGIスクリプトやシンプルなウェブアプリケーションの構築を補助するために設計されたPythonライブラリです。ウェブ環境での開発において頻繁に必要となる基本的な機能を提供し、開発者がアプリケーションのロジックに集中できるようにします。

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

  • HTML形式の例外ハンドリング: Pythonスクリプトで未処理の例外が発生した場合、エラー情報（トレースバック）をHTML形式で整形して標準出力に出力します。これにより、ウェブブラウザでエラー内容を視覚的に確認しやすくなります。

  • 基本的なHTML出力補助: CGIヘッダとHTMLドキュメントの基本的な構造（<html>, <head>, <body> タグなど）の生成を簡素化します。

  • ファイル読み込み: 特定のエンコーディングを指定してテキストファイルを読み込む機能を提供します。

  • INIファイル解析: INI形式の設定ファイルを読み込み、キーと値のペアをPythonの辞書として抽出する機能を提供します。コメントやセクションヘッダは自動的に無視されます。

  • パス情報の整形と置換: ファイルパスからディレクトリ名、ファイル名、拡張子などの要素を抽出し、それらを任意のテンプレート文字列に埋め込んで新しいパス文字列を生成します。

このライブラリは、特に軽量なウェブアプリケーションやツールにおいて、エラー表示の改善、HTML出力の定型化、設定管理、ファイルパス操作といった共通の課題を解決することを目的としています。

importする方法

tkBase.py ライブラリを他のPythonプログラムから利用するには、通常のPythonモジュールと同様に import ステートメントを使用します。

ライブラリ全体をインポートする場合：

import tkBase

特定の関数のみをインポートする場合：

from tkBase import set_error_handler, init_html, read_ini

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

tkBase.py は、Pythonの標準ライブラリである sys, traceback, os のみを使用しており、特に外部の非標準ライブラリに依存していません。 したがって、pip コマンドなどを用いた追加のインストールは不要です。Pythonが動作する環境であれば、すぐに利用できます。

ただし、replace_path 関数内で os モジュールが利用されていますが、tkBase.py のソースコード中には import os の記述がありません。replace_path 関数を使用する場合は、アプリケーションコード側で import os を記述する必要があるかもしれません（Pythonのバージョンや実行環境によっては自動的に利用可能であることもありますが、明示的なインポートが推奨されます）。

importできる変数と関数

tkBase.py ライブラリは、以下の関数を公開しています。グローバル変数は定義されていません。

関数

handle_exception(exc_type, exc_value, exc_tb)

  • 動作: Pythonで発生した例外情報をHTML形式で整形し、標準出力に表示します。主にCGI環境で未処理の例外が発生した際に、ブラウザにエラーの詳細を表示するために使用されます。sys.excepthook に設定することを想定しています。

  • 引数:

    • exc_type (type): 例外の型。例: TypeError, ValueError。

    • exc_value (Exception): 発生した例外オブジェクト。

    • exc_tb (traceback): 例外発生時のトレースバックオブジェクト。

  • 戻り値: なし。

set_error_handler()

  • 動作: Pythonのシステムレベルの例外フック sys.excepthook を、このライブラリの handle_exception 関数に設定します。これにより、プログラム中でキャッチされなかった例外が発生した場合に、handle_exception が自動的に呼び出され、HTML形式でエラー情報が出力されるようになります。

  • 引数: なし。

  • 戻り値: なし。

init_html(charset="utf-8")

  • 動作: ウェブブラウザにHTMLドキュメントとして認識させるためのCGIヘッダと、HTML5ドキュメントの基本的な開始部分を標準出力に生成します。具体的には Content-Type ヘッダ、<!DOCTYPE html>, <html>, <head>, <meta charset>, <title>Debug</title>, <body> タグが出力されます。

  • 引数:

    • charset (str, オプション): HTMLドキュメントの文字エンコーディングを指定します。デフォルトは "utf-8" です。

  • 戻り値: なし。

end_html()

  • 動作: init_html() で開始されたHTMLドキュメントの終了タグ (</body> と </html>) を標準出力に生成します。

  • 引数: なし。

  • 戻り値: なし。

read_file(path, charcode='utf8')

  • 動作: 指定されたパスのファイルを読み込み、その内容全体を文字列として返します。

  • 引数:

    • path (str): 読み込むファイルのパス。

    • charcode (str, オプション): ファイルの文字エンコーディングを指定します。デフォルトは "utf8" です。

  • 戻り値: ファイルの内容を示す文字列 (str)。ファイルが見つからない場合や開けない場合は None を返します。

read_ini(path)

  • 動作: 指定されたパスのINI形式の設定ファイルを読み込み、セクションヘッダやコメント行 (# で始まる行) を無視して、キー=値 の形式の行を解析し、Pythonの辞書として返します。

  • 引数:

    • path (str): 読み込むINIファイルのパス。

  • 戻り値: INIファイルの内容を表す辞書 (dict)。ファイルが見つからない場合は None を返します。

replace_path(path, template, ext_dict = {})

  • 動作: 与えられたファイルパスから、fullpath (絶対パス), dirname (ディレクトリ名), filename (ファイル名と拡張子), filebody (ファイル名本体), ext (拡張子) などの要素を抽出し、これらを指定されたテンプレート文字列に埋め込んで新しいパス文字列を生成します。template 文字列はPythonの str.format() メソッドが使用するプレースホルダ ({key}) を含めることができます。

  • 引数:

    • path (str): 処理する元のファイルパス。

    • template (str): 新しいパスを生成するためのフォーマット文字列。利用可能なプレースホルダには {fullpath}, {dirname}, {filename}, {filebody}, {ext} などがあります。

    • ext_dict (dict, オプション): テンプレートに渡される追加のキーワード引数を持つ辞書。デフォルトは空の辞書です。この辞書の内容は、抽出されたパス要素の辞書とマージされます。

  • 戻り値: フォーマットされた新しいパス文字列 (str)。

  • 注記: この関数は内部で os モジュールを使用しています。tkBase.py のソースコードには import os の記述がありませんが、通常はPythonの標準ライブラリとして利用可能です。

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

tkBase.py には if __name__ == "__main__": ブロックが存在しないため、このファイルをPythonインタプリタで直接実行 (python tkBase.py など) しても、特別な動作は実行されません。単に関数と変数の定義がメモリにロードされるだけです。このライブラリは、他のスクリプトやアプリケーションから import してその機能を利用することを想定しています。