in2lambda 0.3.3__tar.gz → 1.0.1__tar.gz

{in2lambda-0.3.3 → in2lambda-1.0.1}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: in2lambda
-Version: 0.3.3
+Version: 1.0.1
 Summary: Converts content ready for import into Lambda Feedback
-Home-page: https://lambda-feedback.github.io/in2lambda
 License: MIT
+License-File: LICENSE
 Requires-Python: >=3.10,<4.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: MIT License
@@ -13,13 +13,18 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Typing :: Typed
 Requires-Dist: beartype (>=0.17.2,<0.18.0)
 Requires-Dist: panflute (>=2.3.1,<3.0.0)
+Requires-Dist: requests (<2.34.0)
 Requires-Dist: rich-click (>=1.7.4,<2.0.0)
 Project-URL: Bug Tracker, https://github.com/lambda-feedback/in2lambda/issues
 Project-URL: Documentation, https://lambda-feedback.github.io/in2lambda
+Project-URL: Homepage, https://lambda-feedback.github.io/in2lambda
 Project-URL: Repository, https://github.com/lambda-feedback/in2lambda
 Description-Content-Type: text/markdown
 

in2lambda-1.0.1/in2lambda/api/part.py

@@ -0,0 +1,30 @@
+"""A part of a question."""
+
+from dataclasses import dataclass, field
+
+from in2lambda.api.response_area import ResponseArea
+
+
+@dataclass
+class Branch:
+    """A (titled) branch of a structured tutorial or worked solution, which may branch further."""
+
+    title: str
+    content: str
+    branches: list["Branch"] = field(default_factory=list)
+
+
+@dataclass
+class Part:
+    """A part of a question as represented on Lambda Feedback.
+
+    Markdown content for the question and supporting materials. Note that in ``tutorial`` and ``worked_solution`` fields, steps can by separated by a line with only ``---`` (or ``***``).
+    """
+
+    content: str = ""
+    response_areas: list[ResponseArea] = field(default_factory=list)
+    tutorial: str = ""
+    tutorial_branches: list[Branch] = field(default_factory=list)
+    answer: str = ""
+    worked_solution: str = ""
+    worked_solution_branches: list[Branch] = field(default_factory=list)

{in2lambda-0.3.3 → in2lambda-1.0.1}/in2lambda/api/question.py

@@ -1,7 +1,7 @@
-"""A full question with optional parts that's contained in a module."""
+"""A full question with optional parts that's contained in a set."""
 
 from dataclasses import dataclass, field
-from typing import Union
+from typing import Optional, Union
 
 import panflute as pf
 
@@ -14,10 +14,12 @@ class Question:
 
     Each question has a title and is composed of a list of parts.
 
+    It also carries the settings Lambda Feedback keeps per 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", master_content="Some text")
+        Question(title='Some title', parts=[], images=[], master_content='Some text')
     """
 
     title: str = ""
@@ -25,10 +27,10 @@ class Question:
     parts: list[Part] = field(default_factory=list)
     images: list[str] = field(default_factory=list)
 
-    # Use getter/setter methods for main_text without exposing private attribute.
+    # Use getter/setter methods for master_content without exposing private attribute.
     # See https://stackoverflow.com/a/61480946
-    main_text: str = ""
-    _main_text: str = field(init=False, repr=False, default="")
+    master_content: str = ""
+    _master_content: str = field(init=False, repr=False, default="")
 
     _last_part: dict[str, int] = field(
         default_factory=lambda: {"solution": 0, "text": 0}, repr=False
@@ -36,8 +38,23 @@ class Question:
     """Keeps track of the last question part that contains a solution /
     text."""
 
+    # The settings below are left out of the repr, so that printing a question shows its
+    # content rather than nine lines of configuration.
+
+    # The skill level may be an int as well as a float, because Lambda Feedback writes
+    # its exports in JavaScript, which writes the levels 0.0 and 1.0 as 0 and 1.
+    skill: Optional[Union[int, float]] = field(default=None, repr=False)
+    guidance: Optional[str] = field(default=None, repr=False)
+    duration_lower_bound: Optional[int] = field(default=None, repr=False)
+    duration_upper_bound: Optional[int] = field(default=None, repr=False)
+    publish: bool = field(default=False, repr=False)
+    display_final_answer: bool = field(default=True, repr=False)
+    display_worked_solution: bool = field(default=True, repr=False)
+    display_structured_tutorial: bool = field(default=True, repr=False)
+    display_chatbot: bool = field(default=False, repr=False)
+
     @property
-    def main_text(self) -> str:
+    def master_content(self) -> str:
         r"""Main top-level question text.
 
         Setting the attribute multiple times appends to the current value with a newline.
@@ -46,21 +63,21 @@ class Question:
         Examples:
             >>> from in2lambda.api.question import Question
             >>> question = Question()
-            >>> question.main_text = "hello"
-            >>> question.main_text = "there"
-            >>> question.main_text
+            >>> question.master_content = "hello"
+            >>> question.master_content = "there"
+            >>> question.master_content
             'hello\nthere'
         """
-        return self._main_text
+        return self._master_content
 
-    @main_text.setter
-    def main_text(self, value: Union[pf.Element, str, property]) -> None:
+    @master_content.setter
+    def master_content(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.
+        See example in master_content property.
         """
         # Converts the inputted value into a string, stored in text_value
         match value:
@@ -69,13 +86,13 @@ class Question:
             case property():
                 # Use default value when no value set at initialisation.
                 # See https://stackoverflow.com/a/61480946
-                text_value = self.main_text
+                text_value = self.master_content
             case pf.Element():
                 text_value = pf.stringify(value, False)
 
-        if self._main_text:
-            self._main_text += "\n"
-        self._main_text += text_value
+        if self._master_content:
+            self._master_content += "\n"
+        self._master_content += text_value
 
     def add_solution(self, elem: Union[pf.Element, str]) -> None:
         """Adds a worked solution to all question parts without one, or inserts a new empty part with the solution if all parts already have a solution.
@@ -89,20 +106,20 @@ class Question:
             >>> 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(content='part a', response_areas=[], tutorial='', tutorial_branches=[], answer='', worked_solution='part a solution', worked_solution_branches=[])], images=[], master_content='')
             >>> 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='')
+            Question(title='', parts=[Part(content='part a', response_areas=[], tutorial='', tutorial_branches=[], answer='', worked_solution='part a solution', worked_solution_branches=[]), \
+Part(content='part b', response_areas=[], tutorial='', tutorial_branches=[], answer='', worked_solution='Solution for b', worked_solution_branches=[]), \
+Part(content='part c', response_areas=[], tutorial='', tutorial_branches=[], answer='', worked_solution='Solution for b', worked_solution_branches=[])], images=[], master_content='')
             >>> 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='')
+            Question(title='', parts=[Part(content='part a', response_areas=[], tutorial='', tutorial_branches=[], answer='', worked_solution='part a solution', worked_solution_branches=[]), \
+Part(content='part b', response_areas=[], tutorial='', tutorial_branches=[], answer='', worked_solution='Solution for b', worked_solution_branches=[]), \
+Part(content='part c', response_areas=[], tutorial='', tutorial_branches=[], answer='', worked_solution='We now have a solution for c!', worked_solution_branches=[])], images=[], master_content='')
         """
         elem_text = elem if isinstance(elem, str) else pf.stringify(elem)
 
@@ -131,19 +148,19 @@ Part(text='part c', worked_solution='We now have a solution for c!')], images=[]
             >>> 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(content='part a', response_areas=[], tutorial='', tutorial_branches=[], answer='', worked_solution='part a solution', worked_solution_branches=[])], images=[], master_content='')
             >>> # 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='')
+            Question(title='', parts=[Part(content='part a', response_areas=[], tutorial='', tutorial_branches=[], answer='', worked_solution='part a solution', worked_solution_branches=[]), \
+Part(content='part b', response_areas=[], tutorial='', tutorial_branches=[], answer='', worked_solution='part b solution', worked_solution_branches=[])], images=[], master_content='')
         """
         elem_text = elem if isinstance(elem, str) else pf.stringify(elem)
 
         if len(self.parts) == self._last_part["text"]:
-            self.parts.append(Part(text=elem_text))
+            self.parts.append(Part(content=elem_text))
         else:
-            self.parts[self._last_part["text"]].text = elem_text
+            self.parts[self._last_part["text"]].content = elem_text
 
         self._last_part["text"] += 1

in2lambda-1.0.1/in2lambda/api/response_area.py

@@ -0,0 +1,317 @@
+"""An area for student responses that will receive automated feedback."""
+
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, ClassVar, Optional, Union
+
+
+def _new_id() -> str:
+    return str(uuid.uuid4())
+
+
+@dataclass
+class InputSymbol:
+    """Defines symbols and how to enter them into a response area.
+
+    Fields per symbol:
+    - ``symbol`` for display to users (markdown, typically dollar-delimited math latex)
+    - ``code`` for users to input (plan text, fed to the algorithm and also be rendered to users within backticks as `code`)
+    - ``aliases`` list of alternative code inputs, to be substituted by the `code` field when evaluating
+    - ``is_visible`` Boolean, whether to display input symbol info to users (in addition to always sending it to the evaluator to help parsing)
+    """
+
+    symbol: str
+    code: str
+    aliases: list[str] = field(default_factory=list)
+    is_visible: bool = True
+
+
+@dataclass
+class Test:
+    """Teacher author's assertions of how responses should be evaluated."""
+
+    # Its name would otherwise make pytest try to collect it wherever it is imported.
+    __test__ = False
+
+    payload: str
+    is_correct: bool
+    id: str = field(default_factory=_new_id)
+
+
+class Color(Enum):
+    """Acceptable colours for a feedback case."""
+
+    RED = "#ff5630"
+    AMBER = "#FFAB00"
+    GREEN = "#22C55E"
+    BLUE = "#0099c4"
+    GREY = "#C4CDD5"
+
+
+@dataclass
+class Case:
+    """A declared case for which bespoke feedback is prescribed."""
+
+    answer: str
+    feedback: str
+    is_correct: bool
+    params: Any = None
+    color: Optional[Color] = None
+    id: str = field(default_factory=_new_id)
+
+
+@dataclass(kw_only=True)
+class ResponseArea:
+    """Specifies the interaction when a student provides a response.
+
+    Multiple response areas per part are allowed; if so, order is implicit.
+    Use a subclass for each response type. ``grade_params`` are passed to the
+    evaluation function unedited.
+
+    Examples:
+        >>> from in2lambda.api.response_area import NumericUnits, Test
+        >>> area = NumericUnits(
+        ...     answer="30 N",
+        ...     grade_params={"rtol": 0.05},
+        ...     pre_text="$F=$",
+        ...     tests=[Test("30 N", True)],
+        ... )
+        >>> area.response_type, area.evaluation_function
+        ('NUMERIC_UNITS', 'compareExpressions')
+    """
+
+    response_type: ClassVar[str]
+    answer: Any = None
+    evaluation_function: str
+    grade_params: Optional[dict[str, Any]] = None
+    pre_text: str = ""
+    post_text: str = ""
+    content_after: str = ""
+    """Markdown shown after the box, before the next one."""
+    check_button_text: str = ""
+    """Replaces the label of the check button; left out of the JSON when empty."""
+    input_symbols: list[InputSymbol] = field(default_factory=list)
+    display_input_symbols: bool = False
+    live_preview: bool = False
+    include_in_pdf: bool = False
+    save_allowed: bool = False
+    separate_feedback: bool = True
+    common_feedback_color: str = "#C4CDD5"
+    correct_feedback_color: str = "#22C55E"
+    correct_feedback_prefix: str = "Correct"
+    incorrect_feedback_color: str = "#ff5630"
+    incorrect_feedback_prefix: str = "Incorrect"
+    tests: list[Test] = field(default_factory=list)
+    cases: list[Case] = field(default_factory=list)
+
+    def _config(self) -> Optional[dict[str, Any]]:
+        """The response type's settings, as Lambda Feedback writes them."""
+        return None
+
+    def _grade_params(self) -> Optional[dict[str, Any]]:
+        """The parameters sent to the evaluation function."""
+        return self.grade_params
+
+
+@dataclass(kw_only=True)
+class _Maths(ResponseArea):
+    answer: str = ""
+    allow_handwrite: bool = True
+    allow_photo: bool = True
+    enable_refinement: bool = True
+
+    def _config(self) -> Optional[dict[str, Any]]:
+        return {
+            "allowHandwrite": self.allow_handwrite,
+            "allowPhoto": self.allow_photo,
+            "enableRefinement": self.enable_refinement,
+        }
+
+
+@dataclass(kw_only=True)
+class MathSingleLine(_Maths):
+    """A single symbolic expression."""
+
+    response_type: ClassVar[str] = "MATH_SINGLE_LINE"
+    evaluation_function: str = "compareExpressions"
+
+
+@dataclass(kw_only=True)
+class MathMultiLines(_Maths):
+    """Multiple lines of mathematical work."""
+
+    response_type: ClassVar[str] = "MATH_MULTI_LINES"
+
+
+@dataclass(kw_only=True)
+class Number(ResponseArea):
+    """A number."""
+
+    response_type: ClassVar[str] = "NUMBER"
+    answer: Optional[Union[int, float]] = None
+    evaluation_function: str = "isSimilar"
+
+
+@dataclass(kw_only=True)
+class NumericUnits(ResponseArea):
+    """A number with units, e.g. ``30 N``."""
+
+    response_type: ClassVar[str] = "NUMERIC_UNITS"
+    answer: str = ""
+    evaluation_function: str = "compareExpressions"
+
+    def _grade_params(self) -> Optional[dict[str, Any]]:
+        # compareExpressions compares units only when told to.
+        return {"physical_quantity": True, **(self.grade_params or {})}
+
+
+@dataclass(kw_only=True)
+class Text(ResponseArea):
+    """A short piece of text."""
+
+    response_type: ClassVar[str] = "TEXT"
+    answer: str = ""
+
+
+@dataclass(kw_only=True)
+class Boolean(ResponseArea):
+    """True or false."""
+
+    response_type: ClassVar[str] = "BOOLEAN"
+    answer: bool = False
+    evaluation_function: str = "isExactEqual"
+
+
+@dataclass(kw_only=True)
+class MultipleChoice(ResponseArea):
+    """A choice among ``options``; ``answer`` marks each option correct or not."""
+
+    response_type: ClassVar[str] = "MULTIPLE_CHOICE"
+    answer: list[bool] = field(default_factory=list)
+    evaluation_function: str = "arrayEqual"
+    options: list[str] = field(default_factory=list)
+    single: bool = True
+    randomise: bool = False
+
+    def _config(self) -> Optional[dict[str, Any]]:
+        return {
+            "options": self.options,
+            "randomise": self.randomise,
+            "single": self.single,
+        }
+
+
+@dataclass(kw_only=True)
+class Table(ResponseArea):
+    """A grid of cells, one row per row name and one column per column name."""
+
+    response_type: ClassVar[str] = "TABLE"
+    answer: list[list[str]] = field(default_factory=list)
+    evaluation_function: str = "arraySymbolicEqual"
+    row_names: list[str] = field(default_factory=list)
+    col_names: list[str] = field(default_factory=list)
+
+    def _config(self) -> Optional[dict[str, Any]]:
+        return {
+            "rows": len(self.row_names),
+            "cols": len(self.col_names),
+            "rowNames": self.row_names,
+            "colNames": self.col_names,
+        }
+
+
+@dataclass(kw_only=True)
+class Matrix(ResponseArea):
+    """A table, with parentheses displayed around it, with the shape of ``answer``."""
+
+    response_type: ClassVar[str] = "MATRIX"
+    answer: list[list[str]] = field(default_factory=list)
+    evaluation_function: str = "arraySymbolicEqual"
+
+    def _config(self) -> Optional[dict[str, Any]]:
+        return {
+            "rows": len(self.answer),
+            "cols": len(self.answer[0]) if self.answer else 0,
+        }
+
+
+@dataclass(kw_only=True)
+class Code(ResponseArea):
+    """A monaco code editor."""
+
+    response_type: ClassVar[str] = "CODE"
+    answer: str = ""
+    evaluation_function: str = "evaluatePython"
+    language: str = "python"
+
+    def _config(self) -> Optional[dict[str, Any]]:
+        return {"language": self.language}
+
+
+@dataclass(kw_only=True)
+class Essay(ResponseArea):
+    """Large text box."""
+
+    response_type: ClassVar[str] = "ESSAY"
+    answer: Union[str, dict[str, str]] = ""
+    allow_draw: bool = False
+    allow_scan: bool = False
+    repeat_for_subjects: bool = False
+    allow_empty_submission: bool = False
+
+    def _config(self) -> Optional[dict[str, Any]]:
+        return {
+            "allowDraw": self.allow_draw,
+            "allowScan": self.allow_scan,
+            "repeatForSubjects": self.repeat_for_subjects,
+            "allowEmptySubmission": self.allow_empty_submission,
+        }
+
+
+@dataclass(kw_only=True)
+class Likert(ResponseArea):
+    """A multiple choice with Likert scales."""
+
+    response_type: ClassVar[str] = "LIKERT"
+    answer: Union[
+        list[Optional[Union[int, float]]],
+        dict[str, list[Optional[Union[int, float]]]],
+        None,
+    ] = None
+    statements: list[str] = field(default_factory=list)
+    options: Optional[list[str]] = None
+    repeat_for_subjects: bool = False
+    allow_empty_submission: bool = False
+
+    def _config(self) -> Optional[dict[str, Any]]:
+        config: dict[str, Any] = {
+            "statements": self.statements,
+            "repeatForSubjects": self.repeat_for_subjects,
+            "allowEmptySubmission": self.allow_empty_submission,
+        }
+        if self.options is not None:
+            config["options"] = self.options
+        return config
+
+
+@dataclass(kw_only=True)
+class Images(ResponseArea):
+    """Upload images."""
+
+    response_type: ClassVar[str] = "IMAGES"
+    max_images: int = 3
+    allowed_types: list[str] = field(
+        default_factory=lambda: ["image/jpg", "image/jpeg", "image/png"]
+    )
+    max_size_mb: int = 10
+    resize_max_side: int = 0
+    """The longest side images are resized to; 0 leaves them as they are."""
+
+    def _config(self) -> Optional[dict[str, Any]]:
+        return {
+            "maxImages": self.max_images,
+            "allowedTypes": self.allowed_types,
+            "maxSizeMb": self.max_size_mb,
+            "resizeMaxSide": self.resize_max_side,
+        }