make_run_report.py ドキュメント
概要
make_run_report.py は、指定した作業ディレクトリで任意のコマンドを実行し、実行結果を包括的なMarkdownレポートとして自動生成するユーティリティスクリプトです。コマンド実行前後のファイルシステムの差分(新規作成、変更、削除)を追跡し、標準出力や標準エラー出力、終了コードを収集します。さらに、ログファイルから警告やエラーを自動検出し、生成された画像ファイルをレポートに埋め込むことができます。
動作原理
本プログラムは以下の手順でコマンドの実行とレポートの生成を行います。
実行前スナップショットの取得 作業ディレクトリ (
--workdir) 内のファイルを再帰的に走査し、各ファイルのサイズと最終更新時刻を記録します。この際、--ignoreで指定されたパターン(__pycache__や*.tmpなど)に一致するファイルは監視から除外されます。コマンドの実行
subprocess.runを用いて、指定されたコマンド (--cmd) を実行します。このとき、標準出力と標準エラー出力をキャプチャし、タイムアウト (--timeout) の監視を行います。実行後スナップショットの取得と差分計算 コマンド終了後に再度ファイルシステムの走査を行い、実行前の状態と比較して、新規に作成されたファイル、変更されたファイル、および削除されたファイルを特定します。
ログとエラーの走査 新規作成・変更されたファイルのうち、指定された拡張子 (
--log-exts) を持つファイルと、コマンドの標準エラー出力を対象に、テキストの走査を行います。エラーを示す正規表現 (--error-regex) と警告を示す正規表現 (--warning-regex) を用いて、該当する行を抽出します。レポートの生成 収集したすべての情報(実行サマリー、実行されたコマンド、実行前後のファイルツリー、ファイル差分、生成された画像の埋め込み、抽出されたログヒット、標準出力・標準エラー出力の内容)をまとめ、指定されたファイル名 (
--report) でMarkdown形式のレポートを出力します。HTML変換 (オプション)
--html 1が指定されている場合、外部ツールのpandocを呼び出し、生成されたMarkdownレポートをHTMLファイル (--html-name) に変換します。
非標準ライブラリ・依存関係
本スクリプトの import 文からは、以下の依存関係が確認できます。
Python標準ライブラリ すべてのインポートモジュール (
argparse,dataclasses,datetime,fnmatch,os,pathlib,platform,re,shlex,subprocess,sys,traceback,typing) はPython標準ライブラリであり、外部パッケージ (非標準ライブラリ) への依存はありません。外部コマンド HTML形式のレポートを生成する場合 (
--html 1を指定した場合)、システムにpandocコマンドがインストールされている必要があります。
入出力仕様
本プログラムはコマンドライン引数経由で入力を受け取り、作業ディレクトリ内にレポートファイルを出力します。
入力
--workdir: コマンドを実行し、監視対象とする作業ディレクトリのパス。--cmd: 実行するコマンド文字列(必須)。--ignore: 監視から除外するファイルのパターン(カンマ区切り文字列)。--log-exts: 警告・エラー走査の対象とする拡張子(カンマ区切り文字列)。その他、出力上限やタイムアウトを制御するための各種オプション。
出力
Markdownレポート:
--reportオプションで指定されたファイル名(デフォルトはreport.md)で、作業ディレクトリ内に生成されます。HTMLレポート:
--html 1を指定した場合、--html-nameオプションで指定されたファイル名(デフォルトはreport.html)で、作業ディレクトリ内に生成されます。
実行例
以下に、コマンドラインからの基本的な実行例を示します。
基本的なコマンド実行とMarkdownレポートの生成:
python make_run_report.py --workdir ./my_project --cmd "python main.py"
HTMLレポートの同時生成と、タイムアウト時間を設定した実行例:
python make_run_report.py --workdir ./data_pipeline --cmd "bash run_all.sh" --html 1 --timeout 300.0
監視除外パターンや対象ログ拡張子をカスタマイズした実行例:
python make_run_report.py --workdir ./training --cmd "python train_model.py" --ignore "*.tmp,*.bak,.git" --log-exts ".log,.csv" --report "training_report.md"