mdq 0.1.0__py3-none-any.whl

mdq/__init__.py

@@ -0,0 +1,19 @@
+"""mdq: tools for the MDQ (Markdown Questions) file format."""
+
+from .errors import ParseError
+from .loading import Diagnostic, InvalidDocument, Loaded, Severity, load, parse
+from .models import Exam, Question
+
+__version__ = "0.1.0"
+__all__ = [
+    "Question",
+    "Exam",
+    "ParseError",
+    #: Loading
+    "load",
+    "parse",
+    "Loaded",
+    "Diagnostic",
+    "Severity",
+    "InvalidDocument",
+]

mdq/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

mdq/_diagnostics.py

@@ -0,0 +1,40 @@
+"""
+`Diagnostic`, the one problem shape every stage of `mdq.loading`'s
+pipeline reports through -- a parse failure, a pydantic error, a lint
+warning, an unknown frontmatter key.
+
+Split out from `mdq.loading` (which owns and re-exports it) so that
+`mdq.linter` and `mdq.parser` -- both upstream of `mdq.loading` in the
+pipeline -- can report `Diagnostic`s of their own without importing back
+into the module that orchestrates them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Severity = Literal["error", "warning", "info"]
+
+#: Severity, ranked so "at or above" (as `Loaded.validate` uses it) is a
+#: plain integer comparison. Higher is more severe.
+RANK: dict[Severity, int] = {"info": 1, "warning": 2, "error": 3}
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """
+    One problem found while loading a document.
+
+    `path` locates the offending value the way a `jsonschema`
+    `ValidationError.path` or a pydantic error's `loc` does: a tuple of
+    keys/indices from the document's root. `line` is set only for a
+    parse failure tied to a source node, and only when that node's
+    position in the source is known.
+    """
+
+    severity: Severity
+    code: str
+    message: str
+    path: tuple[str | int, ...] = ()
+    line: int | None = None

mdq/cli.py

@@ -0,0 +1,327 @@
+"""
+Command-line interface for mdq.
+
+Usage:
+    mdq validate <question.json|question.yaml>
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated, Literal
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from . import show as _show
+from .convert import export_question, import_question
+from .loading import Diagnostic, InvalidDocument, load, parse
+from .scaffold import QUESTION_TYPES, default_output_path, render_template
+
+app = typer.Typer(
+    name="mdq",
+    help="Tools for the MDQ (Markdown Questions) file format.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+
+Level = Literal["default", "strict"]
+
+stderr = Console(file=sys.stderr, highlight=False, force_terminal=True)
+
+
+def main() -> None:
+    """
+    Main entry point to the CLI.
+    """
+    app()
+
+
+@app.command()
+def validate(
+    file: Path = typer.Argument(
+        ...,
+        help="Path to a question or exam document (.mdq.md, .mdq, .yaml, .yml, or .json).",
+    ),
+    level: Level = typer.Option(
+        "default",
+        "--level",
+        case_sensitive=False,
+        help=(
+            "'default' prints errors and warnings; 'strict' also prints "
+            "info-level diagnostics. Every lint rule always runs -- this "
+            "only changes what gets printed."
+        ),
+    ),
+) -> None:
+    """
+    Validate a question or exam file, and lint it for issues beyond
+    what a schema can express.
+    """
+
+    try:
+        loaded = load(file)
+    except (OSError, ValueError) as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=2)
+
+    exit_code = _print_result(file, loaded.diagnostics, level=level)
+    if exit_code:
+        raise typer.Exit(code=exit_code)
+
+
+@app.command()
+def new(
+    question_type: str = typer.Argument(
+        ...,
+        help=f"Question type to scaffold ({', '.join(QUESTION_TYPES)}).",
+    ),
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            ...,
+            "-o",
+            "--output",
+            help="Where to write the new question file (default: <type>.mdq.md).",
+        ),
+    ] = None,
+    complete: bool = typer.Option(
+        False,
+        "--complete",
+        help=(
+            "Illustrate every feature the question type supports, "
+            "instead of a bare-bones example."
+        ),
+    ),
+) -> None:
+    """
+    Scaffold a new question document.
+    """
+
+    try:
+        content = render_template(question_type, complete=complete)
+    except KeyError:
+        valid = ", ".join(QUESTION_TYPES)
+        typer.echo(
+            f"error: unknown question type {question_type!r} (expected one of: {valid})",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    path = output or default_output_path(question_type)
+    if path.exists():
+        typer.echo(f"error: {path} already exists", err=True)
+        raise typer.Exit(code=2)
+
+    path.write_text(content, encoding="utf-8")
+    typer.echo(f"wrote {path}")
+
+
+@app.command("import")
+def import_(
+    file: Path = typer.Argument(
+        ...,
+        help="Path to a question file in an external format (e.g. Aiken, GIFT).",
+    ),
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "-o",
+            "--output",
+            help="Where to write the imported MDQ document (default: print to stdout).",
+        ),
+    ] = None,
+    format: str | None = typer.Option(
+        None,
+        "--format",
+        help="External format to import from (default: inferred from FILE's extension).",
+    ),
+) -> None:
+    """
+    Import a question from an external format into MDQ Markdown.
+    """
+
+    if not file.is_file():
+        typer.echo(f"error: file not found: {file}", err=True)
+        raise typer.Exit(code=2)
+
+    fmt = format or _format_from_suffix(file)
+    if fmt is None:
+        typer.echo(
+            f"error: cannot infer format from {file} -- pass --format",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    source = file.read_text(encoding="utf-8")
+    try:
+        question = import_question(source, format=fmt)
+    except (ValueError, NotImplementedError) as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=1)
+
+    _write_output(str(question), output)
+
+
+@app.command()
+def export(
+    file: Path = typer.Argument(
+        ...,
+        help="Path to an MDQ question document (.mdq.md or .mdq).",
+    ),
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "-o",
+            "--output",
+            help="Where to write the exported document (default: print to stdout).",
+        ),
+    ] = None,
+    format: str | None = typer.Option(
+        None,
+        "--format",
+        help=(
+            "External format to export to (default: inferred from -o's "
+            "extension, falling back to 'aiken')."
+        ),
+    ),
+) -> None:
+    """
+    Export an MDQ question document to an external format.
+    """
+
+    if not file.is_file():
+        typer.echo(f"error: file not found: {file}", err=True)
+        raise typer.Exit(code=2)
+
+    fmt = format or (output and _format_from_suffix(output)) or "aiken"
+
+    source = file.read_text(encoding="utf-8")
+    try:
+        question = parse(source, kind="question", ids="fill")
+    except InvalidDocument as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=1)
+
+    try:
+        rendered = export_question(question, format=fmt)
+    except (ValueError, TypeError, NotImplementedError) as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=1)
+
+    _write_output(rendered, output)
+
+
+@app.command()
+def show(
+    file: Path = typer.Argument(
+        ...,
+        help="Path to a question or exam document (.mdq.md or .mdq), or - for stdin.",
+    ),
+    no_answer_key: bool = typer.Option(
+        False,
+        "--no-answer-key",
+        help=(
+            "Hide anything that reveals the correct answer (correctness "
+            "marks, an essay's answer key, a numeric answer, ...), as if "
+            "previewing the question for a student."
+        ),
+    ),
+    width: int | None = typer.Option(
+        None,
+        "--width",
+        help="Console width to render at (default: the terminal's own width).",
+    ),
+) -> None:
+    """
+    Show the parsed representation of a question or exam document.
+
+    Renders rich-text fields (preamble, stem, epilogue, choice text,
+    feedback, ...) as Markdown and everything else as structured
+    metadata, so the document's shape is easy to check at a glance.
+    """
+
+    console = Console(
+        file=sys.stdout,
+        width=width,
+        highlight=False,
+        force_terminal=True,
+    )
+    error_console = Console(
+        file=sys.stderr,
+        highlight=False,
+        force_terminal=True,
+    )
+
+    # Everything below that can embed a path or an exception message is
+    # printed as a `Text` object, never spliced into a markup `str` --
+    # `file` and `exc` can both carry document/filesystem content with
+    # square brackets, which Rich would otherwise parse as markup (and,
+    # for a stray closing tag like `[/]`, raise instead of print).
+    #
+    # A `Path` source resolves an exam's `include:` entries against its
+    # own directory automatically (see `mdq.load`); stdin has no
+    # directory to resolve against, so it is read as plain text instead.
+    source = sys.stdin.read() if str(file) == "-" else file
+
+    try:
+        _show.show_source(source, console, show_answer_key=not no_answer_key)
+    except OSError as exc:
+        error_console.print("[b red]error:[/]", Text(f"could not read {file}: {exc}"))
+        raise typer.Exit(code=2)
+    except (ValueError, InvalidDocument) as exc:
+        error_console.print("[b red]error:[/]", Text(str(exc)))
+        raise typer.Exit(code=1)
+
+
+#
+# Utilities
+#
+FORMAT_SUFFIX_ALIASES = {"xml": "moodle-xml", "moodlexml": "moodle-xml"}
+
+
+def _format_from_suffix(file: Path) -> str | None:
+    """
+    Infer a converter format name from a file's extension, e.g. `.aiken`
+    -> "aiken". Returns None if the file has no extension.
+    """
+    suffix = file.suffix.lstrip(".")
+    if not suffix:
+        return None
+    return FORMAT_SUFFIX_ALIASES.get(suffix, suffix)
+
+
+def _write_output(content: str, output: Path | None) -> None:
+    if output is None:
+        typer.echo(content)
+    else:
+        output.write_text(content, encoding="utf-8")
+        typer.echo(f"wrote {output}")
+
+
+def _print_result(file: Path, diagnostics: list[Diagnostic], *, level: Level) -> int:
+    """
+    Print one line per diagnostic and return the process exit code.
+
+    `level="default"` hides `info`-severity diagnostics; `strict` prints
+    everything. Either way, only an `error` fails the exit code -- a
+    warning or an info diagnostic is advisory.
+    """
+    has_error = any(d.severity == "error" for d in diagnostics)
+    typer.echo(f"{'FAIL' if has_error else 'OK':<5} {file}", err=has_error)
+
+    shown = diagnostics if level == "strict" else [d for d in diagnostics if d.severity != "info"]
+    for d in shown:
+        location = "/".join(str(part) for part in d.path) or "<root>"
+        if d.line is not None:
+            location = f"{location}:{d.line}"
+        typer.echo(f"  {d.severity:<7} [{d.code}] {location}: {d.message}", err=True)
+
+    return 1 if has_error else 0
+
+
+if __name__ == "__main__":
+    main()

mdq/convert/__init__.py

@@ -0,0 +1,14 @@
+"""
+Convert questions to different formats.
+"""
+
+from .base import export_question, import_question, register_format
+
+__all__ = ["import_question", "export_question"]
+
+
+register_format("aiken", converter="mdq.convert.aiken:Aiken")
+register_format("moodle-xml", converter="mdq.convert.moodle_xml:MoodleXml")
+register_format("gift", converter="mdq.convert.gift:Gift")
+
+del register_format

mdq/convert/aiken.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from string import ascii_lowercase
+
+from ..models import MultipleChoiceQuestion, Question, ScoredChoice
+from .base import ConversionBase
+from .parser import StringParser
+
+CHOICE_REGEX = re.compile(r"(?P<letter>[a-zA-Z])[.)]\s+(?P<choice>[^\n]*)")
+NEWLINE_REGEX = re.compile(r"\s*\n\s*")
+
+__all__ = ["Aiken", "AikenQuestion", "AikenParser", "CHOICE_REGEX"]
+
+
+class Aiken(ConversionBase["AikenQuestion"]):
+    """
+    Aiken is a very simple format for multiple choice questions.
+
+    ```
+    Question stem
+
+    A. Option 1
+    B. Option 2
+    C. Option 3
+
+    ANSWER: a
+    ```
+
+    Aiken carries no metadata, so a conversion drops `id`, `title` and every
+    feedback string, and collapses partial credit to 1.0 on the highest
+    scoring choice and 0.0 elsewhere.
+
+    For more details: https://docs.moodle.org/en/Aiken_format
+    """
+
+    supports = {"multiple-choice": "both"}
+
+    def from_mdq(self, question: Question) -> AikenQuestion:
+        if not isinstance(question, MultipleChoiceQuestion):
+            raise ValueError(f"Aiken does not support {question.type!r} questions")
+
+        scores = [choice.score for choice in question.choices]
+        if any(score is None for score in scores):
+            raise ValueError(
+                "cannot convert to Aiken: every choice must have a score"
+            )
+
+        parts = [question.preamble, question.stem, question.epilogue]
+        return AikenQuestion(
+            stem="\n\n".join(filter(None, parts)),
+            choices=[choice.text for choice in question.choices],
+            # `-i` breaks ties towards the first of the highest scoring choices.
+            answer=max(range(len(scores)), key=lambda i: (scores[i], -i)),
+        )
+
+    def to_mdq(self, aiken: AikenQuestion) -> MultipleChoiceQuestion:
+        return MultipleChoiceQuestion(
+            stem=aiken.stem,
+            choices=[
+                ScoredChoice(text=choice, score=1.0 if i == aiken.answer else 0.0)
+                for i, choice in enumerate(aiken.choices)
+            ],
+        )
+
+    def parse(self, source: str) -> AikenQuestion:
+        parser = AikenParser(source)
+        return parser.parse()
+
+
+@dataclass
+class AikenQuestion:
+    stem: str
+    choices: list[str]
+    answer: int
+
+    def __post_init__(self) -> None:
+        # A choice occupies exactly one Aiken line, so a newline in its text
+        # would render source that no longer reparses.
+        self.choices = [NEWLINE_REGEX.sub(" ", text).strip() for text in self.choices]
+
+        if len(self.choices) > len(ascii_lowercase):
+            raise ValueError(
+                f"Aiken supports at most {len(ascii_lowercase)} choices, "
+                f"got {len(self.choices)}"
+            )
+        if not 0 <= self.answer < len(self.choices):
+            raise ValueError(
+                f"answer index {self.answer} does not reference one of the "
+                f"{len(self.choices)} choices"
+            )
+
+    def __str__(self) -> str:
+        lines = [self.stem, ""]
+        for i, choice in enumerate(self.choices):
+            letter = ascii_lowercase[i]
+            lines.append(f"{letter}. {choice}")
+
+        answer = ascii_lowercase[self.answer]
+        lines.append("")
+        lines.append(f"ANSWER: {answer}")
+        return "\n".join(lines)
+
+
+class AikenParser(StringParser[AikenQuestion]):
+    def start(self):
+        stem_lines = []
+
+        while not (m := self.match_group(CHOICE_REGEX, full=True)):
+            stem_lines.append(self.read())
+
+        choices = [self._choice_text(m, index=0)]
+        while m := self.match_group(CHOICE_REGEX, full=True):
+            choices.append(self._choice_text(m, index=len(choices)))
+
+        self.ws()
+        self.expect("ANSWER:", full=False)
+        self.ws()
+
+        char = self.read().strip().lower()
+        if len(char) != 1 or char not in ascii_lowercase:
+            self.error("answer must be a single letter")
+        answer = ascii_lowercase.index(char)
+
+        if not 0 <= answer < len(choices):
+            self.error(
+                f"ANSWER {char!r} does not reference one of the "
+                f"{len(choices)} parsed choices"
+            )
+
+        return AikenQuestion(
+            stem="\n".join(stem_lines).strip(),
+            choices=choices,
+            answer=answer,
+        )
+
+    def _choice_text(self, match: dict[str, str], *, index: int) -> str:
+        """
+        Validate that a matched choice's letter is the expected sequential
+        letter (a, b, c, ...) for its position, then return its text.
+        """
+        letter = match["letter"].lower()
+        if index >= len(ascii_lowercase):
+            self.error(f"Aiken supports at most {len(ascii_lowercase)} choices")
+        expected = ascii_lowercase[index]
+        if letter != expected:
+            self.error(
+                f"expected choice {expected.upper()!r}, got {letter.upper()!r}"
+            )
+        return match["choice"]

mdq/convert/base.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import importlib
+from typing import Any, ClassVar, Literal
+
+from ..models import Question
+from ..types import QuestionType
+
+CONVERSION_REGISTRY: dict[str, ConversionBase | str] = {}
+
+
+class ConversionBase[Q]:
+    """
+    Base class for conversion types.
+    """
+
+    supports: ClassVar[dict[QuestionType, Literal["import", "export", "both"]]]
+
+    def to_mdq(self, external: Q, /) -> Question:
+        """
+        Import question to a MDQ representation.
+        """
+        raise NotImplementedError
+
+    def from_mdq(self, mdq: Question, /) -> Q:
+        """
+        Convert MDQ question to the external question format
+        """
+        raise NotImplementedError
+
+    def render(self, external: Q, /) -> str:
+        """
+        Render the external format as a string.
+        """
+        return str(external)
+
+    def parse(self, source: str, /) -> Q:
+        """
+        Parse source code in the external format into the internal
+        representation.
+        """
+        raise NotImplementedError
+
+
+def register_format(format: str, *, converter: str | ConversionBase):
+    """
+    Associate a format to the given conversion class instance.
+    """
+    CONVERSION_REGISTRY[format.lower()] = converter
+
+
+def load_converter(format: str) -> ConversionBase[Any]:
+    """
+    Load a conversion instance from the registry.
+    """
+    format = format.lower()
+    try:
+        converter = CONVERSION_REGISTRY[format]
+    except KeyError:
+        raise ValueError(f"Unknown format: {format}")
+
+    if isinstance(converter, str):
+        mod_name, cls_name = converter.split(":")
+        mod = importlib.import_module(mod_name)
+        converter_cls = getattr(mod, cls_name)
+        if not (
+            isinstance(converter_cls, type) and issubclass(converter_cls, ConversionBase)
+        ):
+            msg = f"invalid registry: {format} is not a valid converter"
+            raise RuntimeError(msg)
+        converter = converter_cls()
+        CONVERSION_REGISTRY[format] = converter
+
+    return converter
+
+
+def import_question(source: str, /, *, format: str) -> Question:
+    """
+    Load a question in the given format from source.
+
+    Args:
+        source: Source code from the external question.
+        format: The external question format.
+    """
+
+    converter = load_converter(format)
+    external = converter.parse(source)
+    return converter.to_mdq(external)
+
+
+def export_question(question: Question, /, *, format: str):
+    """
+    Convert a mdq question to a different format.
+
+    Renders the resulting source code.
+
+    Args:
+        source: Source code from the external question.
+        format: The external question format.
+    """
+    converter = load_converter(format)
+    if question.type not in converter.supports:
+        msg = f"{format!r} does not support {question.type!r} questions"
+        raise TypeError(msg)
+    external = converter.from_mdq(question)
+    return converter.render(external)