|
| 1 | +"""Compiles a set the way Lambda Feedback makes a PDF of it, and reads the errors back. |
| 2 | +
|
| 3 | +Lambda Feedback renders question PDFs with lambda-feedback/PDF-generator: pandoc with |
| 4 | +``template.latex`` beside this file, then xelatex. Markdown that pipeline refuses is a |
| 5 | +fault in the set, so the whole set is compiled once here and each LaTeX error is traced |
| 6 | +back to the field it came from. |
| 7 | +
|
| 8 | +The trick for tracing is a marker: the document handed to pandoc carries a raw-LaTeX |
| 9 | +comment naming the field before each field's markdown, and pandoc copies raw blocks |
| 10 | +through untouched. ``xelatex -file-line-error`` then reports every error as |
| 11 | +``set.tex:<line>: <message>``, and the last marker above that line names the field. |
| 12 | +
|
| 13 | +pandoc and xelatex are both optional, as they are everywhere else in in2lambda: without |
| 14 | +them this reports what to install rather than raising. |
| 15 | +""" |
| 16 | + |
| 17 | +import re |
| 18 | +import shutil |
| 19 | +import subprocess |
| 20 | +import tempfile |
| 21 | +from pathlib import Path |
| 22 | + |
| 23 | +from in2lambda.api.problem import Problem |
| 24 | + |
| 25 | +_TEMPLATE = Path(__file__).with_name("template.latex") |
| 26 | +"""The PDF generator's own pandoc template - see the README beside it.""" |
| 27 | + |
| 28 | +_TOOLS = { |
| 29 | + "pandoc": "pandoc (see https://pandoc.org/installing.html)", |
| 30 | + "xelatex": ( |
| 31 | + "xelatex (apt install texlive-xetex texlive-latex-recommended" |
| 32 | + " texlive-latex-extra texlive-science texlive-lang-chinese" |
| 33 | + " fonts-noto-core fonts-noto-cjk)" |
| 34 | + ), |
| 35 | +} |
| 36 | + |
| 37 | +_SET = "The set" |
| 38 | +"""Where an error that is not inside any one field is reported against.""" |
| 39 | + |
| 40 | +_MARKER = "% in2lambda: " |
| 41 | + |
| 42 | +_ERROR = re.compile( |
| 43 | + r"^(?:\./)?(\S+\.(?:tex|sty|cls|def|cfg|fd|ltx)):(\d+): (.+)$", re.MULTILINE |
| 44 | +) |
| 45 | +"""One ``-file-line-error`` line. The file is only ``set.tex`` for the set's own text.""" |
| 46 | + |
| 47 | +_IMAGE = re.compile(r"(!\[[^\]]*\]\()([^)]*)(\))") |
| 48 | +"""A markdown image with its path apart, so that the path can be rewritten or dropped.""" |
| 49 | + |
| 50 | +_TIMEOUT = 120 |
| 51 | +"""Seconds for pandoc or xelatex. A set that takes longer is reported, not waited for.""" |
| 52 | + |
| 53 | + |
| 54 | +def missing_tools() -> list[str]: |
| 55 | + """What is needed to compile a set but is not installed, each saying how to get it. |
| 56 | +
|
| 57 | + Returns: |
| 58 | + One line per missing tool, or an empty list if a set can be compiled here. |
| 59 | + """ |
| 60 | + return [hint for tool, hint in _TOOLS.items() if shutil.which(tool) is None] |
| 61 | + |
| 62 | + |
| 63 | +def problems(fields: list[tuple[str, str]], images: list[str]) -> list[Problem]: |
| 64 | + """Everything the PDF generator's pandoc and xelatex refuse, by the field it is in. |
| 65 | +
|
| 66 | + Args: |
| 67 | + fields: Every markdown field of the set in the order it is written, each with |
| 68 | + the location - ``Question 1 "Title", part (a), text`` - to report against. |
| 69 | + images: Every image path the set's questions hold. Those that exist are put |
| 70 | + beside the compiled document under their file name, since that is how the |
| 71 | + export refers to them; a reference to any other is dropped, as the image |
| 72 | + check already reports it. |
| 73 | +
|
| 74 | + Returns: |
| 75 | + One :class:`~in2lambda.api.problem.Problem` per distinct LaTeX error. An empty |
| 76 | + list means the set compiles as Lambda Feedback will compile it. |
| 77 | + """ |
| 78 | + if missing := missing_tools(): |
| 79 | + return [ |
| 80 | + Problem( |
| 81 | + _SET, |
| 82 | + "not compiled as the PDF generator would: install " |
| 83 | + + " and ".join(missing), |
| 84 | + ) |
| 85 | + ] |
| 86 | + |
| 87 | + try: |
| 88 | + return _compiled(fields, images) |
| 89 | + except subprocess.TimeoutExpired as expired: |
| 90 | + # TeX can be made to loop forever, which is itself a fault in the set. |
| 91 | + return [ |
| 92 | + Problem( |
| 93 | + _SET, |
| 94 | + f"the PDF generator cannot compile this: {expired.cmd[0]} did not" |
| 95 | + f" finish within {_TIMEOUT} seconds", |
| 96 | + ) |
| 97 | + ] |
| 98 | + |
| 99 | + |
| 100 | +def _compiled(fields: list[tuple[str, str]], images: list[str]) -> list[Problem]: |
| 101 | + """The set run through pandoc and then xelatex in a directory of its own.""" |
| 102 | + with tempfile.TemporaryDirectory() as directory: |
| 103 | + work = Path(directory) |
| 104 | + available = set() |
| 105 | + for image in images: |
| 106 | + if Path(image).is_file(): |
| 107 | + shutil.copy(image, work / Path(image).name) |
| 108 | + available.add(Path(image).name) |
| 109 | + |
| 110 | + run = subprocess.run( |
| 111 | + [ |
| 112 | + "pandoc", |
| 113 | + "-f", |
| 114 | + "markdown-implicit_figures", |
| 115 | + "-t", |
| 116 | + "latex", |
| 117 | + "-s", |
| 118 | + f"--template={_TEMPLATE}", |
| 119 | + "-o", |
| 120 | + "set.tex", |
| 121 | + ], |
| 122 | + input=_marked_document(fields, available), |
| 123 | + capture_output=True, |
| 124 | + text=True, |
| 125 | + # Not the locale's encoding: a set holding any non-ASCII character would |
| 126 | + # then fail to even be handed over under, say, LC_ALL=C. |
| 127 | + encoding="utf-8", |
| 128 | + cwd=work, |
| 129 | + timeout=_TIMEOUT, |
| 130 | + ) |
| 131 | + if run.returncode: |
| 132 | + return [Problem(_SET, f"pandoc cannot read the set: {run.stderr.strip()}")] |
| 133 | + |
| 134 | + latex = (work / "set.tex").read_text(encoding="utf-8") |
| 135 | + run = subprocess.run( |
| 136 | + [ |
| 137 | + "xelatex", |
| 138 | + "-interaction=nonstopmode", |
| 139 | + "-file-line-error", |
| 140 | + "-no-shell-escape", |
| 141 | + "set.tex", |
| 142 | + ], |
| 143 | + stdin=subprocess.DEVNULL, |
| 144 | + capture_output=True, |
| 145 | + text=True, |
| 146 | + encoding="utf-8", |
| 147 | + cwd=work, |
| 148 | + timeout=_TIMEOUT, |
| 149 | + ) |
| 150 | + return _reported(run.stdout, _locations(latex)) |
| 151 | + |
| 152 | + |
| 153 | +def _marked_document(fields: list[tuple[str, str]], available: set[str]) -> str: |
| 154 | + """The whole set as one markdown document, each field under a marker naming it. |
| 155 | +
|
| 156 | + The fence is four backticks so that a field which itself contains a code block |
| 157 | + cannot close the marker's raw-LaTeX block early. |
| 158 | + """ |
| 159 | + blocks = [] |
| 160 | + for location, markdown in fields: |
| 161 | + markdown = _IMAGE.sub( |
| 162 | + lambda image: ( |
| 163 | + f"{image[1]}{Path(image[2]).name}{image[3]}" |
| 164 | + if Path(image[2]).name in available |
| 165 | + else "" |
| 166 | + ), |
| 167 | + markdown, |
| 168 | + ) |
| 169 | + blocks.append(f"````{{=latex}}\n{_MARKER}{location}\n````\n\n{markdown}\n") |
| 170 | + return "\n".join(blocks) |
| 171 | + |
| 172 | + |
| 173 | +def _locations(latex: str) -> list[tuple[int, str]]: |
| 174 | + """Each marker in the generated LaTeX as the line it is on and the field it names.""" |
| 175 | + return [ |
| 176 | + (number, line.partition(_MARKER)[2]) |
| 177 | + for number, line in enumerate(latex.splitlines(), start=1) |
| 178 | + if line.startswith(_MARKER) |
| 179 | + ] |
| 180 | + |
| 181 | + |
| 182 | +def _reported(log: str, locations: list[tuple[int, str]]) -> list[Problem]: |
| 183 | + """The xelatex log's errors as problems, each against the field it happened in. |
| 184 | +
|
| 185 | + The same error repeated - a command used twice, say - is one problem, since the |
| 186 | + author has one thing to go and fix. |
| 187 | + """ |
| 188 | + found = [] |
| 189 | + for error in _ERROR.finditer(log): |
| 190 | + file, line, message = error[1], int(error[2]), error[3].strip() |
| 191 | + where = _SET |
| 192 | + if file == "set.tex": |
| 193 | + for number, location in locations: |
| 194 | + if number <= line: |
| 195 | + where = location |
| 196 | + problem = Problem(where, f"the PDF generator cannot compile this: {message}") |
| 197 | + if problem not in found: |
| 198 | + found.append(problem) |
| 199 | + return found |
0 commit comments