pl-faded-parsons.py

try:
    import prairielearn as pl
except ModuleNotFoundError:
    import _prairielearn_mock_ as pl

import base64
import chevron
import json
import os.path
import random
import re
import lxml.html as xml

from dataclasses import asdict, dataclass, field, is_dataclass
from typing import (
    Union,
    ForwardRef,
    List,
    Literal,
    Any,
    get_args,
    get_origin,
    cast
)
from enum import Enum

UnionType = Union  # replace with an import when python>=3.10
NoneType = type(None)  # replace with an import when python>=3.10

#
# Common Interfaces for Parsing/Generating Data
#

"""
We use dataclasses instead of `TypeDict`s to allow for type checking in constructors
"""


@dataclass(frozen=True, slots=True)
class Submission:
    """
    Represent the JSON contents of input.main and input.log from pl-faded-parsons-question.mustache

    Naming is sensitive! Compare to mustache and pl-faded-parsons.js
    """

    @dataclass(frozen=True, slots=True)
    class Line:
        indent: int
        codeSnippets: List[str]
        blankValues: List[str]

        def __post_init__(self):
            if len(self.codeSnippets) != len(self.blankValues) + 1:
                raise ValueError(
                    "codeSnippets must have one more element than blankValues"
                )

    @dataclass(frozen=True, slots=True)
    class Trays:
        solution: List["Submission.Line"]
        # starter: Union[List["Submission.Line"], None] = None # TODO: this breaks validate_and_instantiate, but isn't necessary
        starter: List["Submission.Line"] = field(default_factory=list)

    @dataclass(frozen=True, slots=True)
    class LogEntry:
        timestamp: str # TODO: this as a datetime breaks validate_and_instantiate, but isn't necessary
        tag: str  # this is technically an enum of string literals ... Maybe enumerate eventually?
        data: dict  # TODO: expand this, the "tag" tells us the type of JSON object this is

    main: Trays
    log: List[LogEntry] = field(default_factory=list)


@dataclass(frozen=True, slots=True)
class Mustache:
    """
    The structure expected by chevron for pl-faded-parsons-question.mustache

    Naming is sensitive! compare to mustache!
    """

    @dataclass(frozen=True, slots=True)
    class Line:
        @dataclass(frozen=True, slots=True, kw_only=True)
        class Segment:
            @dataclass(frozen=True, slots=True)
            class Blank:
                default: str
                width: int

            @dataclass(frozen=True, slots=True)
            class Code:
                content: str
                language: str

            # { 'blank': { 'default': ..., 'width': max(4, len(...) + 1) } }
            blank: Union[Blank, None] = None
            # { 'code': { 'content': ..., 'language': ... } }
            code: Union[Code, None] = None

            def __post_init__(self):
                if bool(self.blank) == bool(self.code):
                    raise ValueError(
                        "A Segment must be either blank *or* code, set exactly one, not "
                        + ("both" if self.blank else "neither")
                    )

        indent: int
        segments: List[Segment]

    @dataclass(frozen=True, slots=True, kw_only=True)
    class TrayLines:
        lines: List["Mustache.Line"]  # [Line.to_mustache(l, lang) for l in lines]
        narrow: bool = False
        wide: bool = False

        def __post_init__(self):
            if self.narrow == self.wide:
                raise ValueError(
                    "A TrayLine must be either narrow *or* wide, set exactly one, not "
                    + ("both" if self.narrow else "neither")
                )

    @dataclass(frozen=True, slots=True)
    class PrePostText:
        text: str
        language: str

    # chevron skips rendering when values are falsy (eg pre-text/post-text/starter)

    # main element config
    answers_name: str
    language: str
    previous_log: str
    uuid: str

    # trays and code context
    starter: Union[TrayLines, Literal[""]]
    pre_text: Union[Literal[False], PrePostText]
    given: TrayLines
    post_text: Union[Literal[False], PrePostText]


#
# Helper Routines
#
class ParsingError(Exception):
    """Something went wrong during parsing"""


# add generic typing when python>=3.12 (i.e. `val_and_inst[T](t: T, value: Any) -> T`)
def validate_and_instantiate(t: type, value: Any):
    """
    Validate that `value` (a primitive type) can be converted to `t`.
    If so, returns an instance of `t`. Raises a ParsingError otherwise.
    """

    if get_origin(t) is UnionType:
        annotated_types = get_args(t)

        if NoneType in annotated_types and value is None:  # fast return for common case
            return None

        casts = []
        for t in annotated_types:  # for each type that isn't None:
            if t is NoneType:
                continue

            try:  # try to cast it to each anotation, skipping ones that error
                singly_typed = validate_and_instantiate(t, value)
                if singly_typed is None:
                    continue

                casts.append((singly_typed, t))
            except TypeError as _:
                pass

        if casts == []:
            raise ParsingError(
                f"None of {annotated_types} can be constructed from: {value}"
            )
        elif len(casts) > 1:  # multiple casts worked -- that's bad
            matching_types = list(map(lambda x: x[1], casts))
            raise ParsingError(
                f"Ambiguous type! All of {matching_types} could be constructed from: {value}"
            )

        return casts[0][0]

    # this is the `List` in `List[int]`, is None if just `list`
    wanted_type = get_origin(t)
    if wanted_type is None and isinstance(t, ForwardRef):
        # handle the case where the type wasn't auto-resolved to the class
        t = t._evaluate(globalns=globals(), localns=locals(), recursive_guard=set())

    if is_dataclass(t):
        if not isinstance(value, dict):
            raise ParsingError(f"Expected a dictionary object to instantiate type {t}, got: {type(value)}")
        return t(
            **{
                k: validate_and_instantiate(t.__annotations__[k], v)
                for k, v in value.items()
            }
        )

    if wanted_type == None:
        # `t` is a class that's not a dataclass with no annotations, cast it
        return t(value)

    # this is the `(int,)` in `List[int]`, is `tuple()` if just `list`/`List`
    type_args = get_args(t)
    if len(type_args) == 0:
        return wanted_type(value)

    if wanted_type == list and isinstance(value, list):
        # `List`/`list` only accepts one type argument
        item_type = type_args[0]
        return list(validate_and_instantiate(item_type, v) for v in value)

    if wanted_type == tuple and isinstance(value, tuple):
        # `Tuple`/`tuple` requires a type argument for each position
        return tuple(validate_and_instantiate(tt, v) for tt, v in zip(type_args, value))

    if wanted_type == dict and isinstance(value, dict):
        # `Dict`/`dict` requires 2 type arguments: one for keys, another for values
        k_type, v_type = type_args
        return {
            validate_and_instantiate(k_type, k): validate_and_instantiate(v_type, v)
            for k, v in value.items()
        }

    raise ParsingError(f"Unhandled case! Could not parse type:{t}, value:{value}")


def interleave(list1: list, list2: list) -> list:
    out = []
    max_len = max(len(list1), len(list2))
    for i in range(max_len):
        if i < len(list1):
            out.append(list1[i])
        if i < len(list2):
            out.append(list2[i])

    return out


#
# The FPP Definition
#
class FadedParsonsProblem:
    """An instance of an FPP

    Instantiate an FPP from an html tag and populate the trays with
    either submitted state or the provided markup.

    XML Attributes
    --------------
    `answers-name="..."`
        The unique identifier for this problem. Raises error if `ValueError` if empty or missing.
    `format={ right | bottom | no-code }`
        The provided format of the problem. Defaults to "right".
    `language`
        The language with which to apply syntax highlighting. Defaults to "" (no highlighting).
    `file-name`
        The file to store the student's submission for grading. Defaults to `user_code.py`.
    `solution-path`
        The path to a file containing the solution. Defaults to "./solution".

    Attributes
    ----------
    `answers_name` : `str`
        This problem's identifier. Specified with `answers-name="..."`.
    `format` : `FadedParsonsProblem.Formats`
        The provided format of the problem. Specified with `format="..."`.
    `markup` : `str`
        The markup provided in html that is parsed into lines for the student. Is not used if the student has previously made a submission.
    `pre_text` : `str`
        The text that will be shown directly before the solution tray. Will be an empty string and not rendered if omitted. Cannot be used with format="right".
    `post_text` : `str`
        The text that will be shown directly after the solution tray. Will be an empty string and not rendered if omitted. Cannot be used with format="right".
    `language` : `str`
        The language with which to apply syntax highlighting. May be an empty string, in which case no highlighting will be done.
    `out_filename` : `str`
        The file to which to include the student's submission. Specified with `file-name="..."`.
    `size` : `Literal["narrow", "wide"]`
        The size of the solution tray. `"narrow"` indicates it should take approximately half the width of the problem pane. `"wide"` indicates it should take the full width of the problem pane.
    `solution_path` : `str`
        The path to a file containing the solution. Specified with `solution-path="..."`. Raises `FileNotFoundError` on access if not found.
    `solution` : `str`
        The solution. Specified with `solution-path="..."`. Raises `FileNotFoundError` on access if file not found.
    `trays` : `Submission.Trays`
        The trays used in this problem. MUST CALL `.load(...)` TO DEFINE.
    `log` : `List[Submission.LogEntry]`
        The log of events for this problem. MUST CALL `.load(...)` TO DEFINE.

    Methods
    -------
    `to_mustache() -> Mustache`
        Produce a `Mustache` instance for rendering
    `to_code() -> str`
        Compile the student submission into an executable code snippet.

    """

    class Format(Enum):
        BOTTOM = "bottom"
        RIGHT = "right"
        NO_CODE = "no_code"

    @staticmethod
    def _get_child_text_by_tag(element: xml.HtmlElement, tag: str) -> str:
        return next((elem.text for elem in element if elem.tag == tag), "")

    @staticmethod
    def _parse_markup_segments(line_str: str) -> tuple[list[str], list[str]]:
        code_portion = line_str.split("#", 1)[0].rstrip()
        snippets = code_portion.split("!BLANK")
        blanks = [""] * (len(snippets) - 1)

        for i, val in enumerate(re.findall(r"#blank [^#]*", line_str)):
            blanks[i] = val.replace("#blank", "").strip()

        return snippets, blanks

    @staticmethod
    def line_to_code(sub_line: Submission.Line) -> str:
        prefix = sub_line.indent * "    "
        return prefix + "".join(interleave(sub_line.codeSnippets, sub_line.blankValues))

    @staticmethod
    def line_to_mustache(sub_line: Submission.Line, language: str) -> Mustache.Line:
        return Mustache.Line(
            indent=sub_line.indent,
            segments=interleave(
                [
                    Mustache.Line.Segment(
                        code=Mustache.Line.Segment.Code(content, language=language)
                    )
                    for content in sub_line.codeSnippets
                ],
                [
                    Mustache.Line.Segment(
                        blank=Mustache.Line.Segment.Blank(
                            placeholder, width=max(4, len(placeholder) + 1)
                        )
                    )
                    for placeholder in sub_line.blankValues
                ],
            ),
        )


    @property
    def solution_path(self) -> str:
        if not os.path.exists(self._solution_path):
            raise FileNotFoundError(
                "\n"
                f"\tCorrect answer not found at `{self._solution_path}`! \n"
                '\tProvide an answer or set "showCorrectAnswer" to false in `./info.json`'
            )

        return self._solution_path

    @property
    def solution(self) -> str:
        with open(self.solution_path, "r") as f:
            return f.read()

    def __init__(self, element_html: str, data: pl.QuestionData):
        element: xml.HtmlElement = xml.fragment_fromstring(element_html)
        self._element: xml.HtmlElement = element
        self._raw_answers = data["raw_submitted_answers"]
        self._options = data["options"]
        pl.check_attribs(
            element,
            required_attribs=[
                "answers-name",
            ],
            optional_attribs=[
                "format",
                "language",
                "file-name",
                "solution-path",
            ],
        )

        self.answers_name = pl.get_string_attrib(element, "answers-name")
        self.format = FadedParsonsProblem.Format(
            pl.get_string_attrib(element, "format", "right").replace("-", "_")
        )
        self.pre_text = self._get_child_text_by_tag(element, "pre-text").strip("\n")
        self.post_text = self._get_child_text_by_tag(element, "post-text").strip("\n")
        self.language: str = pl.get_string_attrib(element, "language", "")
        self.out_filename = pl.get_string_attrib(element, "file-name", "user_code.py")
        self.size = (
            "narrow" if self.format == FadedParsonsProblem.Format.RIGHT else "wide"
        )

        self.markup = self._get_child_text_by_tag(self._element, "code-lines")
        if not self.markup:
            try:
                path = os.path.join(
                    self._options["question_path"],
                    "serverFilesQuestion",
                    "code_lines.txt",
                )
                with open(path, "r") as f:
                    self.markup = f.read()
            except:
                self.markup = str(self._element.text)

        if self.format == FadedParsonsProblem.Format.RIGHT and (
            self.pre_text or self.post_text
        ):
            raise Exception(
                "pre-text and post-text are not supported in right (horizontal) mode. "
                + 'Add/set `format="bottom"` or `format="no-code"` to your element to use this feature.'
            )

        path = pl.get_string_attrib(
            element, "solution-path", "./solution"
        )
        self._solution_path = os.path.join(data["options"]["question_path"], path)
        self._max_distractors = 10  # this was hardcoded before

        # load the trays and log fields
        if f"{self.answers_name}.main" in self._raw_answers:
            prev_submission: Submission = cast(
                Submission,
                validate_and_instantiate(
                    Submission, {
                        "main": json.loads(
                            self._raw_answers[f"{self.answers_name}.main"]
                        ),
                        "log": json.loads(
                            self._raw_answers.get(f"{self.answers_name}.log", "[]")
                        )
                    }
                ),
            )
            self._trays_from_submission(prev_submission)
        else:
            self._trays_from_markup()

    def _trays_from_markup(self) -> None:
        starters, givens, distractors = [], [], []
        GIVEN = re.compile(r"#(\d+)given")
        DISTRACTOR = re.compile(r"#distractor")

        for raw_line in self.markup.strip().split("\n"):
            line_str = raw_line.strip()
            snippets, blanks = self._parse_markup_segments(line_str)

            if match := re.search(GIVEN, line_str):
                givens.append(Submission.Line(int(match.group(1)), snippets, blanks))
            else:
                line = Submission.Line(0, snippets, blanks)
                if re.search(DISTRACTOR, line_str):
                    distractors.append(line)
                else:
                    starters.append(line)

        distractor_count = min(len(distractors), self._max_distractors)
        starters.extend(random.sample(distractors, k=distractor_count))

        random.shuffle(starters)

        self.trays: Submission.Trays
        if self.format == FadedParsonsProblem.Format.NO_CODE:
            self.trays = Submission.Trays(solution=givens + starters, starter=[])
        else:
            self.trays = Submission.Trays(solution=givens, starter=starters)
        self.log: List[Submission.LogEntry] = []

    def _trays_from_submission(self, data: Submission) -> None:
        self.trays: Submission.Trays = data.main
        self.log: List[Submission.LogEntry] = data.log

    def to_mustache(self) -> Mustache:
        if self.trays.starter in ([], None):
            starter_lines = ""
        else:
            starter_lines = Mustache.TrayLines(
                lines=[
                    self.line_to_mustache(sub_line=l, language=self.language)
                    for l in self.trays.starter
                ],
                **{self.size: True},
            )

        return Mustache(
            answers_name=self.answers_name,
            language=self.language,
            previous_log=json.dumps(self.log, default=asdict),
            uuid=pl.get_uuid(),
            starter=starter_lines,
            pre_text=bool(self.pre_text) and Mustache.PrePostText(text=self.pre_text, language=self.language),
            given=Mustache.TrayLines(
                lines=[
                    self.line_to_mustache(sub_line=l, language=self.language)
                    for l in self.trays.solution
                ],
                **{self.size: True},
            ),
            post_text=bool(self.post_text) and Mustache.PrePostText(text=self.post_text, language=self.language),
        )

    def to_code(self) -> str:
        return "\n".join(
            map(
                self.line_to_code,
                self.trays.solution,
            )
        )

def prepare(element_html: str, data: pl.QuestionData):
    element: xml.HtmlElement = xml.fragment_fromstring(element_html)
    pl.check_attribs(
        element,
        required_attribs=["answers-name"],
        optional_attribs=["format", "language", "file-name", "solution-path"],
    )
    pl.check_answers_names(data, pl.get_string_attrib(element, "answers-name"))


def render(element_html: str, data: pl.QuestionData):
    panel_type = data["panel"]

    fpp = FadedParsonsProblem(element_html, data)
    mustache_file = f"pl-faded-parsons-{panel_type}.mustache"

    if panel_type == "question":
        # chevron skips rendering when values are falsy (eg pre-text/post-text/starter)
        html_params = asdict(fpp.to_mustache())
    elif panel_type == "submission":
        html_params = {
            "code": fpp.to_code(),
        }
    elif panel_type == "answer":
        html_params = {"solution_path": fpp.solution_path}
    else:
        raise Exception(f"Invalid panel type: {panel_type}")

    with open(mustache_file, "r") as f:
        return chevron.render(f, html_params).strip()


def parse(element_html: str, data: pl.QuestionData):
    """Parse student's submitted answer (HTML form submission)"""

    def base64_encode(s):
        return base64.b64encode(s.encode("ascii")).decode("ascii")

    fpp = FadedParsonsProblem(element_html, data)

    student_code = fpp.to_code()

    # provide the answer to users of pl-faded-parsons in classic PL style
    data["submitted_answers"][fpp.answers_name] = student_code
    pl.add_submitted_file(data, fpp.out_filename, base64_encode(student_code))