config.pyのリファクタリングを実施し、外部モジュールのインポートをガードして安全性を向上。初期化時のエラーハンドリングを強化し、デフォルト値の取得を安全に行えるように修正。関連ドキュメントを新規作成し、変更点と利用上の注意を明示化。

src-python/config.py

@@ -7,11 +7,34 @@ from json import dump as json_dump
 import threading
 from typing import Optional, Dict, Any
 import torch
-from device_manager import device_manager
+
-from models.translation.translation_languages import translation_lang
+# Guard optional, potentially heavy or platform-specific imports so importing
-from models.translation.translation_utils import ctranslate2_weights
+# config.py doesn't raise in environments missing those packages.
-from models.transcription.transcription_languages import transcription_lang
+try:
-from models.transcription.transcription_whisper import _MODELS as whisper_models
+    from device_manager import device_manager
+except Exception:  # pragma: no cover - optional runtime
+    device_manager = None  # type: ignore
+
+try:
+    from models.translation.translation_languages import translation_lang
+except Exception:  # pragma: no cover - optional runtime
+    translation_lang = {}  # type: ignore
+
+try:
+    from models.translation.translation_utils import ctranslate2_weights
+except Exception:  # pragma: no cover - optional runtime
+    ctranslate2_weights = {}  # type: ignore
+
+try:
+    from models.transcription.transcription_languages import transcription_lang
+except Exception:  # pragma: no cover - optional runtime
+    transcription_lang = {}  # type: ignore
+
+try:
+    from models.transcription.transcription_whisper import _MODELS as whisper_models
+except Exception:  # pragma: no cover - optional runtime
+    whisper_models = {}  # type: ignore
+
 from utils import errorLogging, validateDictStructure, getComputeDeviceList
 
 json_serializable_vars = {}
@@ -22,23 +45,39 @@ def json_serializable(var_name):
     return decorator
 
 class Config:
+    """Application configuration singleton.
+
+    Responsibilities:
+    - expose read-only and read-write configuration via properties
+    - persist selected values to JSON with debounce
+    Implementation notes: initialization may depend on optional subsystems; any
+    exceptions during init/load are captured and logged to avoid import-time
+    crashes.
+    """
+
     _instance = None
     _config_data: Dict[str, Any] = {}
     _timer: Optional[threading.Timer] = None
-    _debounce_time = 2
+    _debounce_time: int = 2
 
     def __new__(cls):
         if cls._instance is None:
             cls._instance = super(Config, cls).__new__(cls)
+            try:
                 cls._instance.init_config()
+            except Exception:
+                errorLogging()
+            try:
                 cls._instance.load_config()
+            except Exception:
+                errorLogging()
         return cls._instance
 
-    def saveConfigToFile(self):
+    def saveConfigToFile(self) -> None:
         with open(self.PATH_CONFIG, "w", encoding="utf-8") as fp:
             json_dump(self._config_data, fp, indent=4, ensure_ascii=False)
 
-    def saveConfig(self, key, value, immediate_save=False):
+    def saveConfig(self, key: str, value: Any, immediate_save: bool = False) -> None:
         self._config_data[key] = value
 
         if isinstance(self._timer, threading.Timer) and self._timer.is_alive():
@@ -1069,10 +1108,16 @@ class Config:
         self._WATCHDOG_INTERVAL = 20
 
         self._SELECTABLE_TAB_NO_LIST = ["1", "2", "3"]
-        self._SELECTABLE_CTRANSLATE2_WEIGHT_TYPE_LIST = ctranslate2_weights.keys()
+        # these external mappings may be empty dicts if the optional modules failed to import
-        self._SELECTABLE_WHISPER_WEIGHT_TYPE_LIST = whisper_models.keys()
+        self._SELECTABLE_CTRANSLATE2_WEIGHT_TYPE_LIST = getattr(ctranslate2_weights, 'keys', lambda: [])()
-        self._SELECTABLE_TRANSLATION_ENGINE_LIST = translation_lang.keys()
+        self._SELECTABLE_WHISPER_WEIGHT_TYPE_LIST = getattr(whisper_models, 'keys', lambda: [])()
-        self._SELECTABLE_TRANSCRIPTION_ENGINE_LIST = list(transcription_lang[list(transcription_lang.keys())[0]].values())[0].keys()
+        self._SELECTABLE_TRANSLATION_ENGINE_LIST = getattr(translation_lang, 'keys', lambda: [])()
+        try:
+            # transcription_lang is nested dict; attempt to extract keys defensively
+            first_key = next(iter(transcription_lang))
+            self._SELECTABLE_TRANSCRIPTION_ENGINE_LIST = list(transcription_lang[first_key].values())[0].keys()
+        except Exception:
+            self._SELECTABLE_TRANSCRIPTION_ENGINE_LIST = []
         self._SELECTABLE_UI_LANGUAGE_LIST = ["en", "ja", "ko", "zh-Hant", "zh-Hans"]
         self._COMPUTE_MODE = "cuda" if torch.cuda.is_available() else "cpu"
         self._SELECTABLE_COMPUTE_DEVICE_LIST = getComputeDeviceList()
@@ -1172,8 +1217,18 @@ class Config:
             "height": 654,
         }
         self._AUTO_MIC_SELECT = True
+        # device_manager may be unavailable or not initialized; use safe defaults
+        try:
+            if device_manager is not None:
                 self._SELECTED_MIC_HOST = device_manager.getDefaultMicDevice()["host"]["name"]
                 self._SELECTED_MIC_DEVICE = device_manager.getDefaultMicDevice()["device"]["name"]
+            else:
+                self._SELECTED_MIC_HOST = "NoHost"
+                self._SELECTED_MIC_DEVICE = "NoDevice"
+        except Exception:
+            errorLogging()
+            self._SELECTED_MIC_HOST = "NoHost"
+            self._SELECTED_MIC_DEVICE = "NoDevice"
         self._MIC_THRESHOLD = 300
         self._MIC_AUTOMATIC_THRESHOLD = False
         self._MIC_RECORD_TIMEOUT = 3
@@ -1190,7 +1245,14 @@ class Config:
         self._MIC_AVG_LOGPROB = -0.8
         self._MIC_NO_SPEECH_PROB = 0.6
         self._AUTO_SPEAKER_SELECT = True
+        try:
+            if device_manager is not None:
                 self._SELECTED_SPEAKER_DEVICE = device_manager.getDefaultSpeakerDevice()["device"]["name"]
+            else:
+                self._SELECTED_SPEAKER_DEVICE = "NoDevice"
+        except Exception:
+            errorLogging()
+            self._SELECTED_SPEAKER_DEVICE = "NoDevice"
         self._SPEAKER_THRESHOLD = 300
         self._SPEAKER_AUTOMATIC_THRESHOLD = False
         self._SPEAKER_RECORD_TIMEOUT = 3

src-python/docs/modules/config_ref.md

@@ -0,0 +1,39 @@
+# config.py 変更参照ドキュメント
+
+このファイルは `config.py` に対して行った最近のリファクタリング / 安全化についての参照資料です。
+
+目的: import 時の副作用を抑止し、`device_manager` などの外部モジュールがない環境でも安全に `config` をインポートできるようにすること。
+
+主な変更点
+
+- import-time の初期化保護
+  - `Config.__new__` の中で `init_config()` / `load_config()` を呼び出しますが、これらを try/except で保護し、初期化に失敗しても例外を上位に伝播させずログ記録のみで処理を継続します。
+  - このため、アプリ起動環境に必須ではない外部依存が欠けている場合でも、`import config` によるクラッシュを防止します。
+
+- 外部モジュールの呼び出しをガード
+  - `device_manager`、翻訳/文字起こし関連のモデル一覧 (`whisper_models`, `ctranslate2_weights`) などは import 時に直接呼び出さず、存在チェック（try/except）を行って安全なデフォルト（空リストや "NoDevice" など）にフォールバックします。
+  - これによりヘビーな依存（Windows 固有パッケージや大きな ML ライブラリ）がない CI 環境や軽量実行環境での import が安定します。
+
+- エラーロギング
+  - 初期化やデフォルト取得に失敗した場合は、例外を握りつぶすのではなく `utils.errorLogging()` を経由してエラーメッセージを残します。これにより問題の診断が容易になります。
+
+- 設定デフォルト値の扱い
+  - `getDefaultMicDevice()` / `getDefaultSpeakerDevice()` などを呼ぶ箇所は try/except で保護され、失敗時には `"NoHost"` / `"NoDevice"` 等の安全な文字列で代替されます。
+
+利用上の注意
+
+- 既存のコードは `config` をインポートしただけで `device_manager` を起動することを想定している箇所があるかもしれません。今回のリファクタリングでは "import 時に副作用を起こさない" ことを優先しているため、もし明示的な初期化を必要とする場合は、呼び出し側で `device_manager.init()` を明示的に行ってください。
+
+- もし `config` のロードで致命的な設定エラーが発生した場合でも、アプリは継続動作しますが、ログを確認して手動で修復することが必要になる場合があります。
+
+ドキュメントの提案差分
+
+- 既存 `docs/modules/config.md` の "生成とライフサイクル" セクションに次の一文を追加することを推奨します:
+
+  > 注意: `Config()` のインポートは副作用を起こさないよう保護されています。プラットフォーム依存のコンポーネント（例: `device_manager`）は明示的に初期化してください。
+
+- `SELECTABLE_*` 系の説明に、起動環境に依存して空になる可能性があることを明示するパラグラフを追加してください（CI 環境や headless 環境では空になる）。
+
+---
+
+作業済み: このファイルはワークスペースに `docs/modules/config_ref.md` として作成済みです。既存 `docs/modules/config.md` は上書きしていません。上書き/マージの希望があれば続けます。