QuizGenerator 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

QuizGenerator/question.py

@@ -15,10 +15,13 @@ import pprint
 import random
 import re
 import uuid
+import types
+import inspect
+from types import MappingProxyType
 
 import pypandoc
 import yaml
-from typing import List, Dict, Any, Tuple, Optional
+from typing import List, Dict, Any, Tuple, Optional, Mapping, MutableMapping
 import canvasapi.course, canvasapi.quiz
 
 import QuizGenerator.contentast as ca
@@ -58,6 +61,81 @@ class QuestionInstance:
     flags: RegenerationFlags
 
 
+@dataclasses.dataclass
+class QuestionContext:
+  rng_seed: Optional[int]
+  rng: random.Random
+  data: MutableMapping[str, Any] | Mapping[str, Any] = dataclasses.field(default_factory=dict)
+  frozen: bool = False
+  question_cls: type | None = None
+
+  def __getitem__(self, key: str) -> Any:
+    if key == "rng_seed":
+      return self.rng_seed
+    if key == "rng":
+      return self.rng
+    return self.data[key]
+
+  def __setitem__(self, key: str, value: Any) -> None:
+    if self.frozen:
+      raise TypeError("QuestionContext is frozen.")
+    if key == "rng_seed":
+      self.rng_seed = value
+      return
+    if key == "rng":
+      self.rng = value
+      return
+    if isinstance(self.data, MappingProxyType):
+      raise TypeError("QuestionContext is frozen.")
+    self.data[key] = value
+
+  def get(self, key: str, default: Any = None) -> Any:
+    if key == "rng_seed":
+      return self.rng_seed
+    if key == "rng":
+      return self.rng
+    return self.data.get(key, default)
+
+  def __contains__(self, key: object) -> bool:
+    if key in ("rng_seed", "rng"):
+      return True
+    return key in self.data
+
+  def __getattr__(self, name: str) -> Any:
+    if name in self.data:
+      return self.data[name]
+    if self.question_cls is not None and hasattr(self.question_cls, name):
+      raw_attr = inspect.getattr_static(self.question_cls, name)
+      if isinstance(raw_attr, staticmethod):
+        return raw_attr.__func__
+      if isinstance(raw_attr, classmethod):
+        return raw_attr.__func__.__get__(self.question_cls, self.question_cls)
+      attr = getattr(self.question_cls, name)
+      if callable(attr):
+        return types.MethodType(attr, self)
+      return attr
+    raise AttributeError(f"{type(self).__name__} has no attribute {name!r}")
+
+  def keys(self):
+    return self.data.keys()
+
+  def items(self):
+    return self.data.items()
+
+  def values(self):
+    return self.data.values()
+
+  def freeze(self) -> "QuestionContext":
+    frozen_data = MappingProxyType(dict(self.data))
+    return QuestionContext(
+      rng_seed=self.rng_seed,
+      rng=self.rng,
+      data=frozen_data,
+      frozen=True,
+      question_cls=self.question_cls,
+    )
+
+
 # Spacing presets for questions
 SPACING_PRESETS = {
     "NONE": 0,
@@ -262,7 +340,7 @@ class RegenerableChoiceMixin:
           self.register_choice('scheduler_kind', self.Kind, scheduler_kind, kwargs)
           super().__init__(**kwargs)
 
-      def _build_context(self, rng_seed=None, **kwargs):
+      def _build_context(cls, rng_seed=None, **kwargs):
           self.rng.seed(rng_seed)
           # Get the choice (randomly selected or from config_params)
           self.scheduler_algorithm = self.get_choice('scheduler_kind', self.Kind)
@@ -382,6 +460,7 @@ class RegenerableChoiceMixin:
         del choice_info['_temp_fixed_value']
 
 class Question(abc.ABC):
+  AUTO_ENTRY_WARNINGS = True
   """
   Base class for all quiz questions with cross-format rendering support.
 
@@ -438,6 +517,7 @@ class Question(abc.ABC):
 
   # Default version - subclasses should override this
   VERSION = "1.0"
+  FREEZE_CONTEXT = False
   
   class Topic(enum.Enum):
     # CST334 (Operating Systems) Topics
@@ -546,8 +626,10 @@ class Question(abc.ABC):
     """
     # Generate the question, retrying with incremented seeds until we get an interesting one
     base_seed = kwargs.get("rng_seed", None)
+    max_backoff_attempts = kwargs.get("max_backoff_attempts", None)
     build_kwargs = dict(kwargs)
     build_kwargs.pop("rng_seed", None)
+    build_kwargs.pop("max_backoff_attempts", None)
     # Include config params so build() implementations can access YAML-provided settings.
     build_kwargs = {**self.config_params, **build_kwargs}
 
@@ -561,6 +643,10 @@ class Question(abc.ABC):
       is_interesting = False
       ctx = None
       while not is_interesting:
+        if max_backoff_attempts is not None and backoff_counter >= max_backoff_attempts:
+          raise RuntimeError(
+            f"Exceeded max_backoff_attempts={max_backoff_attempts} for {self.__class__.__name__}"
+          )
         # Increment seed for each backoff attempt to maintain deterministic behavior
         current_seed = None if base_seed is None else base_seed + backoff_counter
         ctx = self._build_context(
@@ -573,7 +659,17 @@ class Question(abc.ABC):
       # Store the actual seed used and question metadata for QR code generation
       actual_seed = None if base_seed is None else base_seed + backoff_counter - 1
 
-      components = self.build(rng_seed=current_seed, context=ctx, **build_kwargs)
+      # Keep instance rng in sync for any legacy usage.
+      if isinstance(ctx, QuestionContext):
+        self.rng = ctx.rng
+      elif isinstance(ctx, dict) and "rng" in ctx:
+        self.rng = ctx["rng"]
+
+      components = self.__class__.build(
+        rng_seed=current_seed,
+        context=ctx,
+        **build_kwargs
+      )
 
       # Collect answers from explicit lists and inline AST
       inline_body_answers = self._collect_answers_from_ast(components.body)
@@ -584,6 +680,10 @@ class Question(abc.ABC):
 
       can_be_numerical = self._can_be_numerical_from_answers(answers)
 
+      if self.AUTO_ENTRY_WARNINGS:
+        warnings = self._entry_warnings_from_answers(answers)
+        components.body = self._append_entry_warnings(components.body, warnings)
+
       config_params = dict(self.config_params)
       if isinstance(ctx, dict) and ctx.get("_config_params"):
         config_params.update(ctx.get("_config_params"))
@@ -614,19 +714,27 @@ class Question(abc.ABC):
   def post_instantiate(self, instance, **kwargs):
     pass
    
-  def build(self, *, rng_seed=None, context=None, **kwargs) -> QuestionComponents:
+  @classmethod
+  def build(cls, *, rng_seed=None, context=None, **kwargs) -> QuestionComponents:
     """
     Build question content (body, answers, explanation) for a given seed.
 
     This should only generate content; metadata like points/spacing belong in instantiate().
     """
-    cls = self.__class__
     if context is None:
-      context = self._build_context(rng_seed=rng_seed, **kwargs)
+      context = cls._coerce_context(
+        cls._build_context(rng_seed=rng_seed, **kwargs),
+        rng_seed=rng_seed
+      )
+    else:
+      context = cls._coerce_context(context, rng_seed=rng_seed)
+
+    if cls.FREEZE_CONTEXT:
+      context = context.freeze()
 
     # Build body + explanation. Each may return just an Element or (Element, answers).
-    body, body_answers = cls._normalize_build_output(self._build_body(context))
-    explanation, explanation_answers = cls._normalize_build_output(self._build_explanation(context))
+    body, body_answers = cls._normalize_build_output(cls._build_body(context))
+    explanation, explanation_answers = cls._normalize_build_output(cls._build_explanation(context))
 
     # Collect inline answers from both body and explanation.
     inline_body_answers = cls._collect_answers_from_ast(body)
@@ -645,30 +753,48 @@ class Question(abc.ABC):
       explanation=explanation
     )
 
-  def _build_context(self, *, rng_seed=None, **kwargs):
+  @classmethod
+  def _coerce_context(cls, context, *, rng_seed=None) -> QuestionContext:
+    if isinstance(context, QuestionContext):
+      return context
+    if isinstance(context, dict):
+      ctx_seed = context.get("rng_seed", rng_seed)
+      rng = context.get("rng") or random.Random(ctx_seed)
+      ctx = QuestionContext(rng_seed=ctx_seed, rng=rng)
+      for key, value in context.items():
+        if key in ("rng_seed", "rng"):
+          continue
+        ctx.data[key] = value
+      return ctx
+    raise TypeError(f"Unsupported context type: {type(context)}")
+
+
+  @classmethod
+  def _build_context(cls, *, rng_seed=None, **kwargs) -> QuestionContext:
     """
     Build the deterministic context for a question instance.
 
-    Override to return a context dict and avoid persistent self.* state.
+    Override to return a QuestionContext and avoid persistent self.* state.
     """
     rng = random.Random(rng_seed)
-    # Keep instance rng in sync for questions that still use self.rng.
-    self.rng = rng
-    return {
-      "rng_seed": rng_seed,
-      "rng": rng,
-    }
+    return QuestionContext(
+      rng_seed=rng_seed,
+      rng=rng,
+      question_cls=cls,
+    )
 
   @classmethod
   def is_interesting_ctx(cls, context) -> bool:
     """Context-aware hook; defaults to existing is_interesting()."""
     return True
 
-  def _build_body(self, context) -> ca.Element | Tuple[ca.Element, List[ca.Answer]]:
+  @classmethod
+  def _build_body(cls, context) -> ca.Element | Tuple[ca.Element, List[ca.Answer]]:
     """Context-aware body builder."""
     raise NotImplementedError("Questions must implement _build_body().")
 
-  def _build_explanation(self, context) -> ca.Element | Tuple[ca.Element, List[ca.Answer]]:
+  @classmethod
+  def _build_explanation(cls, context) -> ca.Element | Tuple[ca.Element, List[ca.Answer]]:
     """Context-aware explanation builder."""
     raise NotImplementedError("Questions must implement _build_explanation().")
 
@@ -723,6 +849,38 @@ class Question(abc.ABC):
         merged.append(ans)
     return merged
 
+  @classmethod
+  def _entry_warnings_from_answers(cls, answers: List[ca.Answer]) -> List[str]:
+    warnings: List[str] = []
+    seen: set[str] = set()
+    for answer in answers:
+      warning = None
+      if hasattr(answer.__class__, "get_entry_warning"):
+        warning = answer.__class__.get_entry_warning()
+      if not warning:
+        continue
+      if isinstance(warning, str):
+        warning_list = [warning]
+      else:
+        warning_list = list(warning)
+      for item in warning_list:
+        if item and item not in seen:
+          warnings.append(item)
+          seen.add(item)
+    return warnings
+
+  @classmethod
+  def _append_entry_warnings(cls, body: ca.Element, warnings: List[str]) -> ca.Element:
+    if not warnings:
+      return body
+    notes_lines = ["**Notes for answer entry**", ""]
+    notes_lines.extend(f"- {warning}" for warning in warnings)
+    warning_elements = ca.OnlyHtml([ca.Text("\n".join(notes_lines))])
+    if isinstance(body, ca.Container):
+      body.add_element(warning_elements)
+      return body
+    return ca.Section([body, warning_elements])
+
   @classmethod
   def _can_be_numerical_from_answers(cls, answers: List[ca.Answer]) -> bool:
     return (

{quizgenerator-0.8.0.dist-info → quizgenerator-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: QuizGenerator
-Version: 0.8.0
+Version: 0.9.0
 Summary: Generate randomized quiz questions for Canvas LMS and PDF exams
 Project-URL: Homepage, https://github.com/OtterDen-Lab/QuizGenerator
 Project-URL: Documentation, https://github.com/OtterDen-Lab/QuizGenerator/tree/main/documentation
@@ -150,26 +150,29 @@ All questions follow the same three‑method flow:
 
 ```python
 class MyQuestion(Question):
-    def _build_context(self, *, rng_seed=None, **kwargs):
+    @classmethod
+    def _build_context(cls, *, rng_seed=None, **kwargs):
         context = super()._build_context(rng_seed=rng_seed, **kwargs)
-        rng = context["rng"]
+        rng = context.rng
         context["value"] = rng.randint(1, 10)
         return context
 
-    def _build_body(self, context):
+    @classmethod
+    def _build_body(cls, context):
         body = ca.Section()
         body.add_element(ca.Paragraph([f"Value: {context['value']}"]))
         body.add_element(ca.AnswerTypes.Int(context["value"], label="Value"))
         return body
 
-    def _build_explanation(self, context):
+    @classmethod
+    def _build_explanation(cls, context):
         explanation = ca.Section()
         explanation.add_element(ca.Paragraph([f"Answer: {context['value']}"]))
         return explanation
 ```
 
 Notes:
-- Always use `context["rng"]` for deterministic randomness.
+- Always use `context.rng` (or `context["rng"]`) for deterministic randomness.
 - Avoid `refresh()`; it is no longer part of the API.
 
 ## Built-in Question Types

{quizgenerator-0.8.0.dist-info → quizgenerator-0.9.0.dist-info}/RECORD

@@ -1,13 +1,13 @@
 QuizGenerator/__init__.py,sha256=8EV-k90A3PNC8Cm2-ZquwNyVyvnwW1gs6u-nGictyhs,840
 QuizGenerator/__main__.py,sha256=Dd9w4R0Unm3RiXztvR4Y_g9-lkWp6FHg-4VN50JbKxU,151
 QuizGenerator/constants.py,sha256=AO-UWwsWPLb1k2JW6KP8rl9fxTcdT0rW-6XC6zfnDOs,4386
-QuizGenerator/contentast.py,sha256=6eqhgjAGrkFQUoEOnnEuGIyllGnNC4354aP8IvnGCx4,86316
-QuizGenerator/generate.py,sha256=dqF-WWmWxyJmPHl0gTYr3gNNxyF877fvXYaMvYA3uA8,15790
+QuizGenerator/contentast.py,sha256=LEjr-J79ooge0sAlZMuJcyz5Xfj2wRHlAJ_7jAULhBY,87614
+QuizGenerator/generate.py,sha256=qXLJ3WfOo_poIWoAZvEK7epNlVNSWxpOomMVt2MDExA,15816
 QuizGenerator/misc.py,sha256=MXrguUhhdrWSV4Hqdl4G21ktowODu1AcKy6-5mvy3aI,454
-QuizGenerator/mixins.py,sha256=B9Ee52wUCeclmBTgonasHNo0WHvVOcnILsz0iecrf78,15705
+QuizGenerator/mixins.py,sha256=zXj2U94qNbIEusbwTnzRM1Z_zSybpvozWhveq-t5q2Q,15771
 QuizGenerator/performance.py,sha256=CM3zLarJXN5Hfrl4-6JRBqD03j4BU1B2QW699HAr1Ds,7002
 QuizGenerator/qrcode_generator.py,sha256=S3mzZDk2UiHiw6ipSCpWPMhbKvSRR1P5ordZJUTo6ug,10776
-QuizGenerator/question.py,sha256=cfhCViOSI4p7rcQHE2igv1-aWZgyEKU6rUqJ25VHkfU,32304
+QuizGenerator/question.py,sha256=PKpQ6ZsHkyNw3yJBXlU3akS9Dqhmprq0dLu7wjRzg9A,37240
 QuizGenerator/quiz.py,sha256=CEWy7FB7BZiK33s_wYs6MqGKDetc6htUaqvP3--2HzI,21621
 QuizGenerator/regenerate.py,sha256=ZAs1mtERmO8JXza2tBqJpd-uJs9V7gS1jJ9A9gSb8jo,19764
 QuizGenerator/typst_utils.py,sha256=JGQn_u5bEHd8HAtjAHuZoVJwLkx-Rd4ZCBWffwFZa3o,3136
@@ -15,22 +15,22 @@ QuizGenerator/canvas/__init__.py,sha256=TwFP_zgxPIlWtkvIqQ6mcvBNTL9swIH_rJl7DGKc
 QuizGenerator/canvas/canvas_interface.py,sha256=StMcdXgLvTA1EayQ44m_le2GXGQpDQnduYXVeUYsqW0,24618
 QuizGenerator/canvas/classes.py,sha256=v_tQ8t_JJplU9sv2p4YctX45Fwed1nQ2HC1oC9BnDNw,7594
 QuizGenerator/premade_questions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-QuizGenerator/premade_questions/basic.py,sha256=F_Qsu14b2xERyibCAMP1NPgnmi1h2G2DDkKJoU_RS8g,3284
+QuizGenerator/premade_questions/basic.py,sha256=u6Viv__5HYWjLOknYt_jsBJTej5-cPd9FM1xsuwUQcQ,4613
 QuizGenerator/premade_questions/cst334/__init__.py,sha256=BTz-Os1XbwIRKqAilf2UIva2NlY0DbA_XbSIggO2Tdk,36
 QuizGenerator/premade_questions/cst334/languages.py,sha256=ctemEAMkI8C6ASMIf59EHAW1ndFWi7hXzdEt-zOByUE,14114
 QuizGenerator/premade_questions/cst334/math_questions.py,sha256=aUYbQxneL5MXE7Xo3tZX9-xcg71CXwvG3rrxcoh0l7A,8638
 QuizGenerator/premade_questions/cst334/memory_questions.py,sha256=g0EFJ2HUogYnOYMWYyn-z4lEv15Pfv5IdSvj0xGoKbI,51050
 QuizGenerator/premade_questions/cst334/ostep13_vsfs.py,sha256=d9jjrynEw44vupAH_wKl57UoHooCNEJXaC5DoNYualk,16163
 QuizGenerator/premade_questions/cst334/persistence_questions.py,sha256=9mgsX-3oWDQgm_n2YwmFSil0QPyzsruHzuqB-hfGMuA,16220
-QuizGenerator/premade_questions/cst334/process.py,sha256=J9sk-tXeuCDFk2hHm_h9XJE40avacQWPNGf92yp4EjA,37682
+QuizGenerator/premade_questions/cst334/process.py,sha256=0SqXkvdxaEJZXJA8fBqheh7F0PL8I6xgO5a8u2s2po4,37238
 QuizGenerator/premade_questions/cst463/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 QuizGenerator/premade_questions/cst463/gradient_descent/__init__.py,sha256=sH2CUV6zK9FT3jWTn453ys6_JTrUKRtZnU8hK6RmImU,240
-QuizGenerator/premade_questions/cst463/gradient_descent/gradient_calculation.py,sha256=laBeC0tMc2EaLzCotGHQNzePPPOKS1EGgQirigNyi9M,13479
-QuizGenerator/premade_questions/cst463/gradient_descent/gradient_descent_questions.py,sha256=_2HlC0sqfGy__Qyzbw0PwMD_OkQiiQukl72LQFyPYx0,10939
-QuizGenerator/premade_questions/cst463/gradient_descent/loss_calculations.py,sha256=8GtJX1DNNox-AgMvABFkRgmHB-lvrxMZKzv-3Ils_Jg,22380
+QuizGenerator/premade_questions/cst463/gradient_descent/gradient_calculation.py,sha256=y_R26wUt7AIZVUoe3e_qpzkPdwMyo3mZjxLI504-YQw,13840
+QuizGenerator/premade_questions/cst463/gradient_descent/gradient_descent_questions.py,sha256=OssybIkHx4l8ryHGT9rqHUecta9qpItK4QYVHuuQLeo,11525
+QuizGenerator/premade_questions/cst463/gradient_descent/loss_calculations.py,sha256=slNXfEeLRRM8IDhn3TSQdUWjAimDIfbgUSEmb48zCuU,24156
 QuizGenerator/premade_questions/cst463/gradient_descent/misc.py,sha256=0R-nFeD3zsqJyde5CXWrF6Npjmpx6_HbzfCbThLi3os,2657
 QuizGenerator/premade_questions/cst463/math_and_data/__init__.py,sha256=EbIaUrx7_aK9j3Gd8Mk08h9GocTq_0OoNu2trfNwaU8,202
-QuizGenerator/premade_questions/cst463/math_and_data/matrix_questions.py,sha256=4HsMflR1Fm-yjD0J3iW057_q3UHDRiW-swzOd5D73Ys,15647
+QuizGenerator/premade_questions/cst463/math_and_data/matrix_questions.py,sha256=4DLdo_8XDS_xtPA8R-wH4K0cKnMn4r5727Vszz8keTc,15565
 QuizGenerator/premade_questions/cst463/math_and_data/vector_questions.py,sha256=VXQCLQEeNKxRDPn_fGW5nAPX-0betrZ8mURh0ElbNz0,12668
 QuizGenerator/premade_questions/cst463/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 QuizGenerator/premade_questions/cst463/models/attention.py,sha256=iECxOoR0LEJAH_d7ZE3MoLOkdYVbGOKo4Dwf8Pww0tM,5443
@@ -40,11 +40,11 @@ QuizGenerator/premade_questions/cst463/models/rnns.py,sha256=5fKQuWnpSAoznZVJuCY
 QuizGenerator/premade_questions/cst463/models/text.py,sha256=BnW6qIB8pnQiFRyXxtX9cdsIfmjw99p6TI0WqI0AQzk,6605
 QuizGenerator/premade_questions/cst463/models/weight_counting.py,sha256=sFnEvSs7ZwR4RZPltiMEElKJgoxHTaY427_g8Abi2uk,6912
 QuizGenerator/premade_questions/cst463/neural-network-basics/__init__.py,sha256=pmyCezO-20AFEQC6MR7KnAsaU9TcgZYsGQOMVkRZ-U8,149
-QuizGenerator/premade_questions/cst463/neural-network-basics/neural_network_questions.py,sha256=bit_HfAG4K6yh9SZZw_HAPhFUVFkOBdZ2odwt-Cdvmo,42868
+QuizGenerator/premade_questions/cst463/neural-network-basics/neural_network_questions.py,sha256=j2f5LFmme-2rSgJzcb8nZJ1_hnZaL-S4lXSnIbpoH_E,43010
 QuizGenerator/premade_questions/cst463/tensorflow-intro/__init__.py,sha256=G1gEHtG4KakYgi8ZXSYYhX6bQRtnm2tZVGx36d63Nmo,173
-QuizGenerator/premade_questions/cst463/tensorflow-intro/tensorflow_questions.py,sha256=jZRbEqb65BAtliv_V9VR4kvpwOt-o10ApN7RmOIg3XI,30464
-quizgenerator-0.8.0.dist-info/METADATA,sha256=W3Cb-jkrgfxtWGBJ7zynREY_q-_3q53rKpQ0eFC9OCw,8113
-quizgenerator-0.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-quizgenerator-0.8.0.dist-info/entry_points.txt,sha256=aOIdRdw26xY8HkxOoKHBnUPe2mwGv5Ti3U1zojb6zxQ,98
-quizgenerator-0.8.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-quizgenerator-0.8.0.dist-info/RECORD,,
+QuizGenerator/premade_questions/cst463/tensorflow-intro/tensorflow_questions.py,sha256=t0ghv6o8AsZaIwVHFu07Ozebwuv6Rf18D3g_-Jz4O74,31309
+quizgenerator-0.9.0.dist-info/METADATA,sha256=84oI93hpRcDQO03t5qMjloNUWcCQo9MgOZmkMe9YrbY,8177
+quizgenerator-0.9.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+quizgenerator-0.9.0.dist-info/entry_points.txt,sha256=aOIdRdw26xY8HkxOoKHBnUPe2mwGv5Ti3U1zojb6zxQ,98
+quizgenerator-0.9.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+quizgenerator-0.9.0.dist-info/RECORD,,