exception_handler#

Centralised GUI exception handling for ClearMap.

Usage#

From any tab or controller:

from ClearMap.gui.exception_handler import handle_exception

try:
    worker.run()
except ClearMapException as exc:
    action = handle_exception(exc, parent=self.main_window)
    if action == 'retry':
        ...
    elif action == 'reset_workspace':
        self.main_window.trigger_workspace_reset()

At application startup:

from ClearMap.gui.exception_handler import install_global_handler
install_global_handler(app, parent_getter=lambda: gui.window)
class ExceptionDialog(exc: ClearMapException, parent: QWidget | None = None, context: str = '')[source]#

Bases: QDialog

Modal dialog that presents a ClearMapException to the user. After exec_(), read chosen_action for the action string corresponding to the RecoveryOption the user clicked.

handle_exception(exc: Exception, parent: QWidget | None = None, context: str = '') → str[source]#

Show an exception dialog and return the chosen action string. For non-ClearMap exceptions a generic FATAL dialog is shown.

Parameters:

  • exc – The exception to present.

  • parent – Parent widget for the dialog (centres it on the parent window).

  • context – Optional extra line (e.g. "CellCounterTab.detect_cells").

Returns

str

The action field of the chosen RecoveryOption, e.g. 'dismiss', 'retry', 'reset_workspace', 'close'.

install_global_handler(app: QApplication, parent_getter: Callable[[], ~PyQt5.QtWidgets.QWidget | None]=<function <lambda>>, on_reset: Callable[[], None] | None=None, on_close: Callable[[], None] | None=None) → None[source]#

Install a sys.excepthook that shows handle_exception().

Parameters:

  • app – The running QApplication.

  • parent_getter – Callable returning the current main window (or None).

  • on_reset – Callback for the 'reset_workspace' action. When None, falls back to app.quit().

  • on_close – Callback for the 'close' action. When None, calls app.quit().