debug_sphinx_build プログラム仕様
Sphinx autodocにおけるimportエラーを調査するためのユーティリティスクリプト。
このスクリプトは、Sphinxのビルドプロセスで発生する可能性のあるPythonモジュールのimportエラーをデバッグするために設計されています。 特に、`autodoc_mock_imports`の設定が正しく機能しているか、または他の原因でimportエラーが発生しているかを特定するのに役立ちます。
目的: - ./source/conf.py をインポートし、autodoc_mock_imports の設定を読み込む。 - 読み取った autodoc_mock_imports に基づいて、ダミーモジュールを sys.modules に登録する。 - 指定された source ディレクトリ配下のすべての .py ファイルを再帰的にインポートする。 - インポート中に発生したエラーを記録し、必要に応じて処理を継続する。
仕様: - スクリプト実行時、--source 引数で指定されたディレクトリ (デフォルトは source) をSphinxのソースディレクトリとして扱います。 - conf.py は他のファイルよりも先に個別にインポートされ、その設定が適用されます。 - conf.py 以外の .py ファイルは、source ディレクトリからの相対パスに基づいて一意な疑似モジュール名でインポートされます。 - ファイル名が _数字列 で終わるファイル (例: sample_1.py, test_2024.py) はスキップされます。 - デフォルトでは、インポート中に例外が発生した場合、トレースバックを表示してスクリプトは終了します。 - --keep-going オプションを指定すると、エラーが発生しても処理を最後まで継続し、最後にすべての失敗一覧を表示します。 - --mock オプションを使用すると、conf.py をインポートする前に手動でモジュールをモックできます。 - sys.path にカレントディレクトリやソースディレクトリを追加するオプションも提供されます。
debug_sphinx-build_usage
- class ai.debug_sphinx_build.DummyModule(name, doc=None)[ソース]
ベースクラス:
ModuleType属性アクセス時に DummyObject を返すダミーモジュール。
sys.modules に登録することで、存在しないモジュールがimportされようとした際に、 実際には何もしないダミーのモジュールとして機能させます。 これにより、モジュール内の属性アクセスや関数呼び出しがすべて DummyObject に よって処理され、AttributeError や ImportError を回避できます。
- class ai.debug_sphinx_build.DummyObject(name: str = 'dummy')[ソース]
ベースクラス:
objectどんな属性アクセスや関数呼び出しでも受け流すダミーオブジェクト。
このクラスは、存在しないモジュールやオブジェクトに対する参照、 メソッド呼び出しなどが発生した場合にエラーを回避するために使用されます。 どのような操作に対しても自身を返すか、新しい DummyObject を生成することで、 実行を中断させずに処理を継続させます。
- ai.debug_sphinx_build.install_mock_modules(module_names: list[str]) None[ソース]
指定したモジュール名を sys.modules にダミーモジュールとして登録する。
モジュール名が pkg.subpkg のように階層的である場合、pkg と pkg.subpkg の両方を ダミーモジュールとして登録し、ネストされたimportをサポートします。 既に登録されているモジュールは上書きされません。
- ai.debug_sphinx_build.load_module_from_file(module_name: str, file_path: Path)[ソース]
任意の .py ファイルを module_name という名前でインポートする。
importlib.util を使用してファイルからモジュールをロードし、 sys.modules に登録します。これにより、通常の import 文と同様に モジュールをロードし、そのオブジェクトにアクセスできるようになります。
- パラメータ:
module_name (str) -- インポートするモジュールの名前。sys.modules に登録される名前となります。
file_path (Path) -- インポート対象の .py ファイルのパス。
- 戻り値:
ロードされたモジュールオブジェクト。
- 例外:
ImportError -- モジュールのスペックを生成できなかった場合。
- ai.debug_sphinx_build.main()[ソース]
スクリプトのメイン処理を実行する。
コマンドライン引数を解析し、Sphinxのソースディレクトリ内のPythonファイルを順次インポートします。 conf.py をロードして autodoc_mock_imports を取得し、それらのモジュールをモックします。 その後、ソースディレクトリ内の残りの .py ファイルをインポートし、 --keep-going オプションに応じてエラー処理を行います。 最終的に、記録されたエラーの要約を表示し、エラーがあれば非ゼロの終了コードで終了します。
- 戻り値:
None
- ai.debug_sphinx_build.make_module_name(source_dir: Path, py_file: Path) str[ソース]
source_dir 配下の相対パスから、一意な疑似モジュール名を生成する。
ファイルパスをPythonの識別子として有効な形式に変換し、モジュール名の衝突を避けるために sphinx_debug. というプレフィックスを付与します。 ファイル名やディレクトリ名に含まれるハイフン (-) やスペース (` ) はアンダースコア (`_) に変換され、 無効な文字を含む識別子にはさらにプレフィックスが追加されます。
- パラメータ:
source_dir (Path) -- Sphinxのソースディレクトリのパス。このパスからの相対パスがモジュール名の基になります。
py_file (Path) -- 疑似モジュール名を生成する対象の .py ファイルのパス。
- 戻り値:
生成された一意な疑似モジュール名。
- 戻り値の型:
- ai.debug_sphinx_build.parse_mock_arg(mock_text: str) list[str][ソース]
コマンドライン引数 --mock で渡された文字列をモジュール名のリストに変換する。
入力文字列はセミコロン (;) で区切られたモジュール名を含むと想定されます。 各モジュール名から前後の空白が除去され、空の文字列は無視されます。 例: "whisper;torch;numba" は ["whisper", "torch", "numba"] に変換されます。
- ai.debug_sphinx_build.print_error_summary(errors: list[dict]) None[ソース]
記録されたエラーの要約を表示する。
エラーがない場合はその旨を表示し、ある場合は各エラーのファイルパス、エラータイプ、 エラーメッセージを一覧形式でコンソールに出力します。
- ai.debug_sphinx_build.record_error(errors: list[dict], phase: str, file_path: Path, exc: BaseException) None[ソース]
発生したエラーの詳細をエラーリストに記録する。
エラー情報には、発生フェーズ、ファイルパス、エラータイプ、メッセージ、完全なトレースバックが含まれます。 これは --keep-going オプションが指定された場合に、複数のエラーをまとめて報告するために使用されます。
- パラメータ:
errors (list[dict]) -- エラー情報を格納するリスト。各エラーは辞書としてこのリストに追加されます。
phase (str) -- エラーが発生した処理フェーズを示す文字列（例: "conf.py", "module"）。
file_path (Path) -- エラーが発生したファイルのパス。
exc (BaseException) -- 発生した例外オブジェクト。
- 戻り値:
None