python-hwpx-automation 6.0.3__py3-none-any.whl

hwpx_automation/office/exam/__init__.py

@@ -0,0 +1,44 @@
+"""Exam re-typesetting (조판): authored exam Markdown -> school form .hwpx body."""
+
+from __future__ import annotations
+
+from .compose import (
+    ComposePlan,
+    ComposeResult,
+    ParaSpec,
+    compose_exam_into_form,
+    lower_exam,
+    replace_body_region,
+)
+from .ir import ExamDoc, Placeholder, Question, QuestionSet
+from .measure import (
+    SplitReport,
+    column_x_bounds,
+    group_question_blocks,
+    measure_question_splits,
+)
+from .parser import ExamParseError, parse_exam_markdown
+from .profile import FormProfile, FormProfileError, ResolvedStyle, profile_form
+
+__all__ = [  # noqa: RUF022 - frozen public export order
+    "ExamDoc",
+    "Placeholder",
+    "Question",
+    "QuestionSet",
+    "ExamParseError",
+    "parse_exam_markdown",
+    "FormProfile",
+    "FormProfileError",
+    "ResolvedStyle",
+    "profile_form",
+    "column_x_bounds",
+    "group_question_blocks",
+    "measure_question_splits",
+    "SplitReport",
+    "ParaSpec",
+    "lower_exam",
+    "replace_body_region",
+    "ComposePlan",
+    "ComposeResult",
+    "compose_exam_into_form",
+]

hwpx_automation/office/exam/compose.py

@@ -0,0 +1,282 @@
+"""Lower the Exam IR into the school form's body region.
+
+Strategy (Phase-0 grounded): map each role onto the form's EXISTING style,
+attach keepWithNext (column cohesion) to every paragraph of a 문항 except its
+last, and INSERT into the body region [body_start..body_end] — never append
+(Hancom drops appended content)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from hwpx.document import HwpxDocument
+
+from ..form_fill.fit.wordbox import (
+    detect_overflow,
+    extract_cell_clips,
+    extract_glyph_boxes,
+)
+from ..rendering import resolve_hancom_oracle
+from .ir import ExamDoc, Question, QuestionSet
+from .measure import measure_question_splits
+from .parser import parse_exam_markdown
+from .profile import FormProfile, ResolvedStyle, profile_form
+
+
+@dataclass(slots=True)
+class ParaSpec:
+    text: str
+    role: str  # key into FormProfile.role_styles
+    keep_with_next: bool
+    is_question_head: bool
+    question_number: str | None
+
+
+def _choice_role(n_choices: int, idx: int) -> str:
+    # answer-row styles encode a "rows" hint; default to choice1, fall back gracefully
+    return "choice1"
+
+
+def _lower_question(q: Question) -> list[ParaSpec]:
+    specs: list[ParaSpec] = [
+        ParaSpec(
+            text=f"{q.number}. {q.stem}".rstrip(),
+            role="number",
+            keep_with_next=True,
+            is_question_head=True,
+            question_number=q.number,
+        )
+    ]
+    for i, choice in enumerate(q.choices):
+        specs.append(
+            ParaSpec(
+                text=choice,
+                role=_choice_role(len(q.choices), i),
+                keep_with_next=True,
+                is_question_head=False,
+                question_number=q.number,
+            )
+        )
+    # Placeholders ([그림N]/[표N]/[식N]) are preserved verbatim INSIDE the stem text
+    # by the parser (in authored order), so they are NOT re-emitted here — doing so
+    # rendered each one twice (once inline, once standalone). The Placeholder IR
+    # entries remain as metadata for the gate's integrity check.
+    if specs:
+        specs[
+            -1
+        ].keep_with_next = False  # last para of the 문항 may break before the next
+    return specs
+
+
+def lower_exam(exam: ExamDoc, profile: FormProfile) -> list[ParaSpec]:
+    specs: list[ParaSpec] = []
+    for block in exam.blocks:
+        if isinstance(block, QuestionSet):
+            specs.append(
+                ParaSpec(
+                    text=block.passage,
+                    role="box",
+                    keep_with_next=True,
+                    is_question_head=False,
+                    question_number=None,
+                )
+            )
+            for member in block.members:
+                specs.extend(_lower_question(member))
+        else:
+            specs.extend(_lower_question(block))
+    # drop roles the form lacks -> fall back to "normal"
+    for s in specs:
+        if s.role not in profile.role_styles:
+            s.role = "normal"
+    return specs
+
+
+def _keep_para_pr(
+    doc: HwpxDocument, base: ResolvedStyle, keep: bool, cache: dict
+) -> str | None:
+    key = (base.name, keep)
+    if key in cache:
+        return cache[key]
+    pid = doc.oxml.headers[0].ensure_paragraph_format(
+        base_para_pr_id=base.para_pr_id,
+        break_setting={"keep_with_next": keep, "keep_lines": True},
+    )
+    cache[key] = pid
+    return pid
+
+
+@dataclass(slots=True)
+class ComposePlan:
+    """Snapshot of a pending composition: specs + the target profile.
+
+    Passed to replace_body_region when the caller wants to defer materialization
+    (e.g. inspect specs before writing to the document)."""
+
+    specs: list[ParaSpec]
+    profile: FormProfile
+
+
+def replace_body_region(
+    doc: HwpxDocument, profile: FormProfile, specs: list[ParaSpec]
+) -> dict[str, int]:
+    section = doc.sections[0]
+    paragraphs = section.paragraphs
+    start, end = profile.body_start, profile.body_end
+    old_slots = [
+        paragraphs[i] for i in range(start, end + 1)
+    ]  # capture wrappers up front
+
+    cache: dict = {}
+    temp = []
+    for spec in specs:
+        style = profile.role_styles.get(spec.role) or profile.role_styles["normal"]
+        para_pr_id = _keep_para_pr(doc, style, spec.keep_with_next, cache)
+        temp.append(
+            section.add_paragraph(  # appended to tail; cloned into body below, then removed
+                spec.text,
+                para_pr_id_ref=para_pr_id,
+                style_id_ref=style.style_id,
+                char_pr_id_ref=style.char_pr_id,
+                inherit_style=False,
+            )
+        )
+
+    section.insert_paragraphs(start, temp)  # deep-clone into the body
+    for wrapper in reversed(temp):
+        section.remove_paragraph(wrapper)  # drop the temporary tail copies
+    for wrapper in old_slots:
+        section.remove_paragraph(wrapper)  # drop the old form slots
+    section.mark_dirty()
+
+    # `inserted` is index-aligned with `specs`; each 문항 head now lives at
+    # body-region offset `start + offset`. Build the convergence anchor map.
+    anchors: dict[str, int] = {}
+    for offset, spec in enumerate(specs):
+        if spec.is_question_head and spec.question_number is not None:
+            anchors[spec.question_number] = start + offset
+    return anchors
+
+
+# ---------------------------------------------------------------------------
+# Convergence driver (Task 8)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ComposeResult:
+    out_path: str
+    render_checked: bool
+    splits: int | None
+    overflow: int | None
+    placeholders_ok: bool
+    rounds: int
+    needs_review: bool
+    notes: tuple[str, ...]
+
+
+def _insert_break(section, head_index: int, kind: str) -> None:
+    attr = "pageBreak" if kind == "page" else "columnBreak"
+    section.paragraphs[head_index].element.set(attr, "1")
+    section.mark_dirty()
+
+
+def compose_exam_into_form(
+    form_path: str,
+    exam_md: str,
+    out_path: str,
+    *,
+    oracle=None,
+    max_rounds: int = 2,
+    role_style_names=None,
+) -> ComposeResult:
+    notes: list[str] = []
+    exam = parse_exam_markdown(exam_md)
+    expected_ph = {ph.raw_text for q in exam.iter_questions() for ph in q.placeholders}
+
+    doc = HwpxDocument.open(form_path)
+    prof = profile_form(doc, role_style_names=role_style_names)
+    specs = lower_exam(exam, prof)
+    anchors = replace_body_region(doc, prof, specs)
+    doc.save_to_path(out_path)
+    notes.append(
+        f"composed {len(list(exam.iter_questions()))} 문항 into body"
+        f" [{prof.body_start}..{prof.body_end}]"
+    )
+
+    if oracle is None:
+        oracle = resolve_hancom_oracle()
+    if not oracle.available():
+        notes.append(
+            "oracle unavailable -> render_checked=false, needs_review=true (no silent true)"
+        )
+        return ComposeResult(out_path, False, None, None, True, 0, True, tuple(notes))
+
+    valid_ids = set(anchors)
+    n_questions = len(valid_ids)
+    rounds = 0
+    splits = overflow = None
+    placeholders_ok = True
+    while rounds < max_rounds:
+        rounds += 1
+        pdf = oracle.render_pdf(out_path)
+        if not pdf:
+            notes.append(
+                f"round {rounds}: render returned None -> render_checked=false"
+            )
+            return ComposeResult(
+                out_path, False, None, None, True, rounds, True, tuple(notes)
+            )
+        # Scope split grouping to the composed 문항 numbers so the form's preserved
+        # chrome (e.g. a "2026." year in the 관리박스) never opens a spurious block.
+        report = measure_question_splits(pdf, valid_ids=valid_ids)
+        if report.n_blocks == 0:
+            # None of the composed 문항 are in the extractable text layer: Hancom
+            # exported the body as vector curves (observed on the school 원안지
+            # forms, blank and filled alike). The text-glyph gate is structurally
+            # blind here, so 문항-split / overflow / placeholder integrity are
+            # UNVERIFIABLE — report unverified + needs_review, never a silent 0
+            # (Constitution V). Visual verification (rendered image) is required.
+            notes.append(
+                f"round {rounds}: 0 of {n_questions} composed 문항 found in the"
+                " extractable text layer — Hancom curve-export form; 문항-split,"
+                " overflow and placeholder integrity are UNVERIFIABLE by the text"
+                " gate. Visual verification required (render the output)."
+            )
+            return ComposeResult(
+                out_path, True, None, None, True, rounds, True, tuple(notes)
+            )
+        glyphs = extract_glyph_boxes(pdf)
+        clips = extract_cell_clips(pdf)
+        rendered_text = "".join(g.text for g in glyphs)
+        placeholders_ok = all(
+            ph.replace(" ", "") in rendered_text.replace(" ", "") for ph in expected_ph
+        )
+        overflow = len(detect_overflow(glyphs, clips))
+        splits = report.n_splits
+        notes.append(
+            f"round {rounds}: splits={splits} kinds={report.kinds}"
+            f" overflow={overflow} ph_ok={placeholders_ok} blocks={report.n_blocks}/{n_questions}"
+        )
+        if splits == 0:
+            break
+        # fix: force a break on each straddling 문항's head paragraph, then re-render.
+        # split_ids ⊆ valid_ids = set(anchors) (the grouping is scoped), so every
+        # block_id resolves to a head index.
+        section = doc.sections[0]
+        kind = "page" if report.kinds.get("page") else "column"
+        for block_id in report.split_ids:
+            _insert_break(section, anchors[block_id], kind)
+        doc.save_to_path(out_path)
+
+    needs_review = splits is None or splits > 0 or not placeholders_ok
+    return ComposeResult(
+        out_path,
+        True,
+        splits,
+        overflow,
+        placeholders_ok,
+        rounds,
+        needs_review,
+        tuple(notes),
+    )

hwpx_automation/office/exam/ir.py

@@ -0,0 +1,44 @@
+"""Normalized exam model (Exam IR). Metadata lives in the form's 관리박스, NOT here."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Placeholder:
+    id: str  # e.g. "그림1"
+    kind: str  # "img" | "table" | "equation"
+    raw_text: str  # literal marker preserved verbatim, e.g. "[그림1]"
+
+
+@dataclass(frozen=True, slots=True)
+class Question:
+    number: str  # literal 문항 number text, e.g. "1"
+    stem: str  # 발문
+    choices: tuple[str, ...] = ()  # 답항 ①~⑤, literal markers included
+    points: str | None = None  # 배점, e.g. "3"; None if absent
+    placeholders: tuple[
+        Placeholder, ...
+    ] = ()  # [그림N]/[표N]/[식N] referenced by this 문항
+
+
+@dataclass(frozen=True, slots=True)
+class QuestionSet:  # 세트문제 (shared 공통지문)
+    passage: str
+    rng: str  # e.g. "3∼4"
+    members: tuple[Question, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ExamDoc:
+    title: str = ""
+    blocks: tuple[Question | QuestionSet, ...] = ()
+
+    def iter_questions(self) -> Iterator[Question]:
+        for block in self.blocks:
+            if isinstance(block, QuestionSet):
+                yield from block.members
+            else:
+                yield block

hwpx_automation/office/exam/measure.py

@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure render-geometry helpers for the 문항-split oracle gate.
+
+Lifted from the Phase-0 spike (scripts/exam_spike_keep_together.py) so the
+composer's gate and the spike share ONE implementation (DRY)."""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from dataclasses import dataclass
+
+from ..rendering.block_splits import Block, detect_block_splits
+
+from ..form_fill.fit.wordbox import extract_glyph_boxes
+
+DEFAULT_QUESTION_MARKER = re.compile(r"^\s*(\d+)\s*\.")
+
+
+def column_x_bounds(glyphs) -> list[tuple[float, float]]:
+    """Derive two column x-ranges by splitting the body x-extent at mid-gutter.
+
+    Cluster glyph x-centers into a left group and a right group at the page
+    mid-line; the bounds are each group's [min x0, max x1].
+    """
+    if not glyphs:
+        return []
+    xs0 = min(g.x0 for g in glyphs)
+    xs1 = max(g.x1 for g in glyphs)
+    mid = (xs0 + xs1) / 2.0
+    left = [g for g in glyphs if (g.x0 + g.x1) / 2.0 < mid]
+    right = [g for g in glyphs if (g.x0 + g.x1) / 2.0 >= mid]
+    bounds: list[tuple[float, float]] = []
+    if left:
+        bounds.append((min(g.x0 for g in left), max(g.x1 for g in left)))
+    if right:
+        bounds.append((min(g.x0 for g in right), max(g.x1 for g in right)))
+    return bounds
+
+
+def group_question_blocks(
+    glyphs,
+    *,
+    marker_re: re.Pattern = DEFAULT_QUESTION_MARKER,
+    valid_ids: set[str] | None = None,
+) -> list[Block]:
+    """Group glyphs into one Block per question, sliced on *marker_re*.
+
+    A question owns every glyph from its marker's (page, line position) up to
+    the next question's marker, in reading order.  The block id is
+    ``m.group(1)`` — the captured group from *marker_re*.
+
+    Reading order is (page, column [left before right by page mid], y, x).
+
+    *valid_ids*, when given, restricts which marker matches count as a question
+    start: a line is treated as a marker only if its captured id is in the set.
+    This scopes grouping to the questions actually composed, so stray numeric-
+    dot text in the form's preserved chrome (e.g. a "2026." year) never opens a
+    spurious block.
+    """
+    if not glyphs:
+        return []
+
+    def line_key(g):
+        return (g.page, g.block, g.line)
+
+    lines: dict[tuple, list] = defaultdict(list)
+    for g in glyphs:
+        lines[line_key(g)].append(g)
+
+    records = []
+    for gl in lines.values():
+        gl_sorted = sorted(gl, key=lambda g: g.x0)
+        text = "".join(g.text for g in gl_sorted)
+        cx = sum((g.x0 + g.x1) / 2.0 for g in gl_sorted) / len(gl_sorted)
+        cy = sum((g.y0 + g.y1) / 2.0 for g in gl_sorted) / len(gl_sorted)
+        records.append(
+            {
+                "page": gl_sorted[0].page,
+                "cx": cx,
+                "cy": cy,
+                "text": text,
+                "glyphs": gl_sorted,
+            }
+        )
+
+    by_page: dict[int, list] = defaultdict(list)
+    for rec in records:
+        by_page[rec["page"]].append(rec)
+    ordered: list[dict] = []
+    for page in sorted(by_page):
+        recs = by_page[page]
+        xs0 = min(r["cx"] for r in recs)
+        xs1 = max(r["cx"] for r in recs)
+        mid = (xs0 + xs1) / 2.0
+        recs.sort(key=lambda r: (0 if r["cx"] < mid else 1, r["cy"], r["cx"]))
+        ordered.extend(recs)
+
+    blocks: list[Block] = []
+    cur_id: str | None = None
+    cur_glyphs: list = []
+    for rec in ordered:
+        m = marker_re.search(rec["text"]) or marker_re.search(
+            rec["text"].replace(" ", "")
+        )
+        if m is not None and valid_ids is not None and m.group(1) not in valid_ids:
+            m = None  # numeric-dot text that is not a composed 문항 (chrome) — not a marker
+        if m is not None:
+            if cur_id is not None:
+                blocks.append(Block(id=cur_id, glyphs=cur_glyphs))
+            cur_id = m.group(1)
+            cur_glyphs = list(rec["glyphs"])
+        elif cur_id is not None:
+            cur_glyphs.extend(rec["glyphs"])
+    if cur_id is not None:
+        blocks.append(Block(id=cur_id, glyphs=cur_glyphs))
+    return blocks
+
+
+@dataclass(frozen=True, slots=True)
+class SplitReport:
+    """Summary of 문항 split detection for one rendered PDF."""
+
+    n_splits: int
+    n_blocks: int
+    n_glyphs: int
+    kinds: dict[str, int]
+    split_ids: tuple[str, ...]
+
+
+def measure_question_splits(
+    pdf_path: str,
+    *,
+    marker_re: re.Pattern = DEFAULT_QUESTION_MARKER,
+    valid_ids: set[str] | None = None,
+) -> SplitReport:
+    """Extract glyphs from *pdf_path* and report how many blocks are split.
+
+    Args:
+        pdf_path: Path to a rendered PDF.
+        marker_re: Compiled regex whose group(1) identifies the question number.
+            Defaults to :data:`DEFAULT_QUESTION_MARKER`.
+        valid_ids: When given, only marker matches whose id is in this set open a
+            block (scopes grouping to the composed 문항; ignores chrome numbers).
+            ``n_blocks == 0`` then means none of the composed 문항 were found in
+            the extractable text layer — the caller treats that as *unverifiable*
+            (e.g. a form whose body Hancom exports as vector curves), never a
+            silent "0 splits".
+
+    Returns:
+        A :class:`SplitReport` summarising split counts, block counts, and kinds.
+    """
+    glyphs = extract_glyph_boxes(pdf_path)
+    blocks = group_question_blocks(glyphs, marker_re=marker_re, valid_ids=valid_ids)
+    page_height = max((g.y1 for g in glyphs), default=0.0)
+    bounds = column_x_bounds(glyphs)
+    splits = detect_block_splits(blocks, bounds, page_height)
+    kinds: dict[str, int] = {}
+    for s in splits:
+        kinds[s.kind] = kinds.get(s.kind, 0) + 1
+    return SplitReport(
+        len(splits), len(blocks), len(glyphs), kinds, tuple(s.block_id for s in splits)
+    )

hwpx_automation/office/exam/parser.py

@@ -0,0 +1,150 @@
+"""Parse the recommended exam-md convention into the Exam IR.
+
+The skill authors this md, so the grammar is strict and any unattributable
+line fails loud (Constitution VI/IX — no silently wrong layout)."""
+
+from __future__ import annotations
+
+import re
+
+from hwpx.tools.table_cleanup import normalize_cell_text
+
+from .ir import ExamDoc, Placeholder, Question, QuestionSet
+
+_TITLE_RE = re.compile(r"^#\s+(?P<t>.*\S)\s*$")
+_Q_RE = re.compile(r"^##\s+(?P<n>\d+)\.\s*(?:\((?P<p>\d+)\s*점\))?\s*$")
+_SET_RE = re.compile(r"^##\s+(?P<a>\d+)\s*[~∼-]\s*(?P<b>\d+)\.\s*세트\s*$")
+_MEMBER_RE = re.compile(r"^###\s+(?P<n>\d+)\.\s*(?:\((?P<p>\d+)\s*점\))?\s*$")
+_CHOICE_RE = re.compile(r"^\s*(?P<mark>[①②③④⑤⑥⑦⑧⑨⑩])\s*(?P<t>.*)$")
+_PLACEHOLDER_RE = re.compile(r"\[(?P<k>그림|표|식)\s*(?P<n>\d+)\]")
+
+_KIND = {"그림": "img", "표": "table", "식": "equation"}
+
+
+class ExamParseError(ValueError):
+    def __init__(self, line_no: int, text: str, reason: str) -> None:
+        super().__init__(f"line {line_no}: {reason}: {text!r}")
+        self.line_no = line_no
+        self.text = text
+        self.reason = reason
+
+
+class _QBuf:
+    """Accumulates one 문항 across lines, then freezes to a Question."""
+
+    def __init__(self, number: str, points: str | None) -> None:
+        self.number = number
+        self.points = points
+        self.stem_lines: list[str] = []
+        self.choices: list[str] = []
+        self.placeholders: list[Placeholder] = []
+
+    def add_text(self, text: str) -> None:
+        for m in _PLACEHOLDER_RE.finditer(text):
+            pid = f"{m.group('k')}{m.group('n')}"
+            self.placeholders.append(
+                Placeholder(id=pid, kind=_KIND[m.group("k")], raw_text=m.group(0))
+            )
+        self.stem_lines.append(text)
+
+    def add_choice(self, mark: str, text: str) -> None:
+        self.choices.append(f"{mark} {text}".rstrip())
+
+    def freeze(self) -> Question:
+        return Question(
+            number=self.number,
+            stem=normalize_cell_text(" ".join(self.stem_lines)),
+            choices=tuple(self.choices),
+            points=self.points,
+            placeholders=tuple(self.placeholders),
+        )
+
+
+def parse_exam_markdown(md: str, *, title: str = "") -> ExamDoc:
+    blocks: list[Question | QuestionSet] = []
+    cur_q: _QBuf | None = None
+    set_open = False
+    set_rng = ""
+    set_passage: list[str] = []
+    set_members: list[Question] = []
+
+    def flush_q() -> None:
+        nonlocal cur_q
+        if cur_q is None:
+            return
+        q = cur_q.freeze()
+        if set_open:
+            set_members.append(q)
+        else:
+            blocks.append(q)
+        cur_q = None
+
+    def flush_set() -> None:
+        nonlocal set_open, set_rng, set_passage, set_members
+        if not set_open:
+            return
+        blocks.append(
+            QuestionSet(
+                passage=normalize_cell_text(" ".join(set_passage)),
+                rng=set_rng,
+                members=tuple(set_members),
+            )
+        )
+        set_open, set_rng, set_passage, set_members = False, "", [], []
+
+    for i, raw in enumerate(md.splitlines(), start=1):
+        line = raw.rstrip()
+        if not line.strip():
+            continue
+
+        m_set = _SET_RE.match(line)
+        if m_set:
+            flush_q()
+            flush_set()
+            set_open = True
+            set_rng = f"{m_set.group('a')}∼{m_set.group('b')}"
+            continue
+
+        m_member = _MEMBER_RE.match(line)
+        if m_member:
+            if not set_open:
+                raise ExamParseError(i, line, "'### N.' member outside a 세트 header")
+            flush_q()
+            cur_q = _QBuf(m_member.group("n"), m_member.group("p"))
+            continue
+
+        m_q = _Q_RE.match(line)
+        if m_q:
+            flush_q()
+            flush_set()
+            cur_q = _QBuf(m_q.group("n"), m_q.group("p"))
+            continue
+
+        m_title = _TITLE_RE.match(line)
+        if m_title and not blocks and cur_q is None and not set_open:
+            title = title or normalize_cell_text(m_title.group("t"))
+            continue
+
+        m_choice = _CHOICE_RE.match(line)
+        if m_choice:
+            # A 답항(choice) cannot exist without an active 문항. Even inside an
+            # open 세트, a choice before the first member must fail loud rather
+            # than be silently swallowed into the set passage.
+            if cur_q is None:
+                raise ExamParseError(i, line, "답항(choice) outside any 문항")
+            cur_q.add_choice(
+                m_choice.group("mark"), normalize_cell_text(m_choice.group("t"))
+            )
+            continue
+
+        # plain content line: belongs to the current 문항 stem, or the set passage
+        if cur_q is not None:
+            cur_q.add_text(line.strip())
+        elif set_open:
+            set_passage.append(line.strip())
+        else:
+            raise ExamParseError(i, line, "content before any 문항 / 세트 header")
+
+    flush_q()
+    flush_set()
+    return ExamDoc(title=title, blocks=tuple(blocks))