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"