run_report.py ドキュメント

概要

run_report.py は、指定されたコマンドを実行し、その前後のファイル変更を追跡して実行レポート(HTMLおよびMarkdown形式)を作成するユーティリティスクリプトです。コマンドの標準出力・標準エラー出力をキャプチャするだけでなく、実行環境のハードウェア情報(CPU、メモリ、GPUなど)やソフトウェア環境(Pythonのバージョン、対象パッケージのインストール状況)を記録し、実行時に作成・更新・削除されたファイルを特定します。

動作原理

本スクリプトはデータ処理およびユーティリティプログラムとして、以下の順序で処理を実行します。

  1. 実行前スナップショットの取得 指定された作業ディレクトリ(--cwd)を再帰的に走査し、各ファイルのファイルサイズ、更新日時、およびSHA256ハッシュを取得します。除外パターン(--ignore)に一致するファイルはスキップされます。

  2. 環境情報の収集 実行ホストのOS、アーキテクチャ、CPU情報、メモリ容量、およびNVIDIA GPUの情報(nvidia-smi コマンドを利用)を収集します。

  3. コマンドの実行とログキャプチャ 指定されたコマンド(--cmd)を subprocess を用いて実行します。標準出力および標準エラー出力を並行して読み取り、それぞれ stdout.log および stderr.log に保存します。

  4. 実行後スナップショットの取得と差分比較 コマンド終了後、再度作業ディレクトリを走査し、実行前のスナップショットと比較することで、新規作成、更新、削除されたファイルを特定します。ハッシュ比較方式(--hash)に応じて、すべてのファイルをハッシュ化するか、サイズと日時が変更されたファイルのみをハッシュ化するかを切り替えます。

  5. アーティファクトの保存とログ走査 作成および更新されたファイルは、出力ディレクトリ内の artifacts フォルダにコピーされます。また、ログファイルおよび変更されたテキストファイルを正規表現(--error-regex および --warning-regex)で走査し、エラーや警告を抽出します。

  6. レポート生成 収集したすべての情報を統合し、HTML(report.html)およびMarkdown(report.md)形式でレポートを出力します。

依存ライブラリ

本スクリプトはサードパーティ製の非標準ライブラリに依存せず、Pythonの標準ライブラリのみで動作します。

  • 標準ライブラリ: argparse, datetime, fnmatch, hashlib, html, importlib.metadata, json, locale, os, pathlib, platform, re, shlex, shutil, signal, subprocess, sys, threading, time, urllib.parse

ただし、環境情報の収集やプロセスの終了などのために、以下のシステムコマンドを利用する場合があります。

  • Windows環境: powershell.exe, taskkill

  • NVIDIA GPU環境: nvidia-smi, nvcc

また、環境変数の記録やバージョン確認の対象として、numpy, scipy, matplotlib, numba, cupy などのPythonパッケージがインストールされているかを動的にチェックします(インポート必須ではありません)。

入出力仕様

入力(CLIオプション)

スクリプトはコマンドライン引数から設定を受け取ります。主要なオプションは以下の通りです。

  • --cwd: 実行および比較を行う作業ディレクトリを指定します(デフォルト: カレントディレクトリ)。

  • --output-dir: レポートを保存する出力ディレクトリを指定します(デフォルト: 作業ディレクトリ内の run_report_日時)。

  • --timeout: コマンド実行のタイムアウトを秒単位で指定します。 0 以下の場合は無制限となります。

  • --shell: コマンドをシェル経由で実行します(パイプやリダイレクトを使用する場合に有効です)。

  • --format: 生成するレポートの形式を html, md, both から指定します。

  • --ignore: 比較から除外するファイルのパターンをカンマ区切りで指定します。

  • --hash: ファイルの差分比較方式を none, changed, all から指定します。

  • --cmd: 実行する対象のコマンドとその引数を指定します(必ず引数の最後に記述します)。

出力(レポートフォルダ構成)

コマンド実行後、指定した出力ディレクトリ(--output-dir)に以下のファイルおよびフォルダが生成されます。

  • environment.json: 実行環境の詳細情報が記録されたJSONファイル。

  • stdout.log: 対象コマンドの標準出力をキャプチャしたログファイル。

  • stderr.log: 対象コマンドの標準エラー出力をキャプチャしたログファイル。

  • report.html: HTML形式のコマンド実行レポート(--format で有効化された場合)。

  • report.md: Markdown形式のコマンド実行レポート(--format で有効化された場合)。

  • artifacts/: 実行中に新規作成または更新されたファイルがコピーされるディレクトリ。

実行例

対象のスクリプト(例: simulate.py)を --temperature 300 という引数付きで実行し、タイムアウトを3600秒に設定し、HTMLとMarkdownの両方でレポートを生成する実行例です。

python run_report.py \
    --cwd ./case \
    --timeout 3600 \
    --format both \
    --ignore .git,.venv,__pycache__ \
    --cmd python simulate.py --temperature 300

シェル機能(パイプなど)を含むコマンドを実行する場合は、--shell オプションを付与し、コマンド全体をクォーテーションで囲むか、複数の引数として渡します。

python run_report.py \
    --shell \
    --hash changed \
    --cmd "ls -la | grep .py"