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

ライブラリの機能や目的

tkHTMLDocument.py は、PythonプログラムからHTML要素をオブジェクトとして表現し、プログラム的にHTMLドキュメント構造を構築するためのライブラリです。主な目的と機能は以下の通りです。

  • HTML要素のオブジェクト指向表現: HTMLタグ、コンテンツ、属性、子要素をPythonのクラスインスタンスとして管理します。

  • プログラムによるHTML構造の構築: append_child メソッドなどを使用して、要素の親子関係を簡単に構築できます。

  • 自動HTMLエスケープ: コンテンツや属性値に特殊文字が含まれる場合、安全なHTML出力を確保するために自動的にエスケープ処理を行います（script タグや escape=False を指定した場合を除く）。

  • HTML文字列の生成: 構築された要素ツリーから、outerHTML や innerHTML といったプロパティを通じて、最終的なHTML文字列を簡単に取得できます。

  • テキストコンテンツの抽出: タグ構造を無視して、要素とその子要素全ての純粋なテキストコンテンツを抽出する機能を提供します。

  • テーブル構造の簡易生成: HTMLテーブル (<table>) を作成し、ヘッダーやデータ行を追加するコンビニエンスメソッドを提供します。

このライブラリは、動的にHTMLコンテンツを生成する必要があるWebアプリケーションのバックエンド処理や、静的なHTMLレポートの生成など、PythonでHTMLを操作する様々なシナリオで役立ちます。

importする方法

tkHTMLDocument.py を同じプロジェクトディレクトリに配置するか、Pythonのパスが通っている場所に配置することで、標準のPythonモジュールとして import できます。

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

import tkHTMLDocument

特定のクラスや変数を直接インポートする場合:

from tkHTMLDocument import tkHTMLElement, tkHTMLDocument, document

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

tkHTMLDocument.py は、Pythonの標準ライブラリのみを使用しており、追加の非標準ライブラリは必要ありません。そのため、pip を使用した特別なインストール作業は不要です。

使用している標準ライブラリ:

  • re: 正規表現操作のためのモジュール。

  • html: HTMLの特殊文字をエスケープするためのモジュール。

importできる変数と関数

このライブラリからインポートできる主要なクラスと、それに属するメソッド、プロパティ、およびグローバル変数を説明します。

クラス

class tkHTMLElement

HTMLの単一要素（例: <div>, <p>, <a>）を表現するクラスです。コンテンツ、属性、子要素を管理し、HTML文字列を構築する機能を提供します。

  • __init__(self, tag, content="", attributes=None, escape=True) HTML要素のインスタンスを初期化します。

    • 引数:

      • tag (str): HTMLタグ名（例: "div", "p", "img"）。

      • content (strまたは任意): 要素のテキストコンテンツ。escapeがTrueまたはtagが"script"以外の場合、html.escape() でエスケープされます。

      • attributes (dict, オプション): 要素の属性をキーと値のペアで持つ辞書。デフォルトはNone。

      • escape (bool, オプション): content および属性値をHTMLエスケープするかどうか。デフォルトはTrue。

    • 動作: 指定されたタグ、コンテンツ、属性でtkHTMLElementの新しいインスタンスを作成します。コンテンツは指定された条件に基づいてエスケープされ、属性は辞書として格納されます。子要素を格納するための空のリストも初期化されます。

  • @classmethod create_element(cls, tag, content="", attributes=None, escape=True) tkHTMLElementインスタンスを生成するためのクラスメソッドです。__init__ と同様の機能を提供します。

    • 引数: __init__ と同じ。

    • 戻り値: (tkHTMLElement) 新しく作成された tkHTMLElement インスタンス。

    • 動作: 新しいtkHTMLElementオブジェクトをインスタンス化し、それを返します。

  • @property contentText 要素自身の直接のテキストコンテンツを取得するためのプロパティです。

    • 戻り値: (str) 要素のテキストコンテンツ。

    • 動作: 要素に設定されているエスケープ済みのコンテンツ文字列 (_content) を返します。

  • @contentText.setter 要素の直接のテキストコンテンツを設定するためのセッターです。

    • 引数:

      • new_content (str): 新しいテキストコンテンツ。

    • 動作: 要素のコンテンツをnew_contentで更新します。このセッターではエスケープは行われません。

  • @property innerHTML 要素の子要素を含むHTML文字列（要素自身を囲むタグは含まない）を構築して取得するためのプロパティです。子要素はインデントされます。

    • 戻り値: (str) 子要素を含むHTML文字列。

    • 動作: 現在の要素の_contentと、全ての子要素のbuild_element()メソッドの結果を結合してHTML文字列を生成します。子要素のHTMLは2スペースでインデントされます。

  • @property textContent 要素自身とその全ての子要素のテキストコンテンツを、タグ構造を無視して改行で区切って結合したものを取得するためのプロパティです。

    • 戻り値: (str) 全てのテキストコンテンツを改行で結合した文字列。

    • 動作: 要素とその全ての子要素を再帰的に走査し、各要素の_contentを収集します。収集したコンテンツは改行文字で結合され、前後の空白が取り除かれて返されます。

  • @textContent.setter 要素のテキストコンテンツを一括で更新するためのセッターです。

    • 引数:

      • new_content (str): 新しいテキストコンテンツ。

    • 動作: new_contentをhtml.escape()でエスケープし、要素のコンテンツとして設定します。同時に、既存の子要素は全てクリアされます。

  • @property outerHTML 要素自身を囲むタグを含め、要素全体の完全なHTML文字列を構築して取得するためのプロパティです。

    • 戻り値: (str) 要素全体のHTML文字列。

    • 動作: build_element() メソッドを呼び出し、その結果を返します。

  • append_child(self, *child_elements) 一つまたは複数のtkHTMLElementインスタンスを現在の要素の子要素として追加します。

    • 引数:

      • *child_elements (tkHTMLElementの可変長引数): 追加する子要素のインスタンス。

    • 動作: 引数で渡された各tkHTMLElementインスタンスを、現在の要素のchildrenリストに追加します。

  • build_element(self) 現在の要素のHTML文字列を構築します。属性の書式設定、空要素の処理、子要素のインデントなどを含みます。

    • 戻り値: (str) 構築されたHTML要素の文字列。

    • 動作:

      1. 要素の属性をkey="value"形式の文字列に変換します。True値の属性はkeyのみ（例: open）、FalseやNoneは省略されます。

      2. br, img, inputなどの空要素の場合は、自己閉鎖タグ（例: <img src="a.png" />）として生成します。

      3. 子要素が存在する場合、子要素のHTMLを2スペースでインデントし、現在の要素のコンテンツと子要素の間に改行を挿入して結合します。

      4. 最終的なHTMLタグとコンテンツ、子要素を結合し、適切な書式で要素のHTML文字列を返します。

class TableStructure

HTMLテーブル構造を段階的に構築するためのクラスです。 注意: このクラスは現在、tkHTMLDocument クラスの create_table メソッドでは使用されていません。また、内部で未定義の変数 tk_document を参照しているため、現状ではインスタンス化するとエラーが発生します。

  • __init__(self, document=None) TableStructureインスタンスを初期化し、基本的なテーブル構造（<table>, <thead>, <tbody>, <tr>）を作成します。

    • 引数:

      • document (tkHTMLDocument, オプション): tkHTMLDocumentのインスタンス。指定がない場合、新しいインスタンスが作成されます。

    • 動作: tkHTMLDocumentインスタンスを保持し、table, thead, tr_head, tbody要素を生成してそれらを適切な階層で構築します。

  • add_header(self, headers) テーブルのヘッダー行にセルを追加します。

    • 引数:

      • headers (list of str): ヘッダーとして表示する文字列のリスト。

    • 動作: 各文字列に対して<th>要素を作成し、ヘッダー行 (<tr> dentro <thead>) に追加します。

  • add_row(self, row_data) テーブルのボディにデータ行を追加します。

    • 引数:

      • row_data (list of str): 行のデータとして表示する文字列のリスト。

    • 動作: 新しい<tr>要素を作成し、<tbody>に追加します。その後、各データ文字列に対して<td>要素を作成し、その<tr>に追加します。

class tkHTMLDocument

HTMLドキュメント全体の管理や、複数の要素を作成するためのコンビニエンスメソッドを提供するクラスです。

  • __init__(self) tkHTMLDocumentインスタンスを初期化します。特別な初期化処理はありません。

  • create_element(self, tag, content="", attributes=None, escape=True) tkHTMLElementインスタンスを生成するためのコンビニエンスメソッドです。

    • 引数: tkHTMLElementの__init__と同じ。

    • 戻り値: (tkHTMLElement) 新しく作成された tkHTMLElement インスタンス。

    • 動作: tkHTMLElementクラスのコンストラクタを呼び出し、その結果を返します。

  • create_table(self, attributes={"border": "1"}, header=[], data_list=[]) 完全なHTMLテーブル (<table>) を生成し、オプションでヘッダーとデータ行を追加します。

    • 引数:

      • attributes (dict, オプション): <table>要素の属性。デフォルトは{"border": "1"}。

      • header (list of str, オプション): テーブルヘッダーの文字列リスト。

      • data_list (list of list of str, オプション): テーブルの各行のデータを含むリストのリスト。

    • 戻り値: (tuple of tkHTMLElement) 作成された table, thead, tr_head, tbody 要素のタプル。

    • 動作:

      1. 指定された属性で<table>要素を作成します。

      2. <thead>、<tr>（ヘッダー用）、<th>要素を作成し、headerリストに基づいてヘッダーを構築します。

      3. <tbody>、<tr>（データ行用）、<td>要素を作成し、data_listに基づいてデータ行を構築します。

      4. これらの要素を適切な階層で<table>要素に追加します。

      5. 作成された主要なテーブル要素をタプルとして返します。

グローバル変数

  • document tkHTMLDocumentクラスのグローバルインスタンスです。

    • 型: tkHTMLDocument

    • 説明: このインスタンスを通じて、create_element や create_table といったメソッドを直接呼び出してHTML要素を作成できます。これは、HTML要素の生成を簡略化するためのショートカットとして提供されています。

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

tkHTMLDocument.py ファイルが直接Pythonインタープリタで実行された場合（python tkHTMLDocument.py のように）、if __name__ == "__main__": ブロック内のコードが実行されます。

このブロックでは、以下の処理が行われます。

  1. グローバルに定義された document インスタンス (tkHTMLDocument のオブジェクト) を使用して、3つのHTML要素が作成されます。

    • <details open="true"> 要素 (details)

    • <summary> 要素 (summary)、コンテンツは "クリックして開閉"

    • <div> 要素 (content)、コンテンツは "ここに詳細情報を書きます！"

  2. summary 要素と content 要素が details 要素の子要素として追加され、以下のようなHTML構造が構築されます。

    <details open="true">
  <summary>クリックして開閉</summary>
  <div>ここに詳細情報を書きます！</div>
</details>

  3. 構築された details 要素について、3つのプロパティが呼び出され、その結果が標準出力（コンソール）に表示されます。

    • details.textContent: details 要素とその全ての子要素の純粋なテキストコンテンツを改行で結合したものを出力します。

    • details.innerHTML: details 要素の子要素のHTML文字列（<details> タグ自身は含まない）を出力します。子要素はインデントされます。

    • details.outerHTML: details 要素全体の完全なHTML文字列（<details> タグ自身を含む）を出力します。

実行結果の例:

textContent: クリックして開閉
ここに詳細情報を書きます！
InnerHTML:   <summary>クリックして開閉</summary>
  <div>ここに詳細情報を書きます！</div>
OuterHTML: <details open="true">
  <summary>クリックして開閉</summary>
  <div>ここに詳細情報を書きます！</div>
</details>