Rename to should_require_reset

qt/aqt/gui_hooks.py

@@ -1737,28 +1737,44 @@ class _MainWindowDidInitHook:
 main_window_did_init = _MainWindowDidInitHook()
 
 
-class _MainWindowWillRequireResetFilter:
+class _MainWindowShouldRequireResetFilter:
     """Executed before the main window will require a reset
-        
+
         This hook can be used to change the behavior of the main window,
         when other dialogs, like the AddCards or Browser, require a reset
         from the main window.
+        If you decide to use this hook, make you sure you check the reason for the reset.
+        Some reasons require more attention than others, and skipping important ones might
+        put the main window into an invalid state (e.g. display a deleted note).
         """
 
-    _hooks: List[Callable[[bool, str, Optional[Any]], bool]] = []
+    _hooks: List[
+        Callable[[bool, "Union[aqt.main.ResetReason, str]", Optional[Any]], bool]
+    ] = []
 
-    def append(self, cb: Callable[[bool, str, Optional[Any]], bool]) -> None:
+    def append(
-        """(will_reset: bool, reason: str, context: Optional[Any])"""
+        self,
+        cb: Callable[[bool, "Union[aqt.main.ResetReason, str]", Optional[Any]], bool],
+    ) -> None:
+        """(will_reset: bool, reason: Union[aqt.main.ResetReason, str], context: Optional[Any])"""
         self._hooks.append(cb)
 
-    def remove(self, cb: Callable[[bool, str, Optional[Any]], bool]) -> None:
+    def remove(
+        self,
+        cb: Callable[[bool, "Union[aqt.main.ResetReason, str]", Optional[Any]], bool],
+    ) -> None:
         if cb in self._hooks:
             self._hooks.remove(cb)
 
     def count(self) -> int:
         return len(self._hooks)
 
-    def __call__(self, will_reset: bool, reason: str, context: Optional[Any]) -> bool:
+    def __call__(
+        self,
+        will_reset: bool,
+        reason: Union[aqt.main.ResetReason, str],
+        context: Optional[Any],
+    ) -> bool:
         for filter in self._hooks:
             try:
                 will_reset = filter(will_reset, reason, context)
@@ -1769,7 +1785,7 @@ class _MainWindowWillRequireResetFilter:
         return will_reset
 
 
-main_window_will_require_reset = _MainWindowWillRequireResetFilter()
+main_window_should_require_reset = _MainWindowShouldRequireResetFilter()
 
 
 class _MediaSyncDidProgressHook:

qt/aqt/main.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import enum
 import faulthandler
 import gc
 import os
@@ -68,6 +69,10 @@ from aqt.utils import (
 install_pylib_legacy()
 
 
+class ResetReason(enum.Enum):
+    pass
+
+
 class ResetRequired:
     def __init__(self, mw: AnkiQt):
         self.mw = mw
@@ -688,7 +693,7 @@ from the profile screen."
         "Signal queue needs to be rebuilt when edits are finished or by user."
         self.autosave()
         self.resetModal = modal
-        if gui_hooks.main_window_will_require_reset(
+        if gui_hooks.main_window_should_require_reset(
             self.interactiveState(), reason, context
         ):
             self.moveToState("resetRequired")

qt/tools/genhooks_gui.py

@@ -441,14 +441,21 @@ hooks = [
         """,
     ),
     Hook(
-        name="main_window_will_require_reset",
+        name="main_window_should_require_reset",
-        args=["will_reset: bool", "reason: str", "context: Optional[Any]"],
+        args=[
+            "will_reset: bool",
+            "reason: Union[aqt.main.ResetReason, str]",
+            "context: Optional[Any]",
+        ],
         return_type="bool",
         doc="""Executed before the main window will require a reset
-        
+
         This hook can be used to change the behavior of the main window,
         when other dialogs, like the AddCards or Browser, require a reset
         from the main window.
+        If you decide to use this hook, make you sure you check the reason for the reset.
+        Some reasons require more attention than others, and skipping important ones might
+        put the main window into an invalid state (e.g. display a deleted note).
         """,
     ),
     Hook(name="backup_did_complete"),