torchとctranslate2のインポートをガードし、安全なデフォルトを提供。型注釈とdocstringを追加して可読性を向上。ログ設定の重複ハンドラ追加を防ぐチェックを導入。encodeBase64はデコード失敗時に空辞書を返すように変更。getComputeDeviceListはGPU情報取得失敗時にCPU情報を返すように例外保護を追加。

src-python/docs/modules/utils.md

@@ -1,3 +1,61 @@
+## utils モジュール（src-python/utils.py）
+
+このドキュメントは `src-python/utils.py` に対する最近のリファクタ内容、公開 API、利用上の注意点、テスト方法をまとめたものです。
+
+### 概要
+- `utils.py` はプロジェクト全体で使われる汎用ユーティリティ群を提供します。主な内容:
+  - ネットワーク接続チェック (`isConnectedNetwork`)
+  - ソケットの空きポート確認 (`isAvailableWebSocketServer`)
+  - IP アドレス検証 (`isValidIpAddress`)
+  - 計算デバイス一覧取得 (`getComputeDeviceList` / `getBestComputeType`)
+  - Base64 デコード (JSON) (`encodeBase64`)
+  - ロガー設定/ログ出力ヘルパー (`setupLogger`, `printLog`, `printResponse`, `errorLogging`)
+
+### 今回のリファクタ（要点）
+- Optional 依存へのフォールバック: `torch` と `ctranslate2` が存在しない環境でも動作するよう、import をガードし、安全なデフォルトを返す実装にしました。
+- 型注釈と docstring を追加して可読性を向上させました。
+- ログ設定の重複ハンドラ追加を防ぐチェックを導入しました。
+- `encodeBase64` はデコード失敗時に例外を投げず空辞書を返すように（安全側）変更しました。
+- `getComputeDeviceList` は GPU 情報取得で失敗しても CPU 情報を返すように例外保護を行いました。
+
+### 重要な利用上の注意（breaking/behavior changes）
+- Optional 依存
+  - `torch` が無い環境では GPU 情報は取得できません（`getComputeDeviceList` は CPU エントリのみ返します）。
+  - `ctranslate2` の `get_supported_compute_types` が無い場合は空リストを返します。
+  → 環境に依存する挙動を想定して、呼び出し側は存在チェックやフォールバックを実装してください。
+
+- `encodeBase64` の挙動
+  - 不正な base64/JSON を入力した場合、例外を投げず `{}` を返します。既存コードが例外を期待している場合は注意してください。
+
+- `isAvailableWebSocketServer` の仕様
+  - 指定した host:port に対して bind が成功すれば True を返します（「使用中かどうか」を判定する用途と逆の意味合いになることがあるため注意）。
+
+- ロギング
+  - `setupLogger` は同じログファイルに対するハンドラを重複して追加しません。`errorLogging()` はログ書き込みに失敗した場合でも最後に trace を stdout に出力するフォールバックがあります。
+
+### API 使い方（短い例）
+
+```python
+from utils import getComputeDeviceList, encodeBase64, printResponse
+
+devices = getComputeDeviceList()
+print(devices)
+
+obj = encodeBase64('eyAia2V5IjogInZhbHVlIiB9')  # -> {'key': 'value'}
+
+printResponse(200, '/health', {'status': 'ok'})
+```
+
+### テスト方針
+- optional 依存の違いを扱うため、ユニットテストは `torch` と `ctranslate2` をモックして行うことを推奨します。
+- 例: `getComputeDeviceList()` は GPU がない環境でも CPU のエントリを返すことを確認するテスト。
+
+### トラブルシュート
+- ログファイルの書き込みエラー: 権限やディスク容量を確認してください。`error.log` と `process.log` の存在と権限をチェックします。
+- `getComputeDeviceList()` が空しか返さない場合、`torch` または `ctranslate2` のインストールを確認してください。
+
+### 変更履歴
+- 2025-10-09: 型注釈・docstring 追加、optional import ガード、ロギング堅牢化。
 # utils.py — 関数一覧と使用例
 目的: 共通ユーティリティ（ログ、JSON 出力、ネットワーク/ポート検査、デバイス/計算タイプ列挙、バリデーション等）を提供します。