Refactor status texts + show help tooltips on some statuses

Author: prandla

cms/db/submission.py

@@ -326,8 +326,7 @@ class SubmissionResult(Base):
         nullable=True)
 
     # The output from the sandbox (to allow localization the first item
-    # of the list is a format string, possibly containing some "%s",
-    # that will be filled in using the remaining items of the list).
+    # of the list is a message ID, and the rest are format parameters).
     compilation_text: list[str] = Column(
         ARRAY(String),
         nullable=False,
@@ -758,9 +757,8 @@ class Evaluation(Base):
         nullable=True)
 
     # The output from the grader, usually "Correct", "Time limit", ...
-    # (to allow localization the first item of the list is a format
-    # string, possibly containing some "%s", that will be filled in
-    # using the remaining items of the list).
+    # (to allow localization the first item of the list is a message ID, and
+    # the rest are format parameters).
     text: list[str] = Column(
         ARRAY(String),
         nullable=False,

cms/db/usertest.py

@@ -276,8 +276,7 @@ class UserTestResult(Base):
         nullable=True)
 
     # The output from the sandbox (to allow localization the first item
-    # of the list is a format string, possibly containing some "%s",
-    # that will be filled in using the remaining items of the list).
+    # of the list is a message ID, and the rest are format parameters).
     compilation_text: list[str] = Column(
         ARRAY(String),
         nullable=False,

cms/grading/__init__.py

@@ -25,6 +25,9 @@
 
 import logging
 
+from markupsafe import Markup, escape
+
+from cms.grading.steps.messages import MESSAGE_REGISTRY
 from cms.locale import DEFAULT_TRANSLATION, Translation
 from .language import Language, CompiledLanguage
 
@@ -61,9 +64,10 @@ def format_status_text(
 
     A status text is the content of SubmissionResult.compilation_text,
     Evaluation.text and UserTestResult.(compilation|evaluation)_text.
-    It is a list whose first element is a string with printf-like
-    placeholders and whose other elements are the data to use to fill
-    them.
+    It is a list whose first element is a message ID identifying a
+    MessageCollection and a message in it, and whose other elements are the
+    data to use to fill them. If the message ID begins with "custom:", it is
+    used as a string directly without attempting to look up a message.
     The first element will be translated using the given translator (or
     the identity function, if not given), completed with the data and
     returned.
@@ -78,9 +82,21 @@ def format_status_text(
         if not isinstance(status, list):
             raise TypeError("Invalid type: %r" % type(status))
 
-        # The empty msgid corresponds to the headers of the pofile.
-        text = _(status[0]) if status[0] != '' else ''
-        return text % tuple(status[1:])
+        if status[0] == '':
+            return ''
+        elif status[0].startswith("custom:"):
+            return status[0].removeprefix("custom:") % tuple(status[1:])
+        else:
+            message = MESSAGE_REGISTRY.get(status[0])
+            msg_text = _(message.message) % tuple(status[1:])
+            if message.inline_help:
+                # XXX: is this the best place for this?
+                help = Markup(
+                    f' <i class="icon-question-sign" title="{escape(message.help_text)}"></i>'
+                )
+                return msg_text + help
+            else:
+                return msg_text
     except Exception:
         logger.error("Unexpected error when formatting status "
                      "text: %r", status, exc_info=True)

cms/grading/scoretypes/abc.py

@@ -37,7 +37,6 @@
 
 from cms import FEEDBACK_LEVEL_RESTRICTED
 from cms.db import SubmissionResult
-from cms.grading.steps import EVALUATION_MESSAGES
 from cms.locale import Translation, DEFAULT_TRANSLATION
 from cms.server.jinja2_toolbox import GLOBAL_ENVIRONMENT
 from jinja2 import Template
@@ -469,7 +468,7 @@ def compute_score(self, submission_result):
                     tc_score, parameter)
 
                 time_limit_was_exceeded = False
-                if evaluations[tc_idx].text == [EVALUATION_MESSAGES.get("timeout").message]:
+                if evaluations[tc_idx].text == ["evaluation:timeout"]:
                     time_limit_was_exceeded = True
 
                 testcases.append({

cms/grading/steps/compilation.py

@@ -42,7 +42,7 @@ def N_(message: str):
     return message
 
 
-COMPILATION_MESSAGES = MessageCollection([
+COMPILATION_MESSAGES = MessageCollection("compilation", [
     HumanMessage("success",
                  N_("Compilation succeeded"),
                  N_("Your submission successfully compiled to an "
@@ -54,17 +54,20 @@ def N_(message: str):
                  N_("Compilation timed out"),
                  N_("Your submission exceeded the time limit while compiling. "
                     "This might be caused by an excessive use of C++ "
-                    "templates, for example.")),
+                    "templates, for example."),
+                 inline_help=True),
     HumanMessage("memorylimit",
                  N_("Compilation memory limit exceeded"),
                  N_("Your submission exceeded the memory limit while compiling. "
                     "This might be caused by an excessive use of C++ "
-                    "templates, or too large global variables, for example.")),
+                    "templates, or too large global variables, for example."),
+                 inline_help=True),
     HumanMessage("signal",
                  N_("Compilation killed with signal %s"),
                  N_("Your submission was killed with the specified signal. "
                     "This might be caused by a bug in the compiler, "
-                    "for example.")),
+                    "for example."),
+                 inline_help=True),
 ])
 
 
@@ -89,8 +92,9 @@ def compilation_step(
             executable, False if not, None if success is False;
         * text: a human readable, localized message to inform contestants
             of the status; it is either an empty list (for no message) or a
-            list of strings were the second to the last are formatting
-            arguments for the first, or None if success is False;
+            list of strings were the first is a message ID and the rest are
+            format arguments for that message, if the message takes any; or
+            None if success is False;
         * stats: a dictionary with statistics about the compilation, or None
             if success is False.
 
@@ -121,37 +125,37 @@ def compilation_step(
     if exit_status == Sandbox.EXIT_OK:
         # Execution finished successfully and the executable was generated.
         logger.debug("Compilation successfully finished.")
-        text = [COMPILATION_MESSAGES.get("success").message]
+        text = ["compilation:success"]
         return True, True, text, stats
 
     elif exit_status == Sandbox.EXIT_NONZERO_RETURN:
         # Error in compilation: no executable was generated, and we return
         # an error to the user.
         logger.debug("Compilation failed.")
-        text = [COMPILATION_MESSAGES.get("fail").message]
+        text = ["compilation:fail"]
         return True, False, text, stats
 
     elif exit_status == Sandbox.EXIT_TIMEOUT or \
             exit_status == Sandbox.EXIT_TIMEOUT_WALL:
         # Timeout: we assume it is the user's fault, and we return the error
         # to them.
         logger.debug("Compilation timed out.")
-        text = [COMPILATION_MESSAGES.get("timeout").message]
+        text = ["compilation:timeout"]
         return True, False, text, stats
 
     elif exit_status == Sandbox.EXIT_MEM_LIMIT:
         # Memory limit: we assume it is the user's fault, and we return the
         # error to them.
         logger.debug("Compilation memory limit exceeded.")
-        text = [COMPILATION_MESSAGES.get("memorylimit").message]
+        text = ["compilation:memorylimit"]
         return True, False, text, stats
 
     elif exit_status == Sandbox.EXIT_SIGNAL:
         # Terminated by signal: we assume again it is the user's fault, and
         # we return the error to them.
         signal = stats["signal"]
         logger.debug("Compilation killed with signal %s.", signal)
-        text = [COMPILATION_MESSAGES.get("signal").message, str(signal)]
+        text = ["compilation:signal", str(signal)]
         return True, False, text, stats
 
     elif exit_status == Sandbox.EXIT_SANDBOX_ERROR:

cms/grading/steps/evaluation.py

@@ -42,7 +42,7 @@ def N_(message: str):
     return message
 
 
-EVALUATION_MESSAGES = MessageCollection([
+EVALUATION_MESSAGES = MessageCollection("evaluation", [
     HumanMessage("success",
                  N_("Output is correct"),
                  N_("Your submission ran and gave the correct answer")),
@@ -56,27 +56,38 @@ def N_(message: str):
     HumanMessage("nooutput",
                  N_("Evaluation didn't produce file %s"),
                  N_("Your submission ran, but did not write on the "
-                    "correct output file")),
+                    "correct output file"),
+                 inline_help=True),
     HumanMessage("timeout",
                  N_("Execution timed out"),
-                 N_("Your submission used too much CPU time.")),
+                 N_("Your submission used too much CPU time."),
+                 inline_help=True),
     HumanMessage("walltimeout",
                  N_("Execution timed out (wall clock limit exceeded)"),
                  N_("Your submission used too much total time. This might "
                     "be triggered by undefined code, or buffer overflow, "
                     "for example. Note that in this case the CPU time "
                     "visible in the submission details might be much smaller "
-                    "than the time limit.")),
+                    "than the time limit."),
+                 inline_help=True),
     HumanMessage("memorylimit",
                  N_("Memory limit exceeded"),
-                 N_("Your submission used too much memory.")),
+                 N_("Your submission used too much memory."),
+                 inline_help=True),
     HumanMessage("signal",
                  N_("Execution killed by signal"),
-                 N_("The evaluation was killed by a signal.")),
+                 N_("The evaluation was killed by a signal."),
+                 inline_help=True),
     HumanMessage("returncode",
                  N_("Execution failed because the return code was nonzero"),
                  N_("Your submission failed because it exited with a return "
-                    "code different from 0.")),
+                    "code different from 0."),
+                 inline_help=True),
+])
+# This message is stored separately because we don't want to show it on the help page.
+EXECUTION_MESSAGES = MessageCollection("execution", [
+    HumanMessage("success", N_("Execution completed successfully"), ""),
+    # all other user test messages are shared with the regular evaluation messages.
 ])
 
 
@@ -270,27 +281,26 @@ def human_evaluation_message(stats: StatsDict) -> list[str]:
 
     stats: execution statistics for an evaluation step.
 
-    return: a list of strings composing the message (where
-        strings from the second to the last are formatting arguments for the
-        first); or an empty list if no message should be passed to
-        contestants.
+    return: a list of strings composing the message (where the first is a message
+        ID and the rest are format arguments for the message); or an empty list
+        if no message should be passed to contestants.
 
     """
     exit_status = stats['exit_status']
     if exit_status == Sandbox.EXIT_TIMEOUT:
-        return [EVALUATION_MESSAGES.get("timeout").message]
+        return ["evaluation:timeout"]
     elif exit_status == Sandbox.EXIT_TIMEOUT_WALL:
-        return [EVALUATION_MESSAGES.get("walltimeout").message]
+        return ["evaluation:walltimeout"]
     elif exit_status == Sandbox.EXIT_SIGNAL:
-        return [EVALUATION_MESSAGES.get("signal").message]
+        return ["evaluation:signal"]
     elif exit_status == Sandbox.EXIT_SANDBOX_ERROR:
         # Contestants won't see this, the submission will still be evaluating.
         return []
     elif exit_status == Sandbox.EXIT_MEM_LIMIT:
-        return [EVALUATION_MESSAGES.get("memorylimit").message]
+        return ["evaluation:memorylimit"]
     elif exit_status == Sandbox.EXIT_NONZERO_RETURN:
         # Don't tell which code: would be too much information!
-        return [EVALUATION_MESSAGES.get("returncode").message]
+        return ["evaluation:returncode"]
     elif exit_status == Sandbox.EXIT_OK:
         return []
     else:

cms/grading/steps/messages.py

@@ -37,28 +37,31 @@ class HumanMessage:
 
     """
 
-    def __init__(self, shorthand: str, message: str, help_text: str):
+    def __init__(self, shorthand: str, message: str, help_text: str, inline_help: bool = False):
         """Initialization.
 
         shorthand: what to call this message in the code.
         message: the message itself.
         help_text: a longer explanation for the help page.
+        inline_help: Whether to show a help tooltip for this message whenever it is shown.
 
         """
         self.shorthand = shorthand
         self.message = message
         self.help_text = help_text
+        self.inline_help = inline_help
 
 
 class MessageCollection:
     """Represent a collection of messages, with error checking."""
 
-    def __init__(self, messages: list[HumanMessage] | None = None):
+    def __init__(self, namespace: str, messages: list[HumanMessage] | None = None):
         self._messages: dict[str, HumanMessage] = {}
         self._ordering: list[str] = []
         if messages is not None:
             for message in messages:
                 self.add(message)
+        MESSAGE_REGISTRY.add(namespace, self)
 
     def add(self, message: HumanMessage):
         if message.shorthand in self._messages:
@@ -81,3 +84,28 @@ def all(self) -> list[HumanMessage]:
         for shorthand in self._ordering:
             ret.append(self._messages[shorthand])
         return ret
+
+class MessageRegistry:
+    """Represents a collection of message collections, organized by a namespace
+    prefix. This is a singleton that is automatically populated by
+    MessageCollection."""
+
+    def __init__(self):
+        self._namespaces: dict[str, MessageCollection] = {}
+
+    def add(self, namespace: str, collection: MessageCollection):
+        if namespace in self._namespaces:
+            logger.error(f"Trying to register duplicate namespace {namespace}")
+            return
+        self._namespaces[namespace] = collection
+
+    def get(self, message_id: str) -> HumanMessage:
+        if ':' not in message_id:
+            raise KeyError(f"Invalid message ID {message_id}")
+        namespace, message = message_id.split(':', 1)
+        if namespace not in self._namespaces:
+            raise KeyError(f"Message namespace {namespace} not found")
+        collection = self._namespaces[namespace]
+        return collection.get(message)
+
+MESSAGE_REGISTRY = MessageRegistry()

cms/grading/steps/trusted.py

@@ -41,7 +41,6 @@
 
 from cms import config
 from cms.grading.Sandbox import Sandbox
-from .evaluation import EVALUATION_MESSAGES
 from .utils import generic_step
 from .stats import StatsDict
 
@@ -136,13 +135,15 @@ def extract_outcome_and_text(sandbox: Sandbox) -> tuple[float, list[str], str |
     # If the text starts with translate, the manager is asking us to
     # use a stock message, that can be translated.
     if text.startswith("translate:"):
-        remaining = text[len("translate:"):].strip()
+        remaining = text.removeprefix("translate:").strip()
         if remaining in ["success", "partial", "wrong"]:
-            text = EVALUATION_MESSAGES.get(remaining).message
+            text = "evaluation:" + remaining
         else:
             remaining = remaining[:15]  # to avoid logging lots of text
             logger.warning("Manager asked to translate text, but string "
                            "'%s' is not recognized." % remaining)
+    else:
+        text = "custom:" + text
 
     return outcome, [text], admin_text
 

cms/grading/steps/whitediff.py

@@ -30,8 +30,6 @@
 
 from cms.grading.Sandbox import Sandbox
 
-from .evaluation import EVALUATION_MESSAGES
-
 
 logger = logging.getLogger(__name__)
 
@@ -143,9 +141,9 @@ def white_diff_fobj_step(
     """
     correct, admin_text = _white_diff(output_fobj, correct_output_fobj)
     if correct:
-        return 1.0, [EVALUATION_MESSAGES.get("success").message], admin_text
+        return 1.0, ["evaluation:success"], admin_text
     else:
-        return 0.0, [EVALUATION_MESSAGES.get("wrong").message], admin_text
+        return 0.0, ["evaluation:wrong"], admin_text
 
 
 def white_diff_step(
@@ -169,5 +167,4 @@ def white_diff_step(
                 sandbox.get_file(correct_output_filename) as res_file:
             return white_diff_fobj_step(out_file, res_file)
     else:
-        return 0.0, [
-            EVALUATION_MESSAGES.get("nooutput").message, output_filename], None
+        return 0.0, ["evaluation:nooutput", output_filename], None