ENH: add support for error messages with hints

src/idefix_cli/_commands/run.py

@@ -276,8 +276,8 @@ def command(
     exe = d / "idefix"
     if not exe.is_file() and not (d / "Makefile").is_file():
         print_error(
-            f"No idefix executable or Makefile found in the target directory {d} "
-            "Run `idfx conf` first"
+            f"No idefix executable or Makefile found in the target directory {d}\n",
+            hint="Run `idfx conf` first",
         )
         return 1
 

src/idefix_cli/_theme.py

@@ -13,20 +13,23 @@ class Theme(TypedDict):
     SUCCESS: str
     WARNING: str
     ERROR: str
+    HINT: str
 
 
 Default = Theme(
     LAUNCH=unicodedata.lookup("ROCKET"),  # 🚀
     SUCCESS=unicodedata.lookup("PARTY POPPER"),  # 🎉
     WARNING=unicodedata.lookup("HEAVY EXCLAMATION MARK SYMBOL"),  # ❗
     ERROR=unicodedata.lookup("COLLISION SYMBOL"),  # 💥
+    HINT=unicodedata.lookup("LEFT-POINTING MAGNIFYING GLASS"),  # 🔍
 )
 
 Baballe = Theme(
     LAUNCH=unicodedata.lookup("GUIDE DOG"),  # 🦮
     SUCCESS=unicodedata.lookup("POODLE"),  # 🐩
     WARNING=unicodedata.lookup("PAW PRINTS"),  # 🐾
     ERROR=unicodedata.lookup("HOT DOG"),  # 🌭
+    HINT=unicodedata.lookup("CRYSTAL BALL"),  # 🔮
 )
 
 
@@ -43,5 +46,5 @@ def set_theme(theme: Literal["default", "baballe"]) -> None:
         assert_never(theme)
 
 
-def get_symbol(key: Literal["LAUNCH", "SUCCESS", "WARNING", "ERROR"]) -> str:
+def get_symbol(key: Literal["LAUNCH", "SUCCESS", "WARNING", "ERROR", "HINT"]) -> str:
     return THEME[key]

src/idefix_cli/lib.py

@@ -122,12 +122,13 @@ def print_err(message: str) -> None:
     print_error(message)
 
 
-def print_error(message: str) -> None:
+def print_error(message: str, *, hint: str | None = None) -> None:
     """Print a fatal error message to stderr.
     Normally followed by `return 1`.
 
     Args:
         message (str): the error message
+        hint (str): hint at a potential solution (optional)
 
     Returns:
         None
@@ -140,7 +141,17 @@ def print_error(message: str) -> None:
         ...    return 0
     """
     cprint(get_symbol("ERROR"), end=" ", file=sys.stderr)
-    cprint(message, color="red", attrs=["bold"], file=sys.stderr)
+    cprint(
+        message,
+        color="red",
+        attrs=["bold"],
+        file=sys.stderr,
+        end="\n" if hint is None else "",
+    )
+    if hint is None:
+        return
+    cprint(get_symbol("HINT"), end=" ", file=sys.stderr)
+    cprint(hint, color="magenta", attrs=["underline"], file=sys.stderr)
 
 
 def print_warning(message: str) -> None: