quantized-lab 0.8.0__py3-none-any.whl

quantized/io/registry.py

@@ -0,0 +1,210 @@
+"""Single parser registry: extension map + content sniffers for ambiguous types.
+
+One place to register a parser (no MATLAB-style dual registration). Ambiguous
+extensions (``.dat``) resolve by sniffing file content.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from quantized.datastruct import DataStruct
+from quantized.io.bruker_brml import import_bruker_brml
+from quantized.io.bruker_raw import import_bruker_raw, is_bruker_raw
+from quantized.io.delimited import import_csv
+from quantized.io.excel import import_excel
+from quantized.io.import_filters import match_filter
+from quantized.io.import_preview import parse_import
+from quantized.io.jcamp import import_jcamp
+from quantized.io.lakeshore import import_lake_shore, is_lakeshore_file
+from quantized.io.ncnr import import_ncnr_dat, import_ncnr_pnr, import_ncnr_refl, is_ncnr_refl
+from quantized.io.netcdf import import_netcdf
+from quantized.io.opus import import_opus
+from quantized.io.origin_project import read_origin_project
+from quantized.io.qd import import_ppms, import_qd_vsm, is_ppms_dat, is_qd_file
+from quantized.io.refl1d import import_refl1d_dat, is_refl1d_dat
+from quantized.io.rigaku import import_rigaku_raw, is_rigaku_raw
+from quantized.io.sims import import_sims, is_sims_file
+from quantized.io.spc import import_spc
+from quantized.io.xrdml import import_xrdml
+
+__all__ = [
+    "import_auto",
+    "register_parser",
+    "resolve_parser",
+    "unregister_plugin_parsers",
+]
+
+Parser = Callable[[Path], DataStruct]
+Sniffer = Callable[[Path], bool]
+
+# Unambiguous extensions map directly (grows as parsers land).
+# NOTE: resolve_parser lowercases the suffix, so .datA -> '.data', etc.
+_EXT_MAP: dict[str, Parser] = {
+    ".xrdml": import_xrdml,
+    ".brml": import_bruker_brml,  # Bruker XRD (ZIP of XML); 1-D line scans
+    ".jdx": import_jcamp,  # JCAMP-DX spectroscopy (IR/Raman/UV-Vis/...)
+    ".dx": import_jcamp,
+    ".nc": import_netcdf,  # NetCDF-3/4 (generic + ANDI/AIA chromatography)
+    ".cdf": import_netcdf,  # ANDI/AIA chromatography (NetCDF-3 classic)
+    ".pnr": import_ncnr_pnr,
+    # Origin project files — clean-room reader (no GPL liborigin). Currently
+    # recognizes + guides; the binary decoders land against sample files.
+    ".opj": read_origin_project,  # Origin ≤2017 binary project
+    ".opju": read_origin_project,  # Origin 2018+ Unicode project
+    ".data": import_ncnr_dat,  # .datA
+    ".datb": import_ncnr_dat,  # .datB
+    ".datc": import_ncnr_dat,  # .datC
+    ".datd": import_ncnr_dat,  # .datD
+    # importSPC.m / importOxford.m / importOpus.m were never written in
+    # quantized_matlab (PORT_CHECKLIST.md line 46 — "paused, awaiting example
+    # files"); .spc and .opus below are independent implementations against
+    # the published formats, not MATLAB ports (see each module's docstring).
+    # importOxford stays unported: "format varies by software version" with
+    # no spec and no example file — nothing to implement against honestly.
+    ".spc": import_spc,  # GRAMS/Thermo spectral binary
+    ".opus": import_opus,  # Bruker OPUS FTIR/NIR/Raman binary
+}
+
+
+def _accept_any(_path: Path) -> bool:
+    """Catch-all sniffer: routes to the generic fallback parser for an extension."""
+    return True
+
+
+# Ambiguous extensions resolve by content sniffing — first match wins.
+_SNIFFERS: dict[str, list[tuple[Sniffer, Parser]]] = {
+    ".dat": [
+        (is_qd_file, import_qd_vsm),
+        (is_refl1d_dat, import_refl1d_dat),
+        (is_ppms_dat, import_ppms),
+        (is_lakeshore_file, import_lake_shore),
+    ],
+    # .refl is reductus (JSON "columns" header) for the whole corpus, but refl1d
+    # also exports .refl (a "Q (1/A) R dR" column header below # metadata): route
+    # those to the refl1d parser. Catch-all stays reductus (the prior behaviour).
+    ".refl": [
+        (is_ncnr_refl, import_ncnr_refl),
+        (is_refl1d_dat, import_refl1d_dat),
+        (_accept_any, import_ncnr_refl),
+    ],
+    # .raw is either Rigaku SmartLab (magic "FI") or Bruker Diffrac-AT RAW1.01
+    # (magic "RAW1.01"); the magic bytes disambiguate with no collision.
+    ".raw": [(is_rigaku_raw, import_rigaku_raw), (is_bruker_raw, import_bruker_raw)],
+    # SIMS depth profiles share .csv/.tsv/.xlsx with generic tables: sniff for the
+    # SIMS layout first, else fall back to the generic delimited / Excel parser.
+    # Lake Shore VSM self-identifies in its preamble (MAIN_PLAN #7 — the
+    # parser existed unregistered; the #52 matrix surfaced it). SIMS keeps
+    # precedence (established chain order).
+    ".csv": [
+        (is_sims_file, import_sims),
+        (is_lakeshore_file, import_lake_shore),
+        (_accept_any, import_csv),
+    ],
+    ".tsv": [(is_sims_file, import_sims), (_accept_any, import_csv)],
+    ".xlsx": [(is_sims_file, import_sims), (_accept_any, import_excel)],
+    ".xlsm": [(is_sims_file, import_sims), (_accept_any, import_excel)],
+}
+
+
+def _import_via_saved_filter(path: Path) -> DataStruct:
+    """Parse ``path`` under its best-matching saved import filter.
+
+    See :mod:`quantized.io.import_filters` (gap #40): a user-saved
+    ``ImportSettings`` bound to a filename glob, consulted by
+    :func:`resolve_parser` before the content sniffers below.
+    """
+    filt = match_filter(path)
+    if filt is None:  # pragma: no cover - resolve_parser only routes here on a match
+        raise ValueError(f"no saved import filter matches '{path.name}'")
+    return parse_import(path.read_text(encoding="latin-1"), filt.settings)
+
+
+# ── Plugin registration (single-registration path; gap #8) ──────────────────
+# Third-party plugins (see quantized.plugins) contribute parsers THROUGH this one
+# function — the same ``_EXT_MAP`` / ``_SNIFFERS`` chokepoint the built-ins use
+# above — so there is never a second dispatch path. Plugin registrations are
+# tracked separately so an idempotent reload / test isolation can remove them
+# WITHOUT ever touching a built-in entry.
+_PLUGIN_EXTS: set[str] = set()
+_PLUGIN_SNIFFERS: dict[str, list[tuple[Sniffer, Parser]]] = {}
+
+
+def _normalize_ext(ext: str) -> str:
+    lowered = ext.lower()
+    return lowered if lowered.startswith(".") else f".{lowered}"
+
+
+def register_parser(
+    extensions: list[str], parser: Parser, *, sniff: Sniffer | None = None
+) -> None:
+    """Register a plugin ``parser`` for one or more file ``extensions``.
+
+    Precedence discipline (identical to saved import filters): a plugin may claim
+    a NOVEL extension, but must never SHADOW a built-in one.
+
+    - ``sniff is None`` (unambiguous claim): the extension maps straight to
+      ``parser``. Refused with ``ValueError`` when the extension is already known
+      — a built-in ``_EXT_MAP`` entry *or* an ambiguous ``_SNIFFERS`` extension.
+      This is the "a plugin cannot shadow ``.jdx``" rule.
+    - ``sniff`` given (content sniff): ``(sniff, parser)`` is APPENDED to the
+      extension's sniffer chain, so built-in sniffers keep precedence and a
+      plugin sniffer can only ever act as a fallback.
+    """
+    for raw in extensions:
+        ext = _normalize_ext(raw)
+        if sniff is None:
+            if ext in _EXT_MAP or ext in _SNIFFERS:
+                raise ValueError(
+                    f"extension '{ext}' is already claimed by a built-in parser "
+                    "(plugins may not shadow built-in extensions)"
+                )
+            _EXT_MAP[ext] = parser
+            _PLUGIN_EXTS.add(ext)
+        else:
+            _SNIFFERS.setdefault(ext, []).append((sniff, parser))
+            _PLUGIN_SNIFFERS.setdefault(ext, []).append((sniff, parser))
+
+
+def unregister_plugin_parsers() -> None:
+    """Remove every plugin-registered parser, restoring the built-in registry.
+
+    Used by :func:`quantized.plugins.load_plugins` for an idempotent reload and
+    by tests for isolation; built-in ``_EXT_MAP`` / ``_SNIFFERS`` entries are
+    never touched.
+    """
+    for ext in _PLUGIN_EXTS:
+        _EXT_MAP.pop(ext, None)
+    _PLUGIN_EXTS.clear()
+    for ext, entries in _PLUGIN_SNIFFERS.items():
+        chain = _SNIFFERS.get(ext)
+        if chain is None:
+            continue
+        for entry in entries:
+            if entry in chain:
+                chain.remove(entry)
+        if not chain:
+            _SNIFFERS.pop(ext, None)
+    _PLUGIN_SNIFFERS.clear()
+
+
+def resolve_parser(path: Path) -> Parser:
+    """Pick the parser for ``path``: unambiguous extension, else a saved
+    import filter (gap #40 — a user-named glob -> ``ImportSettings``), else
+    content sniffing."""
+    ext = path.suffix.lower()
+    if ext in _EXT_MAP:
+        return _EXT_MAP[ext]
+    if match_filter(path) is not None:
+        return _import_via_saved_filter
+    for sniff, parser in _SNIFFERS.get(ext, []):
+        if sniff(path):
+            return parser
+    raise ValueError(f"no parser registered for '{path.name}' (extension '{ext}')")
+
+
+def import_auto(path: str | Path) -> DataStruct:
+    """Auto-detect format and import ``path`` into a DataStruct."""
+    resolved = Path(path)
+    return resolve_parser(resolved)(resolved)

quantized/io/report_export.py

@@ -0,0 +1,347 @@
+"""Render a :class:`~quantized.calc.report.ReportSheet` to office / markup files.
+
+ORIGIN_GAP_PLAN #37 (docx/pptx) + #38 (LaTeX) + #39 (HTML). Every renderer
+walks the SAME report schema (title -> sections -> typed blocks) with no
+per-block special cases beyond the four block kinds — that is the #36
+acceptance criterion made real.
+
+LaTeX and HTML are pure-Python and always available. Word (.docx) and
+PowerPoint (.pptx) need the MIT libraries ``python-docx`` / ``python-pptx``;
+those imports are guarded so the module (and CI) work without them — a missing
+library raises a clear ``ReportExportError`` instead of an ImportError at
+module load.
+
+Pure ``io`` layer — no fastapi/pydantic imports (enforced by
+test_repo_integrity). ``value ± error`` formatting rounds the value to the
+precision implied by the uncertainty (2 significant figures on the error).
+"""
+
+from __future__ import annotations
+
+import base64 as _base64
+import binascii as _binascii
+import html as _html
+import io as _io
+import math
+from collections.abc import Mapping
+from typing import Any
+
+# Raster image MIME types Office can embed (SVG/other -> placeholder text).
+_EMBEDDABLE_IMAGE_MIMES = ("image/png", "image/jpeg", "image/jpg", "image/gif", "image/bmp")
+
+
+def _decode_raster(image: Mapping[str, str] | None) -> bytes | None:
+    """Return decoded image bytes iff it's an Office-embeddable raster type."""
+    if not image or image.get("mime") not in _EMBEDDABLE_IMAGE_MIMES:
+        return None
+    try:
+        return _base64.b64decode(image["data"], validate=True)
+    except (_binascii.Error, ValueError, KeyError):
+        return None
+
+__all__ = [
+    "FORMATS",
+    "ReportExportError",
+    "format_value_error",
+    "render_report",
+    "to_html",
+    "to_latex",
+]
+
+FORMATS = ("latex", "html", "docx", "pptx")
+
+
+class ReportExportError(RuntimeError):
+    """Raised for an unknown format or a missing optional export library."""
+
+
+# ── number formatting ─────────────────────────────────────────────────────
+def _fmt_num(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return str(value)
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            return ""
+        return f"{value:.6g}"
+    return str(value)
+
+
+def format_value_error(value: Any, error: Any = None, *, sig: int = 2) -> str:
+    """Format ``value ± error`` with the value rounded to the error's precision.
+
+    With no (finite, non-zero) error, falls back to a plain 6-significant-figure
+    number. ``sig`` is the number of significant figures kept on the error.
+    """
+    if value is None:
+        return ""
+    v = float(value)
+    if error is None or not math.isfinite(float(error)) or float(error) == 0.0:
+        return _fmt_num(value)
+    e = abs(float(error))  # uncertainty is magnitude-only, sign is meaningless
+    exp = math.floor(math.log10(e))
+    ndp = sig - 1 - exp  # decimal places (may be negative for large errors)
+    v_r, e_r = round(v, ndp), round(e, ndp)
+    dp = max(0, ndp)
+    return f"{v_r:.{dp}f} ± {e_r:.{dp}f}"
+
+
+# ── block-walking helpers (shared by every renderer) ──────────────────────
+def _params_rows(block: Mapping[str, Any]) -> tuple[list[str], list[list[str]]]:
+    """(header, rows) for a params block, with value ± error merged."""
+    has_unit = any(p.get("unit") for p in block["params"])
+    header = ["Parameter", "Value", *(["Unit"] if has_unit else [])]
+    rows = []
+    for p in block["params"]:
+        cells = [str(p["name"]), format_value_error(p.get("value"), p.get("error"))]
+        if has_unit:
+            cells.append(str(p.get("unit", "")))
+        rows.append(cells)
+    return header, rows
+
+
+def _table_rows(block: Mapping[str, Any]) -> tuple[list[str], list[list[str]]]:
+    header = [str(c) for c in block["columns"]]
+    rows = [[_fmt_num(c) for c in row] for row in block["rows"]]
+    return header, rows
+
+
+# ── LaTeX (booktabs) ──────────────────────────────────────────────────────
+# LaTeX special chars + the science glyphs the emitters emit (so the output
+# compiles under plain pdfLaTeX, no inputenc/unicode-engine required).
+_LATEX_REPL = {
+    "&": r"\&", "%": r"\%", "$": r"\$", "#": r"\#", "_": r"\_",
+    "{": r"\{", "}": r"\}", "~": r"\textasciitilde{}", "^": r"\textasciicircum{}",
+    "±": r"$\pm$", "×": r"$\times$", "·": r"$\cdot$", "²": r"$^2$", "³": r"$^3$",
+    "χ": r"$\chi$", "η": r"$\eta$", "α": r"$\alpha$", "β": r"$\beta$",
+    "γ": r"$\gamma$", "σ": r"$\sigma$", "λ": r"$\lambda$", "θ": r"$\theta$",
+    "ω": r"$\omega$", "μ": r"$\mu$", "π": r"$\pi$", "τ": r"$\tau$",
+    "Δ": r"$\Delta$", "Ω": r"$\Omega$", "Å": r"\AA{}", "°": r"$^\circ$",
+    "√": r"$\surd$", "∞": r"$\infty$",
+}
+
+
+def _latex_escape(text: str) -> str:
+    return "".join(_LATEX_REPL.get(ch, ch) for ch in text)
+
+
+def _latex_table(header: list[str], rows: list[list[str]], caption: str | None) -> list[str]:
+    ncol = len(header)
+    align = "l" + "r" * (ncol - 1) if ncol > 1 else "l"
+    out = [r"\begin{table}[h]", r"  \centering"]
+    if caption:
+        out.append(rf"  \caption{{{_latex_escape(caption)}}}")
+    out.append(rf"  \begin{{tabular}}{{{align}}}")
+    out.append(r"    \toprule")
+    out.append("    " + " & ".join(_latex_escape(h) for h in header) + r" \\")
+    out.append(r"    \midrule")
+    for row in rows:
+        out.append("    " + " & ".join(_latex_escape(str(c)) for c in row) + r" \\")
+    out.append(r"    \bottomrule")
+    out.append(r"  \end{tabular}")
+    out.append(r"\end{table}")
+    return out
+
+
+def to_latex(report: Mapping[str, Any]) -> str:
+    """Booktabs LaTeX for the report's tables (params + stats), text as prose."""
+    lines = [rf"% Report: {_latex_escape(str(report.get('title', '')))}",
+             r"% Requires \usepackage{booktabs}", ""]
+    for sec in report.get("sections", []):
+        lines.append(rf"\subsection*{{{_latex_escape(str(sec.get('title', '')))}}}")
+        for block in sec.get("blocks", []):
+            btype = block.get("type")
+            if btype == "text":
+                lines.append(_latex_escape(block["text"]) + "\n")
+            elif btype == "params":
+                header, rows = _params_rows(block)
+                lines += _latex_table(header, rows, block.get("caption"))
+            elif btype == "table":
+                header, rows = _table_rows(block)
+                lines += _latex_table(header, rows, block.get("caption"))
+            elif btype == "figure":
+                lines.append(rf"% [figure: {_latex_escape(str(block.get('name', '')))}]")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+# ── HTML (self-contained) ─────────────────────────────────────────────────
+_HTML_CSS = (
+    "body{font-family:system-ui,sans-serif;max-width:52rem;margin:2rem auto;"
+    "padding:0 1rem;color:#1a1a1a}h1{font-size:1.5rem}h2{font-size:1.15rem;"
+    "border-bottom:1px solid #ddd;padding-bottom:.2rem}table{border-collapse:"
+    "collapse;margin:.6rem 0}th,td{border:1px solid #ccc;padding:.25rem .6rem;"
+    "text-align:right}th:first-child,td:first-child{text-align:left}"
+    "caption{caption-side:top;font-style:italic;text-align:left;color:#555}"
+    "figure{color:#777;font-style:italic}"
+)
+
+
+def _html_table(header: list[str], rows: list[list[str]], caption: str | None) -> str:
+    parts = ["<table>"]
+    if caption:
+        parts.append(f"<caption>{_html.escape(caption)}</caption>")
+    parts.append("<thead><tr>" + "".join(f"<th>{_html.escape(h)}</th>" for h in header)
+                 + "</tr></thead><tbody>")
+    for row in rows:
+        parts.append("<tr>" + "".join(f"<td>{_html.escape(str(c))}</td>" for c in row) + "</tr>")
+    parts.append("</tbody></table>")
+    return "".join(parts)
+
+
+def to_html(report: Mapping[str, Any]) -> str:
+    """A self-contained HTML page for the report (#39)."""
+    title = _html.escape(str(report.get("title", "Report")))
+    body = [f"<h1>{title}</h1>"]
+    refs = report.get("source_refs", [])
+    if refs:
+        names = ", ".join(_html.escape(str(r.get("name") or r.get("id"))) for r in refs)
+        body.append(f"<p><small>Sources: {names}</small></p>")
+    for sec in report.get("sections", []):
+        body.append(f"<h2>{_html.escape(str(sec.get('title', '')))}</h2>")
+        for block in sec.get("blocks", []):
+            btype = block.get("type")
+            if btype == "text":
+                body.append(f"<p>{_html.escape(block['text'])}</p>")
+            elif btype == "params":
+                header, rows = _params_rows(block)
+                body.append(_html_table(header, rows, block.get("caption")))
+            elif btype == "table":
+                header, rows = _table_rows(block)
+                body.append(_html_table(header, rows, block.get("caption")))
+            elif btype == "figure":
+                cap = block.get("caption") or block.get("name", "")
+                img = block.get("image")
+                if img:
+                    src = f"data:{img['mime']};base64,{img['data']}"
+                    body.append(f'<figure><img src="{src}" alt="{_html.escape(str(cap))}"'
+                                f' style="max-width:100%"><figcaption>'
+                                f"{_html.escape(str(cap))}</figcaption></figure>")
+                else:
+                    body.append(f"<figure>[figure: {_html.escape(str(cap))}]</figure>")
+    return (f"<!doctype html><html><head><meta charset='utf-8'><title>{title}</title>"
+            f"<style>{_HTML_CSS}</style></head><body>{''.join(body)}</body></html>")
+
+
+# ── Word / PowerPoint (guarded optional deps) ─────────────────────────────
+def _to_docx(report: Mapping[str, Any]) -> bytes:
+    try:
+        from docx import Document  # python-docx (MIT)
+    except ImportError as exc:  # pragma: no cover - exercised only without the dep
+        raise ReportExportError(
+            "Word export needs 'python-docx' (pip install quantized[office])"
+        ) from exc
+
+    doc = Document()
+    doc.add_heading(str(report.get("title", "Report")), level=0)
+    for sec in report.get("sections", []):
+        doc.add_heading(str(sec.get("title", "")), level=1)
+        for block in sec.get("blocks", []):
+            btype = block.get("type")
+            if btype == "text":
+                doc.add_paragraph(block["text"])
+            elif btype in ("params", "table"):
+                header, rows = (_params_rows if btype == "params" else _table_rows)(block)
+                cap = block.get("caption")
+                if cap:
+                    doc.add_paragraph().add_run(str(cap)).italic = True
+                t = doc.add_table(rows=1, cols=len(header))
+                t.style = "Light Grid Accent 1"
+                for j, h in enumerate(header):
+                    t.rows[0].cells[j].text = h
+                for row in rows:
+                    cells = t.add_row().cells
+                    for j, c in enumerate(row):
+                        cells[j].text = str(c)
+            elif btype == "figure":
+                raster = _decode_raster(block.get("image"))
+                if raster is not None:
+                    from docx.shared import Inches
+                    doc.add_picture(_io.BytesIO(raster), width=Inches(6))
+                    if block.get("caption"):
+                        doc.add_paragraph().add_run(str(block["caption"])).italic = True
+                else:
+                    doc.add_paragraph(f"[figure: {block.get('name', '')}]")
+    buf = _io.BytesIO()
+    doc.save(buf)
+    return buf.getvalue()
+
+
+def _to_pptx(report: Mapping[str, Any]) -> bytes:
+    try:
+        from pptx import Presentation  # python-pptx (MIT)
+        from pptx.util import Inches, Pt
+    except ImportError as exc:  # pragma: no cover - exercised only without the dep
+        raise ReportExportError(
+            "PowerPoint export needs 'python-pptx' (pip install quantized[office])"
+        ) from exc
+
+    prs = Presentation()
+    blank = prs.slide_layouts[6]
+    title_layout = prs.slide_layouts[5]
+    first = prs.slides.add_slide(title_layout)
+    first.shapes.title.text = str(report.get("title", "Report"))
+    for sec in report.get("sections", []):
+        slide = prs.slides.add_slide(blank)
+        box = slide.shapes.add_textbox(Inches(0.5), Inches(0.3), Inches(9), Inches(0.8))
+        box.text_frame.text = str(sec.get("title", ""))
+        box.text_frame.paragraphs[0].font.size = Pt(28)
+        top = 1.3
+        for block in sec.get("blocks", []):
+            btype = block.get("type")
+            if btype == "text":
+                tb = slide.shapes.add_textbox(Inches(0.5), Inches(top), Inches(9), Inches(0.6))
+                tb.text_frame.text = block["text"]
+                tb.text_frame.word_wrap = True
+                top += 0.7
+            elif btype in ("params", "table"):
+                header, rows = (_params_rows if btype == "params" else _table_rows)(block)
+                nrows, ncols = len(rows) + 1, len(header)
+                height = min(0.35 * nrows, 5.0)
+                gt = slide.shapes.add_table(
+                    nrows, ncols, Inches(0.5), Inches(top), Inches(9), Inches(height)
+                ).table
+                for j, h in enumerate(header):
+                    gt.cell(0, j).text = h
+                for i, row in enumerate(rows, start=1):
+                    for j, c in enumerate(row):
+                        gt.cell(i, j).text = str(c)
+                top += height + 0.3
+            elif btype == "figure":
+                raster = _decode_raster(block.get("image"))
+                if raster is not None:
+                    slide.shapes.add_picture(
+                        _io.BytesIO(raster), Inches(0.5), Inches(top), width=Inches(6)
+                    )
+                    top += 4.0
+                else:
+                    tb = slide.shapes.add_textbox(Inches(0.5), Inches(top), Inches(9), Inches(0.5))
+                    tb.text_frame.text = f"[figure: {block.get('name', '')}]"
+                    top += 0.6
+    buf = _io.BytesIO()
+    prs.save(buf)
+    return buf.getvalue()
+
+
+# ── dispatch ──────────────────────────────────────────────────────────────
+def render_report(report: Mapping[str, Any], fmt: str) -> tuple[bytes, str, bool]:
+    """Render ``report`` to ``fmt``; return ``(data, mime, is_text)``.
+
+    ``is_text`` is True for latex/html (utf-8 text), False for docx/pptx
+    (binary — the route base64-encodes these). Unknown or unavailable formats
+    raise :class:`ReportExportError`.
+    """
+    if fmt == "latex":
+        return to_latex(report).encode("utf-8"), "text/x-tex", True
+    if fmt == "html":
+        return to_html(report).encode("utf-8"), "text/html", True
+    if fmt == "docx":
+        return (_to_docx(report),
+                "application/vnd.openxmlformats-officedocument.wordprocessingml.document", False)
+    if fmt == "pptx":
+        return (_to_pptx(report),
+                "application/vnd.openxmlformats-officedocument.presentationml.presentation", False)
+    raise ReportExportError(f"unknown report format {fmt!r}; expected one of {FORMATS}")

quantized/io/rigaku.py

@@ -0,0 +1,100 @@
+"""Rigaku SmartLab ``.raw`` binary parser. Port of MATLAB parser.importRigaku_raw.
+
+Binary layout (magic "FI", little-endian, 1-indexed offsets in the MATLAB
+source shown here 0-indexed):
+    0..1       magic "FI"
+    2958..2961 counting time per step (float32, s)
+    2962..2965 start 2theta (float32, deg)
+    2966..2969 end 2theta   (float32, deg)
+    2970..2973 step size     (float32, deg)
+    3154..3157 number of points (uint32)
+    3158..      intensity data (float32, 4 bytes/point)
+"""
+
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["import_rigaku_raw", "is_rigaku_raw"]
+
+_HEADER_SIZE = 3158
+_MIN_FILE_SIZE = 3162  # header + at least one float32
+
+
+def is_rigaku_raw(path: Path) -> bool:
+    """Sniff a ``.raw`` as Rigaku SmartLab via the 'FI' magic bytes."""
+    with Path(path).open("rb") as fh:
+        return fh.read(2) == b"FI"
+
+
+def import_rigaku_raw(
+    filepath: str | Path,
+    *,
+    use_counts_per_sec: bool = False,
+    allow_partial: bool = False,
+) -> DataStruct:
+    """Import a Rigaku SmartLab ``.raw`` (2theta vs intensity)."""
+    path = Path(filepath)
+    raw = path.read_bytes()
+    n_bytes = len(raw)
+    if n_bytes < _MIN_FILE_SIZE:
+        raise ValueError(f"file too small to be a Rigaku .raw ({n_bytes} bytes): {path.name}")
+    if raw[0:2] != b"FI":
+        raise ValueError(f"bad magic {raw[0:2]!r} (expected b'FI'): {path.name}")
+
+    counting_time = float(struct.unpack_from("<f", raw, 2958)[0])
+    start_angle = float(struct.unpack_from("<f", raw, 2962)[0])
+    end_angle = float(struct.unpack_from("<f", raw, 2966)[0])
+    step_size = float(struct.unpack_from("<f", raw, 2970)[0])
+    num_points = int(struct.unpack_from("<I", raw, 3154)[0])
+
+    if step_size == 0:
+        raise ValueError(f"zero step size (variable-step scans unsupported): {path.name}")
+    if step_size < 0 or step_size > 10:
+        raise ValueError(f"implausible step size ({step_size:.6g} deg): {path.name}")
+
+    n_avail = (n_bytes - _HEADER_SIZE) // 4
+    if num_points == 0 or num_points > n_avail:
+        if n_avail == 0:
+            raise ValueError(f"no data bytes after header: {path.name}")
+        num_points = n_avail
+
+    first_range_end = _HEADER_SIZE + num_points * 4
+    if n_bytes > first_range_end + 3 and not allow_partial:
+        raise ValueError(
+            f"multi-range .raw detected ({n_bytes - first_range_end} bytes after first "
+            f"range); pass allow_partial=True to import the first range only: {path.name}"
+        )
+
+    intensities = np.frombuffer(raw, dtype="<f4", count=num_points, offset=_HEADER_SIZE).astype(
+        float
+    )
+    two_theta = start_angle + np.arange(num_points) * step_size
+
+    if use_counts_per_sec and counting_time > 0:
+        values = intensities / counting_time
+        unit = "counts/s"
+    else:
+        values = intensities
+        unit = "counts"
+
+    metadata: dict[str, Any] = {
+        "source": str(path),
+        "parser_name": "import_rigaku_raw",
+        "x_column_name": "2-Theta",
+        "x_column_unit": "deg",
+        "num_points": num_points,
+        "start_angle": start_angle,
+        "end_angle": end_angle,
+        "step_size": step_size,
+        "counting_time": counting_time,
+    }
+    return DataStruct.create(
+        two_theta, values, labels=["Intensity"], units=[unit], metadata=metadata
+    )