feat(question-api): improve main_text encapsulation

- Fix anti-pattern of private `_main_text` in public Question dataclass (https://stackoverflow.com/a/61480946).
- Also allow sphinx to find main_text examples.

BREAKING CHANGE: During Question initialisation, `_main_text` attribute replaced with `main_text`.

Author: harens

in2lambda/api/module.py

@@ -29,11 +29,11 @@ def current_question(self) -> Question:
         Examples:
             >>> from in2lambda.api.module import Module
             >>> Module().current_question
-            Question(title='INVALID', parts=[], images=[], _main_text='')
+            Question(title='INVALID', parts=[], images=[], main_text='')
             >>> module = Module()
             >>> module.add_question()
             >>> module.current_question
-            Question(title='', parts=[], images=[], _main_text='')
+            Question(title='', parts=[], images=[], main_text='')
         """
         return (
             self.questions[self._current_question_index]
@@ -57,7 +57,7 @@ def add_question(
             >>> module = Module()
             >>> module.add_question("Some title", pf.Para(pf.Str("hello"), pf.Space, pf.Str("there")))
             >>> module
-            Module(questions=[Question(title='Some title', parts=[], images=[], _main_text='hello there')])
+            Module(questions=[Question(title='Some title', parts=[], images=[], main_text='hello there')])
             >>> module.add_question(main_text="Normal string text")
             >>> module.questions[1].main_text
             'Normal string text'
@@ -86,8 +86,8 @@ def increment_current_question(self) -> None:
             >>> module.increment_current_question()
             >>> module.current_question.add_solution("Question 2 answer")
             >>> module.questions
-            [Question(title='Question 1', parts=[Part(text='', worked_solution='Question 1 answer')], images=[], _main_text=''),\
- Question(title='Question 2', parts=[Part(text='', worked_solution='Question 2 answer')], images=[], _main_text='')]
+            [Question(title='Question 1', parts=[Part(text='', worked_solution='Question 1 answer')], images=[], main_text=''),\
+ Question(title='Question 2', parts=[Part(text='', worked_solution='Question 2 answer')], images=[], main_text='')]
         """
         self._current_question_index += 1
 

in2lambda/api/question.py

@@ -16,16 +16,20 @@ class Question:
 
     Examples:
         >>> from in2lambda.api.question import Question
-        >>> Question(title="Some title", _main_text="Some text")
-        Question(title='Some title', parts=[], images=[], _main_text='Some text')
+        >>> Question(title="Some title", main_text="Some text")
+        Question(title='Some title', parts=[], images=[], main_text='Some text')
     """
 
     title: str = ""
 
     parts: list[Part] = field(default_factory=list)
     images: list[str] = field(default_factory=list)
 
-    _main_text: str = ""
+    # Use getter/setter methods for main_text without exposing private attribute.
+    # See https://stackoverflow.com/a/61480946
+    main_text: str = ""
+    _main_text: str = field(init=False, repr=False, default="")
+
     _last_part: dict[str, int] = field(
         default_factory=lambda: {"solution": 0, "text": 0}, repr=False
     )
@@ -34,15 +38,10 @@ class Question:
 
     @property
     def main_text(self) -> str:
-        """Main top-level question text."""
-        return self._main_text
+        r"""Main top-level question text.
 
-    @main_text.setter
-    def main_text(self, value: Union[pf.Element, str]) -> None:
-        r"""Appends to the top-level main text, which starts off as an empty string.
-
-        Args:
-            value: A panflute element or string denoting what to append to the main text.
+        Setting the attribute multiple times appends to the current value with a newline.
+        This allows question text to be dynamically appended.
 
         Examples:
             >>> from in2lambda.api.question import Question
@@ -52,7 +51,28 @@ def main_text(self, value: Union[pf.Element, str]) -> None:
             >>> question.main_text
             'hello\nthere'
         """
-        text_value = value if isinstance(value, str) else pf.stringify(value, False)
+        return self._main_text
+
+    @main_text.setter
+    def main_text(self, value: Union[pf.Element, str, property]) -> None:
+        r"""Appends to the top-level main text, which starts off as an empty string.
+
+        Args:
+            value: A panflute element or string denoting what to append to the main text.
+
+        See example in main_text property.
+        """
+        # Converts the inputted value into a string, stored in text_value
+        match value:
+            case str():
+                text_value = value
+            case property():
+                # Use default value when no value set at initialisation.
+                # See https://stackoverflow.com/a/61480946
+                text_value = self.main_text
+            case pf.Element():
+                text_value = pf.stringify(value, False)
+
         if self._main_text:
             self._main_text += "\n"
         self._main_text += text_value
@@ -69,20 +89,20 @@ def add_solution(self, elem: Union[pf.Element, str]) -> None:
             >>> question.add_part_text("part a")
             >>> question.add_solution("part a solution")
             >>> question
-            Question(title='', parts=[Part(text='part a', worked_solution='part a solution')], images=[], _main_text='')
+            Question(title='', parts=[Part(text='part a', worked_solution='part a solution')], images=[], main_text='')
             >>> question.add_part_text("part b")
             >>> question.add_part_text("part c")
             >>> question.add_solution("Solution for b")
             >>> # Note that since c doesn't have a solution, it's set to b's solution
             >>> question
             Question(title='', parts=[Part(text='part a', worked_solution='part a solution'), \
 Part(text='part b', worked_solution='Solution for b'), \
-Part(text='part c', worked_solution='Solution for b')], images=[], _main_text='')
+Part(text='part c', worked_solution='Solution for b')], images=[], main_text='')
             >>> question.add_solution("We now have a solution for c!")
             >>> question
             Question(title='', parts=[Part(text='part a', worked_solution='part a solution'), \
 Part(text='part b', worked_solution='Solution for b'), \
-Part(text='part c', worked_solution='We now have a solution for c!')], images=[], _main_text='')
+Part(text='part c', worked_solution='We now have a solution for c!')], images=[], main_text='')
         """
         elem_text = elem if isinstance(elem, str) else pf.stringify(elem)
 
@@ -111,13 +131,13 @@ def add_part_text(self, elem: Union[pf.Element, str]) -> None:
             >>> question.add_part_text("part a")
             >>> question.add_solution("part a solution")
             >>> question
-            Question(title='', parts=[Part(text='part a', worked_solution='part a solution')], images=[], _main_text='')
+            Question(title='', parts=[Part(text='part a', worked_solution='part a solution')], images=[], main_text='')
             >>> # Supports adding the answer first.
             >>> question.add_solution("part b solution")
             >>> question.add_part_text("part b")
             >>> question
             Question(title='', parts=[Part(text='part a', worked_solution='part a solution'), \
-Part(text='part b', worked_solution='part b solution')], images=[], _main_text='')
+Part(text='part b', worked_solution='part b solution')], images=[], main_text='')
         """
         elem_text = elem if isinstance(elem, str) else pf.stringify(elem)
 

in2lambda/main.py

@@ -80,9 +80,9 @@ def runner(
         >>> from in2lambda.main import runner
         >>> # Retrieve an example TeX file and run the given filter.
         >>> runner(f"{os.path.dirname(in2lambda.__file__)}/filters/PartsSepSol/example.tex", "PartsSepSol") # doctest: +ELLIPSIS
-        Module(questions=[Question(title='', parts=[Part(text=..., worked_solution=''), ...], images=[], _main_text='This is a sample question\n\n'), ...])
+        Module(questions=[Question(title='', parts=[Part(text=..., worked_solution=''), ...], images=[], main_text='This is a sample question\n\n'), ...])
         >>> runner(f"{os.path.dirname(in2lambda.__file__)}/filters/PartsOneSol/example.tex", "PartsOneSol") # doctest: +ELLIPSIS
-        Module(questions=[Question(title='', parts=[Part(text='This is part (a)\n\n', worked_solution=''), ...], images=[], _main_text='Here is some preliminary question information that might be useful.'), ...)
+        Module(questions=[Question(title='', parts=[Part(text='This is part (a)\n\n', worked_solution=''), ...], images=[], main_text='Here is some preliminary question information that might be useful.'), ...)
     """
     # The list of questions for Lambda Feedback as a Python API.
     module = Module()