#!/usr/bin/env python3 """Build and check Lernluchs lesson files (.lernluchs). python3 lernluchs_lektion.py check LESSON.lernluchs [--strict] [--json] python3 lernluchs_lektion.py build CARDS.json -o LESSON.lernluchs [--strict] `check` reads a lesson file the way the Lernluchs app does and reports what the app would drop, refuse or get wrong: incomplete cards, unknown kinds, number cards whose result is wrong, "wrong" options that are really right, duplicates, answers the app would split. `build` turns a list of cards in the card generator's JSON format into a lesson file (and checks it). Only the Python standard library is used. The answer rules are a port of the app's (AnswerChecker, Arithmetic); `tests/` in the website repository checks them against the Swift code's output. """ import argparse import base64 import binascii import json import re import sys import unicodedata FORMAT = "lernluchs-lesson" CURRENT_VERSION = 4 KINDS = ("word", "sentence", "fact", "number", "spelling", "dictation") VOCABULARY = ("word", "sentence") # ---- how the app reads answers (port of AnswerChecker.swift) --------------------- CONTRACTIONS = [ ("can't", "cannot"), ("won't", "will not"), ("shan't", "shall not"), ("n't", " not"), ("i'm", "i am"), ("'re", " are"), ("'ve", " have"), ("'ll", " will"), ("'d", " would"), ("that's", "that is"), ("it's", "it is"), ("what's", "what is"), ("there's", "there is"), ("here's", "here is"), ("he's", "he is"), ("where's", "where is"), ("who's", "who is"), ("let's", "let us"), ("can not", "cannot"), ] def canonical(text): """Lowercase, contractions expanded, punctuation removed, single spaces.""" s = text.lower() for typographic in ("’", "‘", "´", "`"): s = s.replace(typographic, "'") for short, long in CONTRACTIONS: s = s.replace(short, long) kept = "".join(ch if unicodedata.category(ch)[0] in "LMN" else " " for ch in s) return " ".join(kept.split()) def tidy(text): """Spaces collapsed, ends trimmed, a final "." or "!" dropped, typographic apostrophes plain.""" s = " ".join(text.replace("’", "'").split()) while s and s[-1] in ".!": s = s[:-1] return s.strip() def removing_ending_notation(text): return re.sub(r"/\s*-\w+", "", text) def split_alternatives(solution): """Splits at , ; / outside brackets.""" parts, current, depth = [], "", 0 for ch in solution: if ch in "([": depth += 1 current += ch elif ch in ")]": depth = max(0, depth - 1) current += ch elif ch in ",;/": if depth == 0: parts.append(current) current = "" else: current += ch else: current += ch parts.append(current) return [part for part in parts if canonical(part) != ""] def bracket_variants(text): """Every reading of the brackets: each group left out or kept, at most four groups expanded.""" if "(" not in text and "[" not in text: return [text] pieces, current, depth = [], "", 0 for ch in text: if ch in "([": if depth == 0: pieces.append((current, False)) current = "" else: current += ch depth += 1 elif ch in ")]": depth = max(0, depth - 1) if depth == 0: pieces.append((current, True)) current = "" else: current += ch else: current += ch pieces.append((current, False)) variants, groups = [""], 0 for piece, is_group in pieces: if is_group and groups < 4: groups += 1 choices = [""] options = [o for o in piece.split("/") if o] + ([piece] if "/" in piece else []) for choice in options: if choice not in choices: choices.append(choice) variants = [f"{v} {c} " for v in variants for c in choices] else: variants = [v + piece for v in variants] return variants def accepted_answers(solution, kind="word"): """Every canonical text that counts as right (word and fact: also each alternative).""" if kind in ("word", "fact"): alternatives = split_alternatives(removing_ending_notation(solution)) + [solution] else: alternatives = [solution] result = set() for alternative in alternatives: for variant in bracket_variants(alternative): c = canonical(variant) if c: result.add(c) return result def spelling_answers(solution): """Picture words and dictation: alternatives split at ";" only, checked exactly.""" return [t for t in (tidy(part) for part in solution.split(";")) if t] def tip_target(solution, kind): """The first alternative without brackets: what the app asks for in tips and reads aloud.""" if kind in ("spelling", "dictation"): answers = spelling_answers(solution) return answers[0] if answers else solution if kind not in ("word", "fact"): return solution parts = split_alternatives(removing_ending_notation(solution)) first = parts[0] if parts else solution variants = bracket_variants(first) return " ".join((variants[0] if variants else first).split()) # ---- numbers (port of Arithmetic.swift) --------------------------------------------- def _decimal(raw): s, negative = raw, False if s.startswith("-"): negative, s = True, s[1:] if s == "" or any(c not in "0123456789.," for c in s): return None if "," in s: s = s.replace(".", "").replace(",", ".", 1) elif re.fullmatch(r"\d{1,3}(\.\d{3})+", s): s = s.replace(".", "") if s.count(".") > 1 or s == ".": return None try: value = float(s) except ValueError: return None if value in (float("inf"), float("-inf")) or value != value: return None return -value if negative else value def number(text): """The value of a typed number ("56", "3,5", "1.000", "3/4"), or None.""" s = text.strip() for old, new in (("−", "-"), ("–", "-"), (" ", ""), (" ", ""), (" ", "")): s = s.replace(old, new) if s.startswith("+"): s = s[1:] if s == "": return None parts = s.split("/") if len(parts) == 2: a, b = _decimal(parts[0]), _decimal(parts[1]) if a is None or b is None or b == 0: return None return a / b return _decimal(s) if len(parts) == 1 else None def same(a, b): return abs(a - b) <= 1e-9 * max(1, abs(a), abs(b)) def format_number(value): """Display form: "56", "3,5", "0,333".""" if value == round(value) and abs(value) < 1e15: return str(int(value)) rounded = int(value * 1000 + 0.5) / 1000 if value * 1000 >= 0 else -int(-value * 1000 + 0.5) / 1000 text = f"{int(rounded)}.0" if rounded == int(rounded) else repr(rounded) return text.replace(".", ",") _ALLOWED = set("0123456789 ,.()+-−–·×*:/÷") _OPERATORS = set("+-−–·×*:/÷") _EDGE = set(" ,.+-−–·×*:/÷") _DIGITS = set("0123456789") def _trim_operators(run): chars = list(run) start, end = 0, len(chars) while start < end and chars[start] in _EDGE and (chars[start] != "-" or not (start + 1 < len(chars) and chars[start + 1] in _DIGITS)): start += 1 while end > start and chars[end - 1] in _EDGE: end -= 1 return "".join(chars[start:end]) class _Expression: """Recursive descent over + - * : and brackets.""" def __init__(self, text): self.chars = [c for c in text if c != " "] self.pos = 0 def parse(self): value = self._sum() if value is None or self.pos != len(self.chars) or value in (float("inf"), float("-inf")) or value != value: return None return value def _peek(self): return self.chars[self.pos] if self.pos < len(self.chars) else None def _sum(self): value = self._product() if value is None: return None while self._peek() is not None and self._peek() in "+-−–": op = self._peek() self.pos += 1 rhs = self._product() if rhs is None: return None value = value + rhs if op == "+" else value - rhs return value def _product(self): value = self._factor() if value is None: return None while self._peek() is not None and self._peek() in "·×*:/÷": op = self._peek() self.pos += 1 rhs = self._factor() if rhs is None: return None if op in "·×*": value *= rhs else: if rhs == 0: return None value /= rhs return value def _factor(self): if self._peek() == "(": self.pos += 1 value = self._sum() if value is None or self._peek() != ")": return None self.pos += 1 return value if self._peek() is not None and self._peek() in "-−–": self.pos += 1 inner = self._factor() return None if inner is None else -inner digits = "" while self._peek() is not None and self._peek() in "0123456789,.": digits += self._peek() self.pos += 1 return _decimal(digits) def value_of_task(task): """The value of the one plain expression in a task ("7 · 8 = ?" is 56), or None for word problems and gaps.""" runs, current = [], "" for ch in task: if ch in _ALLOWED: current += ch else: runs.append(current) current = "" runs.append(current) def has_operation(run): chars = [c for c in run if c != " "] return any(c in _OPERATORS and 0 < i < len(chars) - 1 and (chars[i - 1] in _DIGITS or chars[i - 1] == ")") and (chars[i + 1] in _DIGITS or chars[i + 1] == "(") for i, c in enumerate(chars)) candidates = [r for r in (_trim_operators(run) for run in runs) if has_operation(r)] if len(candidates) != 1: return None return _Expression(candidates[0]).parse() def recheck(prompt, answer): """The computed result when the answer is a different number, else None.""" computed = value_of_task(prompt) if computed is None: return None given = number(answer) if given is not None and same(given, computed): return None return format_number(computed) # ---- subjects ---------------------------------------------------------------------------- def is_foreign_language(subject): name = subject.lower().strip() if name in ("", "vokabeln", "latein", "latin", "altgriechisch", "griechisch", "greek", "hebräisch"): return True return name.endswith("isch") or name.endswith("ish") or name == "french" ARTICLES = {"der", "die", "das"} # ---- the lesson file ----------------------------------------------------------------------- def file_version(cards): """The lowest version that holds the cards (what the app writes).""" kinds = {c.get("kind", "word") for c in cards} if "dictation" in kinds: return 4 if "spelling" in kinds: return 3 if kinds <= set(VOCABULARY): return 1 return 2 def _is_emoji_like(text): text = text.strip() return 0 < len(text) <= 12 and not re.search(r"[A-Za-z0-9]", text) def _has_control(text): return any(unicodedata.category(c) == "Cc" and c not in "\n\t" for c in text) class Report: def __init__(self): self.items = [] def error(self, where, message): self.items.append(("error", where, message)) def warn(self, where, message): self.items.append(("warning", where, message)) @property def errors(self): return [i for i in self.items if i[0] == "error"] @property def warnings(self): return [i for i in self.items if i[0] == "warning"] def check_lesson(payload): """Checks a parsed lesson file; returns a Report.""" report = Report() if not isinstance(payload, dict) or payload.get("format") != FORMAT: report.error("file", f'"format" must be "{FORMAT}".') return report version = payload.get("version") if not isinstance(version, int) or isinstance(version, bool) or version < 1: report.error("file", '"version" must be a whole number (1 to 4).') elif version > CURRENT_VERSION: report.error("file", f"Version {version} is newer than this checker knows ({CURRENT_VERSION}); the app may refuse or misread it.") if not isinstance(payload.get("lesson"), str): report.error("file", '"lesson" (the lesson\'s name) must be a string.') elif payload["lesson"].strip() == "": report.warn("file", '"lesson" is empty: the lesson has no name in the app.') subject = payload.get("subject", "") if not isinstance(subject, str): report.error("file", '"subject" must be a string.') subject = "" cards = payload.get("cards") if not isinstance(cards, list) or len(cards) == 0: report.error("file", '"cards" must be a non-empty list.') return report seen_prompts, seen_words = {}, {} usable = [] for number_, card in enumerate(cards, 1): where = f"card {number_}" if not isinstance(card, dict): report.error(where, "is not an object.") continue kind = card.get("kind", "word") where = f"card {number_} ({kind})" prompt, answer = card.get("prompt"), card.get("answer") if kind not in KINDS: report.error(where, f'unknown kind. Allowed: {", ".join(KINDS)}. The app refuses the whole file for this.') continue if not isinstance(prompt, str) or not isinstance(answer, str): report.error(where, '"prompt" and "answer" must both be strings (use "" for an empty prompt).') continue usable.append(card) for name, text in (("prompt", prompt), ("answer", answer)): if _has_control(text): report.error(where, f'"{name}" contains a control character.') if text != text.strip() and text.strip() != "": report.warn(where, f'"{name}" has spaces at its start or end.') has_picture = isinstance(card.get("picture"), str) and card["picture"] != "" if answer.strip() == "": report.error(where, "has no answer: the app drops it.") continue if kind == "dictation": pass elif kind == "spelling": if prompt.strip() == "" and not has_picture: report.error(where, "has neither an emoji (prompt) nor a picture: nothing to show, the app drops it.") elif prompt.strip() == "": report.error(where, "has no prompt: the app drops it.") continue choices = card.get("choices") if choices is not None: if not isinstance(choices, list) or not all(isinstance(c, str) for c in choices): report.error(where, '"choices" must be a list of strings.') choices = None elif kind != "fact": report.warn(where, '"choices" are only used for kind "fact".') if "picture" in card and kind != "spelling": report.warn(where, '"picture" is only used for kind "spelling".') if has_picture: try: raw = base64.b64decode(card["picture"], validate=True) if not raw.startswith(b"\xff\xd8"): report.warn(where, "the picture is not a JPEG (the app expects JPEG, 512 px at most).") elif len(raw) > 400_000: report.warn(where, f"the picture is large ({len(raw) // 1000} kB); 512 px keeps the file small.") except (binascii.Error, ValueError): report.error(where, '"picture" is not valid base64.') if kind == "number": value = number(answer) if value is None: report.error(where, f'the answer "{answer}" is not a number (digits, a German decimal comma, a minus sign; no unit, no words).') elif re.fullmatch(r"\d{1,3}(\.\d{3})+", answer.strip()): report.warn(where, f'"{answer}" is read as {format_number(value)} (a dot before exactly three digits is a thousands separator): write it without.') computed = value_of_task(prompt) if computed is None: if value is not None: report.warn(where, "the task is not a plain expression, so the result could not be recomputed here: recompute it yourself.") elif value is not None and not same(value, computed): report.error(where, f'the answer is {answer}, but "{prompt}" is {format_number(computed)}.') elif kind == "fact": target = tip_target(answer, "fact") if len(target.split()) > 4: report.warn(where, f'the answer "{target}" has more than four words: a child has to type it exactly.') if re.search(r"[,/]", re.sub(r"[(\[][^)\]]*[)\]]", "", answer)): report.warn(where, "a comma or slash outside brackets splits the answer into alternatives (any one is right). Use \";\" for synonyms, and avoid commas in one answer.") if choices is not None and len(choices) not in (0, 3): report.warn(where, f"{len(choices)} wrong options: the app shows the answer and three wrong options.") if choices: right = accepted_answers(answer, "fact") counted = set() for option in choices: if option.strip() == "": report.error(where, "an empty wrong option.") elif canonical(option) in right: report.error(where, f'the wrong option "{option}" counts as a right answer.') elif canonical(option) in counted: report.error(where, f'the wrong option "{option}" appears twice.') counted.add(canonical(option)) elif kind in VOCABULARY: if subject.strip() and not is_foreign_language(subject): report.warn(where, f'vocabulary cards belong to a foreign-language subject; the subject is "{subject}".') elif kind == "dictation": word = tip_target(answer, "dictation") if len(word.split()) > 2 or re.search(r"[.!?,]$", word): report.warn(where, f'a dictation is a single word (a noun with its article), but the answer is "{word}".') if prompt.strip() != "" and not _is_emoji_like(prompt): report.warn(where, f'the prompt is only a hint, ideally one emoji for words that sound alike (Meer/mehr); it is "{prompt}".') if subject.strip() == "": report.warn(where, "the lesson has no subject, so the word is read aloud in English; set the subject (Deutsch, Englisch, ...).") elif kind == "spelling": word = tip_target(answer, "spelling") if prompt.strip() != "" and not _is_emoji_like(prompt): report.warn(where, f'the prompt is shown as the picture: use one emoji, not "{prompt}".') if not is_foreign_language(subject) or subject.lower().strip() == "deutsch": words = word.split() if len(words) != 2 or words[0].lower() not in ARTICLES or not words[1][:1].isupper(): report.warn(where, f'a German picture word is a noun with its article and a capital: "der Hund", not "{word}".') # Duplicates, the way the app sees them. if kind in ("spelling", "dictation"): key = (kind, tidy(answer)) if key in seen_words: report.warn(where, f'the word "{key[1]}" is already card {seen_words[key]}: the app drops the second.') seen_words.setdefault(key, number_) else: key = canonical(prompt) if key in seen_prompts: report.warn(where, f'the same question as card {seen_prompts[key]}: the app drops the second.') seen_prompts.setdefault(key, number_) recordings = payload.get("recordings") if recordings is not None: if not isinstance(recordings, dict): report.error("file", '"recordings" must be an object of file name to base64.') else: for name, data in recordings.items(): if not re.fullmatch(r"[0-9a-f]{16}\.mp3", name) or not isinstance(data, str): report.warn("file", f'recording "{name}" is ignored: names look like 0123456789abcdef.mp3.') if isinstance(version, int) and not isinstance(version, bool) and 1 <= version <= CURRENT_VERSION and usable: minimal = file_version(usable) if version != minimal: report.warn("file", f"version is {version}; the app writes {minimal} for these cards (the file works anyway).") return report def format_report(report, count): lines = [] for level, where, message in report.items: lines.append(f"{'ERROR' if level == 'error' else 'warning'} {where}: {message}") lines.append(f"{count} cards, {len(report.errors)} errors, {len(report.warnings)} warnings.") return "\n".join(lines) # ---- build --------------------------------------------------------------------------------- def card_entry(card): """One card of the generator's JSON format (or already of the file format) as a file entry.""" kind = str(card.get("kind", "word")).strip().lower() kind = {"frage": "fact", "zahl": "number", "diktat": "dictation", "bildwort": "spelling", "picture": "spelling"}.get(kind, kind) entry = {"kind": kind} answer = str(card.get("answer", card.get("word", ""))).strip() alternatives = card.get("alternatives") if isinstance(alternatives, list) and kind in ("word", "fact"): alternatives = [str(a).strip() for a in alternatives if str(a).strip()] if alternatives: answer = "; ".join([answer] + alternatives) entry["answer"] = answer if kind in ("dictation", "spelling"): entry["prompt"] = str(card.get("emoji", card.get("prompt", ""))).strip() else: entry["prompt"] = str(card.get("question", card.get("prompt", card.get("foreign", "")))).strip() wrong = card.get("wrong", card.get("choices")) if isinstance(wrong, list) and kind == "fact": wrong = [str(w).strip() for w in wrong if str(w).strip()] if wrong: entry["choices"] = wrong if kind == "spelling" and isinstance(card.get("picture"), str) and re.fullmatch(r"[A-Za-z0-9+/=]{100,}", card["picture"]): entry["picture"] = card["picture"] return entry def build_lesson(source): """The lesson file's payload from {"lesson", "subject", "cards"} in the generator's format.""" cards = [card_entry(c) for c in source.get("cards", []) if isinstance(c, dict)] payload = { "format": FORMAT, "version": file_version(cards) if cards else 1, "lesson": str(source.get("lesson", source.get("title", ""))).strip(), "cards": [dict(sorted(c.items())) for c in cards], } subject = str(source.get("subject", "")).strip() if subject: payload["subject"] = subject return dict(sorted(payload.items())) def main(argv=None): parser = argparse.ArgumentParser(description="Build and check Lernluchs lesson files.") commands = parser.add_subparsers(dest="command", required=True) check = commands.add_parser("check", help="check a .lernluchs file") check.add_argument("file") check.add_argument("--strict", action="store_true", help="warnings count as errors") check.add_argument("--json", action="store_true", help="the report as JSON") build = commands.add_parser("build", help="make a .lernluchs file from a JSON list of cards") build.add_argument("source") build.add_argument("-o", "--output", required=True) build.add_argument("--strict", action="store_true", help="warnings count as errors") args = parser.parse_args(argv) if args.command == "check": try: with open(args.file, encoding="utf-8") as handle: payload = json.load(handle) except (OSError, ValueError) as error: print(f"ERROR file: cannot read {args.file} as JSON ({error}).") return 1 else: try: with open(args.source, encoding="utf-8") as handle: source = json.load(handle) except (OSError, ValueError) as error: print(f"ERROR input: cannot read {args.source} as JSON ({error}).") return 1 if isinstance(source, list): source = {"cards": source} payload = build_lesson(source) report = check_lesson(payload) count = len(payload.get("cards", [])) if isinstance(payload, dict) and isinstance(payload.get("cards"), list) else 0 failed = bool(report.errors) or (args.strict and bool(report.warnings)) if args.command == "check" and args.json: print(json.dumps({"cards": count, "ok": not failed, "errors": [list(i[1:]) for i in report.errors], "warnings": [list(i[1:]) for i in report.warnings]}, ensure_ascii=False, indent=2)) else: print(format_report(report, count)) if args.command == "build": if failed: print("Not written: fix the errors first.") return 1 with open(args.output, "w", encoding="utf-8") as handle: json.dump(payload, handle, ensure_ascii=False, indent=2) print(f"Written: {args.output}") return 1 if failed else 0 if __name__ == "__main__": sys.exit(main())