mathfmt 0.1.0__py3-none-any.whl

mathfmt/__init__.py

@@ -0,0 +1,6 @@
+"""MathFmt public API."""
+
+from .core import apply_docx, find_xsl, formula_to_mathml, scan_docx
+
+__all__ = ["apply_docx", "find_xsl", "formula_to_mathml", "scan_docx"]
+__version__ = "0.1.0"

mathfmt/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

mathfmt/cli.py

@@ -0,0 +1,136 @@
+"""Command-line interface for MathFmt."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+from lxml import etree
+
+from . import __version__
+from .core import apply_docx, find_xsl, scan_docx
+
+
+def default_output(input_path: Path) -> Path:
+    return input_path.with_name(f"{input_path.stem}.mathfmt.docx")
+
+
+def default_result_report(output_path: Path) -> Path:
+    return output_path.with_name(f"{output_path.stem}.report.json")
+
+
+def doctor_data(explicit_xsl: Path | None = None) -> dict[str, object]:
+    data: dict[str, object] = {
+        "mathfmt": __version__,
+        "python": platform.python_version(),
+        "platform": platform.platform(),
+        "windows": os.name == "nt",
+        "lxml": etree.LXML_VERSION,
+        "xsl": None,
+        "ready": False,
+    }
+    try:
+        data["xsl"] = str(find_xsl(explicit_xsl).resolve())
+        data["ready"] = True
+    except FileNotFoundError as exc:
+        data["error"] = str(exc)
+    return data
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mathfmt",
+        description="Typeset plain-text DOCX formulas as native Word equations.",
+    )
+    parser.add_argument("--version", action="version", version=f"MathFmt {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan = subparsers.add_parser("scan", help="create a reviewable formula candidate report")
+    scan.add_argument("input", type=Path)
+    scan.add_argument("--report", type=Path, required=True)
+
+    apply = subparsers.add_parser("apply", help="apply a reviewed candidate report")
+    apply.add_argument("input", type=Path)
+    apply.add_argument("--review", type=Path, required=True)
+    apply.add_argument("--output", "--out", dest="output", type=Path, required=True)
+    apply.add_argument("--report", type=Path, required=True)
+    apply.add_argument("--xsl", type=Path)
+
+    convert = subparsers.add_parser("convert", help="conservatively convert detected formulas in one step")
+    convert.add_argument("input", type=Path)
+    convert.add_argument("--output", "--out", dest="output", type=Path)
+    convert.add_argument("--report", type=Path)
+    convert.add_argument("--xsl", type=Path)
+
+    doctor = subparsers.add_parser("doctor", help="check the local MathFmt environment")
+    doctor.add_argument("--xsl", type=Path)
+    doctor.add_argument("--json", action="store_true", dest="as_json")
+    return parser
+
+
+def run_convert(args: argparse.Namespace) -> int:
+    output = args.output or default_output(args.input)
+    report_path = args.report or default_result_report(output)
+    xsl = find_xsl(args.xsl)
+    with tempfile.TemporaryDirectory(prefix="mathfmt-") as temp_dir:
+        review_path = Path(temp_dir) / "candidates.json"
+        scan = scan_docx(args.input, review_path)
+        result = apply_docx(args.input, review_path, output, report_path, xsl)
+    print(f"Candidates: {scan['summary']['candidates']}")
+    print(f"Converted: {result['converted_count']}")
+    print(f"Skipped: {result['skipped_count']}")
+    print(f"Output: {output}")
+    print(f"Report: {report_path}")
+    return 0 if result["skipped_count"] == 0 else 2
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "scan":
+            report = scan_docx(args.input, args.report)
+            print(f"Candidates: {report['summary']['candidates']}")
+            print(f"Report: {args.report}")
+            return 0
+        if args.command == "apply":
+            result = apply_docx(
+                args.input,
+                args.review,
+                args.output,
+                args.report,
+                find_xsl(args.xsl),
+            )
+            print(f"Converted: {result['converted_count']}")
+            print(f"Skipped: {result['skipped_count']}")
+            print(f"Output: {args.output}")
+            print(f"Report: {args.report}")
+            return 0 if result["skipped_count"] == 0 else 2
+        if args.command == "convert":
+            return run_convert(args)
+        if args.command == "doctor":
+            data = doctor_data(args.xsl)
+            if args.as_json:
+                print(json.dumps(data, ensure_ascii=False, indent=2))
+            else:
+                print(f"MathFmt: {data['mathfmt']}")
+                print(f"Python: {data['python']}")
+                print(f"Platform: {data['platform']}")
+                print(f"MML2OMML.XSL: {data['xsl'] or 'not found'}")
+                print(f"Ready: {'yes' if data['ready'] else 'no'}")
+                if data.get("error"):
+                    print(f"Hint: {data['error']}")
+            return 0 if data["ready"] else 1
+    except (FileNotFoundError, ValueError, json.JSONDecodeError, etree.XMLSyntaxError) as exc:
+        print(f"mathfmt: error: {exc}", file=sys.stderr)
+        return 1
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mathfmt/core.py

@@ -0,0 +1,779 @@
+#!/usr/bin/env python3
+"""Scan and typeset plain-text DOCX formulas as native Word OMML equations."""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+import shutil
+import zipfile
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from lxml import etree
+
+W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+M_NS = "http://schemas.openxmlformats.org/officeDocument/2006/math"
+MML_NS = "http://www.w3.org/1998/Math/MathML"
+XML_NS = "http://www.w3.org/XML/1998/namespace"
+NS = {"w": W_NS, "m": M_NS}
+
+TARGET_PART_RE = re.compile(r"^word/(document|header\d+|footer\d+)\.xml$")
+
+SUBSCRIPT_MAP = str.maketrans(
+    "₀₁₂₃₄₅₆₇₈₉₊₋₌₍₎ₐₑₕᵢⱼₖₗₘₙₒₚᵣₛₜᵤᵥₓ",
+    "0123456789+-=()aehijklmnop rstuvx".replace(" ", ""),
+)
+SUPERSCRIPT_MAP = {
+    "⁰": "0", "¹": "1", "²": "2", "³": "3", "⁴": "4",
+    "⁵": "5", "⁶": "6", "⁷": "7", "⁸": "8", "⁹": "9",
+    "⁺": "+", "⁻": "-", "⁼": "=", "⁽": "(", "⁾": ")", "ⁿ": "n",
+}
+SUPERSCRIPT_CHARS = "".join(SUPERSCRIPT_MAP)
+
+CODE_START_RE = re.compile(
+    r"^(?:%|#|pkg\s|clear\b|close\b|plot\b|grid\b|xlabel\b|ylabel\b|"
+    r"title\b|legend\b|hold\b|for\b|while\b|if\b|function\b|import\b|from\b)",
+    re.IGNORECASE,
+)
+FORMULA_ANCHOR_RE = re.compile(r"(?:=|≠|<=|>=|!=|→|->|±|\+/-|√|sqrt|lim)")
+MATH_CHARS = set(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+    "₀₁₂₃₄₅₆₇₈₉ₚᵥₜ⁰¹²³⁴⁵⁶⁷⁸⁹+-*/^=<>!~→⇒±≠≤≥≈√∞ΔπΓ"
+    "()[]{}.,'′˙¨·×÷_ \t"
+)
+TRIM_PUNCT = " \t,，.。;；:："
+
+
+def qname(ns: str, local: str) -> str:
+    return f"{{{ns}}}{local}"
+
+
+def mml(local: str, text: str | None = None, **attrs: str) -> etree._Element:
+    element = etree.Element(qname(MML_NS, local), **attrs)
+    if text is not None:
+        element.text = text
+    return element
+
+
+def mrow(*children: etree._Element) -> etree._Element:
+    row = mml("mrow")
+    for child in children:
+        row.append(child)
+    return row
+
+
+@dataclass(frozen=True)
+class Token:
+    kind: str
+    value: str
+
+
+@dataclass
+class Node:
+    kind: str
+    value: str | None = None
+    children: tuple[Node, ...] = ()
+    meta: dict[str, str] | None = None
+
+
+class FormulaError(ValueError):
+    pass
+
+
+TOKEN_RE = re.compile(
+    r"\s*(?:"
+    r"(?P<NUMBER>\d+(?:[\.,]\d+)?)|"
+    r"(?P<IDENT>sqrt|lim|exp|sin|cos|tan|Delta|pi|inf|e[pv]|pPAIR|DERV\d+|[A-Za-z](?:\d+)?|[ΔπΓ∞])|"
+    r"(?P<OP><=|>=|!=|~=|->|=>|\+/-|[+\-*/^=<>±≠≤≥≈→⇒·×÷])|"
+    r"(?P<LPAREN>[\(\[\{])|(?P<RPAREN>[\)\]\}])|(?P<COMMA>,)"
+    r")"
+)
+
+
+def preprocess_formula(source: str) -> tuple[str, dict[str, tuple[int, str, str]]]:
+    text = source.strip()
+    derivatives: dict[str, tuple[int, str, str]] = {}
+
+    leibniz_patterns = [
+        (2, re.compile(r"\bd(?:\^?2|²)([A-Za-z])\(([^()]*)\)/d([A-Za-z])(?:\^?2|²)")),
+        (1, re.compile(r"\bd([A-Za-z])\(([^()]*)\)/d([A-Za-z])")),
+    ]
+    for order, pattern in leibniz_patterns:
+        while True:
+            match = pattern.search(text)
+            if not match:
+                break
+            key = f"DERV{len(derivatives)}"
+            derivatives[key] = (order, match.group(1), match.group(3))
+            text = text[: match.start()] + key + text[match.end() :]
+
+    derivative_patterns = [
+        (2, re.compile(r"([A-Za-z])(?:''|¨)\(([^()]*)\)")),
+        (1, re.compile(r"([A-Za-z])(?:'|′|˙)\(([^()]*)\)")),
+    ]
+    for order, pattern in derivative_patterns:
+        while True:
+            match = pattern.search(text)
+            if not match:
+                break
+            key = f"DERV{len(derivatives)}"
+            derivatives[key] = (order, match.group(1), match.group(2))
+            text = text[: match.start()] + key + text[match.end() :]
+
+    text = text.replace("limₚ→0", "lim(p->0)").replace("limₜ→∞", "lim(t->inf)")
+    text = re.sub(r"([A-Za-z0-9)\]])([" + re.escape(SUPERSCRIPT_CHARS) + r"]+)",
+                  lambda m: m.group(1) + "^" + "".join(SUPERSCRIPT_MAP[c] for c in m.group(2)), text)
+    text = text.translate(SUBSCRIPT_MAP)
+    text = re.sub(r"\bp1\s*,\s*2\b", "pPAIR", text)
+    text = text.replace("√", "sqrt").replace("+/-", "±")
+    text = text.replace("!=", "≠").replace("<=", "≤").replace(">=", "≥")
+    text = text.replace("->", "→").replace("=>", "⇒")
+    text = text.replace("×", "*").replace("·", "*").replace("÷", "/")
+    text = re.sub(r"(?:Γ|1)\(t\)", "u(t)", text)
+    text = re.sub(r"\bDelta\b", "Δ", text)
+    text = re.sub(r"\binf\b", "∞", text)
+    text = re.sub(r"\bpi\b", "π", text)
+    text = re.sub(r"e\^\{([^{}]+)\}", r"e^(\1)", text)
+    return text, derivatives
+
+
+def tokenize(text: str) -> list[Token]:
+    tokens: list[Token] = []
+    position = 0
+    while position < len(text):
+        match = TOKEN_RE.match(text, position)
+        if not match:
+            if text[position:].strip() == "":
+                break
+            raise FormulaError(f"Unrecognized formula text near: {text[position:position + 24]!r}")
+        kind = match.lastgroup
+        if kind is None:
+            raise FormulaError("Tokenizer produced an empty token")
+        tokens.append(Token(kind, match.group(kind)))
+        position = match.end()
+    tokens.append(Token("EOF", ""))
+    return tokens
+
+
+class Parser:
+    def __init__(self, tokens: Sequence[Token], derivatives: dict[str, tuple[int, str, str]]):
+        self.tokens = tokens
+        self.derivatives = derivatives
+        self.index = 0
+
+    @property
+    def current(self) -> Token:
+        return self.tokens[self.index]
+
+    def advance(self) -> Token:
+        token = self.current
+        self.index += 1
+        return token
+
+    def accept(self, kind: str, value: str | None = None) -> Token | None:
+        if self.current.kind == kind and (value is None or self.current.value == value):
+            return self.advance()
+        return None
+
+    def expect(self, kind: str) -> Token:
+        token = self.accept(kind)
+        if token is None:
+            raise FormulaError(f"Expected {kind}, got {self.current.kind} {self.current.value!r}")
+        return token
+
+    def parse(self) -> Node:
+        node = self.parse_sequence()
+        if self.current.kind != "EOF":
+            raise FormulaError(f"Unexpected token: {self.current.value!r}")
+        return node
+
+    def parse_sequence(self) -> Node:
+        nodes = [self.parse_relation()]
+        while self.accept("COMMA"):
+            nodes.append(self.parse_relation())
+        return nodes[0] if len(nodes) == 1 else Node("sequence", children=tuple(nodes))
+
+    def parse_relation(self) -> Node:
+        node = self.parse_add()
+        while self.current.kind == "OP" and self.current.value in {
+            "=", "<", ">", "≤", "≥", "≠", "~=", "→", "⇒",
+        }:
+            op = self.advance().value
+            node = Node("binary", op, (node, self.parse_add()))
+        return node
+
+    def parse_add(self) -> Node:
+        node = self.parse_mul()
+        while self.current.kind == "OP" and self.current.value in {"+", "-", "±"}:
+            op = self.advance().value
+            node = Node("binary", op, (node, self.parse_mul()))
+        return node
+
+    def starts_atom(self) -> bool:
+        return self.current.kind in {"NUMBER", "IDENT", "LPAREN"}
+
+    def parse_mul(self) -> Node:
+        node = self.parse_power()
+        while True:
+            if self.current.kind == "OP" and self.current.value in {"*", "·", "×", "/", "÷"}:
+                op = self.advance().value
+                node = Node("binary", "/" if op in {"/", "÷"} else "*", (node, self.parse_power()))
+            elif self.starts_atom():
+                node = Node("binary", "implicit", (node, self.parse_power()))
+            else:
+                break
+        return node
+
+    def parse_power(self) -> Node:
+        node = self.parse_unary()
+        if self.current.kind == "OP" and self.current.value == "^":
+            self.advance()
+            node = Node("power", children=(node, self.parse_power()))
+        return node
+
+    def parse_unary(self) -> Node:
+        if self.current.kind == "OP" and self.current.value in {"+", "-"}:
+            return Node("unary", self.advance().value, (self.parse_unary(),))
+        return self.parse_atom()
+
+    def parse_group(self) -> Node:
+        opener = self.expect("LPAREN").value
+        closer = {"(": ")", "[": "]", "{": "}"}[opener]
+        child = self.parse_sequence()
+        token = self.expect("RPAREN")
+        if token.value != closer:
+            raise FormulaError(f"Mismatched group: {opener}{token.value}")
+        return Node("group", opener + closer, (child,))
+
+    def parse_atom(self) -> Node:
+        if token := self.accept("NUMBER"):
+            return Node("number", token.value)
+        if self.current.kind == "LPAREN":
+            return self.parse_group()
+        if token := self.accept("IDENT"):
+            name = token.value
+            if name in self.derivatives:
+                order, variable, argument = self.derivatives[name]
+                return Node("derivative", children=(Node("identifier", variable), Node("identifier", argument)), meta={"order": str(order)})
+            if self.current.kind == "LPAREN":
+                group = self.parse_group()
+                if name in {"sqrt", "√"}:
+                    return Node("sqrt", children=group.children)
+                if name == "lim":
+                    return Node("limit", children=group.children)
+                return Node("function", name, group.children)
+            return Node("identifier", name)
+        raise FormulaError(f"Expected formula atom, got {self.current.kind} {self.current.value!r}")
+
+
+def identifier_mathml(value: str) -> etree._Element:
+    if value in {"∞", "inf"}:
+        return mml("mo", "∞")
+    greek = {"Delta": "Δ", "Δ": "Δ", "pi": "π", "π": "π"}
+    if value in greek:
+        return mml("mi", greek[value])
+    if value == "pPAIR":
+        sub = mml("msub")
+        sub.append(mml("mi", "p"))
+        sub.append(mrow(mml("mn", "1"), mml("mo", ","), mml("mn", "2")))
+        return sub
+    match = re.fullmatch(r"([A-Za-z])([0-9]+|[pv])", value)
+    if match:
+        sub = mml("msub")
+        sub.append(mml("mi", match.group(1)))
+        suffix = match.group(2)
+        sub.append(mml("mn" if suffix.isdigit() else "mi", suffix))
+        return sub
+    return mml("mi", value)
+
+
+def derivative_mathml(node: Node) -> etree._Element:
+    order = int((node.meta or {}).get("order", "1"))
+    variable = node_to_mathml(node.children[0])
+    argument = node_to_mathml(node.children[1])
+    function = mrow(variable, fenced(argument, "()"))
+    numerator_d = mml("mi", "d")
+    if order > 1:
+        power = mml("msup")
+        power.append(numerator_d)
+        power.append(mml("mn", str(order)))
+        numerator_d = power
+    numerator = mrow(numerator_d, function)
+    denominator_variable = node_to_mathml(node.children[1])
+    if order > 1:
+        power = mml("msup")
+        power.append(denominator_variable)
+        power.append(mml("mn", str(order)))
+        denominator_variable = power
+    denominator = mrow(mml("mi", "d"), denominator_variable)
+    fraction = mml("mfrac")
+    fraction.extend([numerator, denominator])
+    return fraction
+
+
+def fenced(child: etree._Element, brackets: str) -> etree._Element:
+    element = mml("mfenced", open=brackets[0], close=brackets[1])
+    element.append(child)
+    return element
+
+
+def node_to_mathml(node: Node) -> etree._Element:
+    if node.kind == "number":
+        return mml("mn", node.value or "")
+    if node.kind == "identifier":
+        return identifier_mathml(node.value or "")
+    if node.kind == "derivative":
+        return derivative_mathml(node)
+    if node.kind == "group":
+        return fenced(node_to_mathml(node.children[0]), node.value or "()")
+    if node.kind == "sqrt":
+        root = mml("msqrt")
+        root.append(node_to_mathml(node.children[0]))
+        return root
+    if node.kind == "function":
+        return mrow(identifier_mathml(node.value or ""), fenced(node_to_mathml(node.children[0]), "()"))
+    if node.kind == "limit":
+        under = mml("munder")
+        under.append(mml("mi", "lim"))
+        under.append(node_to_mathml(node.children[0]))
+        return under
+    if node.kind == "unary":
+        return mrow(mml("mo", node.value or ""), node_to_mathml(node.children[0]))
+    if node.kind == "power":
+        power = mml("msup")
+        exponent = node.children[1]
+        if exponent.kind == "group" and exponent.value == "()":
+            exponent = exponent.children[0]
+        power.extend([node_to_mathml(node.children[0]), node_to_mathml(exponent)])
+        return power
+    if node.kind == "binary":
+        left = node_to_mathml(node.children[0])
+        right = node_to_mathml(node.children[1])
+        if node.value == "/":
+            left_node, right_node = node.children
+            if left_node.kind == "group":
+                left = node_to_mathml(left_node.children[0])
+            if right_node.kind == "group":
+                right = node_to_mathml(right_node.children[0])
+            fraction = mml("mfrac")
+            fraction.extend([left, right])
+            return fraction
+        if node.value in {"*", "implicit"}:
+            return mrow(left, mml("mo", "\u2062"), right)
+        symbols = {"~=": "≈"}
+        return mrow(left, mml("mo", symbols.get(node.value or "", node.value or "")), right)
+    if node.kind == "sequence":
+        row = mml("mrow")
+        for index, child in enumerate(node.children):
+            if index:
+                row.append(mml("mo", ","))
+            row.append(node_to_mathml(child))
+        return row
+    raise FormulaError(f"Unsupported AST node: {node.kind}")
+
+
+def formula_to_mathml(source: str) -> etree._Element:
+    normalized, derivatives = preprocess_formula(source)
+    ast = Parser(tokenize(normalized), derivatives).parse()
+    root = mml("math", display="inline", nsmap={None: MML_NS})
+    root.append(node_to_mathml(ast))
+    return root
+
+
+def find_xsl(explicit: Path | None = None) -> Path:
+    if explicit is not None and not explicit.is_file():
+        raise FileNotFoundError(f"MML2OMML.XSL was not found at: {explicit}")
+    candidates = [
+        explicit,
+        Path(r"C:\Program Files\Microsoft Office\root\Office16\MML2OMML.XSL"),
+        Path(r"C:\Program Files (x86)\Microsoft Office\root\Office16\MML2OMML.XSL"),
+    ]
+    for candidate in candidates:
+        if candidate and candidate.exists():
+            return candidate
+    raise FileNotFoundError("MML2OMML.XSL was not found; pass --xsl with its path")
+
+
+def mathml_to_omml(math: etree._Element, transform: etree.XSLT) -> etree._Element:
+    result = transform(etree.ElementTree(math))
+    root = result.getroot()
+    if root is None:
+        raise FormulaError("MML2OMML produced no root element")
+    if root.tag == qname(M_NS, "oMathPara"):
+        equations = root.xpath(".//m:oMath", namespaces=NS)
+        if not equations:
+            raise FormulaError("MML2OMML output contains no m:oMath")
+        return copy.deepcopy(equations[0])
+    if root.tag == qname(M_NS, "oMath"):
+        return copy.deepcopy(root)
+    equations = root.xpath(".//m:oMath", namespaces=NS)
+    if not equations:
+        raise FormulaError(f"Unexpected MML2OMML root: {root.tag}")
+    return copy.deepcopy(equations[0])
+
+
+def paragraph_text(paragraph: etree._Element) -> str:
+    return "".join(paragraph.xpath(".//w:t/text()", namespaces=NS))
+
+
+def likely_code(text: str) -> bool:
+    stripped = text.strip()
+    if CODE_START_RE.search(stripped):
+        return True
+    if ";" in stripped and re.search(r"\b[A-Za-z_]\w*\s*=", stripped):
+        return True
+    if re.search(r"\b(?:tf|step|roots|exp)\s*\(", stripped) and stripped.endswith(";"):
+        return True
+    return False
+
+
+def math_score(source: str) -> int:
+    score = 0
+    score += 3 * len(re.findall(r"=|≠|<=|>=|!=", source))
+    score += 2 * len(re.findall(r"[+*/^√±∞→]", source))
+    score += len(re.findall(r"[A-Za-z]\w*\([^)]*\)", source))
+    score += len(re.findall(r"\d", source)) // 2
+    return score
+
+
+def candidate_runs(text: str) -> list[tuple[int, int, str]]:
+    candidates: list[tuple[int, int, str]] = []
+    index = 0
+    while index < len(text):
+        if text[index] not in MATH_CHARS:
+            index += 1
+            continue
+        start = index
+        while index < len(text) and text[index] in MATH_CHARS:
+            index += 1
+        end = index
+        raw = text[start:end]
+        left_trim = len(raw) - len(raw.lstrip(TRIM_PUNCT))
+        right_trim = len(raw) - len(raw.rstrip(TRIM_PUNCT))
+        start += left_trim
+        end -= right_trim
+        source = text[start:end]
+        if not source or not FORMULA_ANCHOR_RE.search(source) or math_score(source) < 4:
+            continue
+        source = re.split(r"\.\s+(?=[A-Za-z])", source, maxsplit=1)[0]
+        source = re.split(r",?\s+(?:avec|si|et|Elle|C|La|Pour)\b", source, maxsplit=1, flags=re.IGNORECASE)[0]
+        source = re.sub(
+            r"^.*\b(?:est|sont|vaut|discriminant|vers|equals?|is)\s+",
+            "",
+            source,
+            flags=re.IGNORECASE,
+        )
+        source = source.strip(TRIM_PUNCT)
+        if not source or not FORMULA_ANCHOR_RE.search(source) or math_score(source) < 4:
+            continue
+        start = text.find(source, start, end)
+        end = start + len(source)
+        if source and start >= 0:
+            candidates.append((start, end, source))
+    deduped: list[tuple[int, int, str]] = []
+    for item in candidates:
+        if not deduped or item[:2] != deduped[-1][:2]:
+            deduped.append(item)
+    return deduped
+
+
+def inspect_docx(input_path: Path) -> tuple[list[zipfile.ZipInfo], dict[str, bytes]]:
+    with zipfile.ZipFile(input_path, "r") as archive:
+        infos = archive.infolist()
+        data = {info.filename: archive.read(info.filename) for info in infos}
+    return infos, data
+
+
+def scan_docx(input_path: Path, report_path: Path) -> dict[str, object]:
+    if input_path.suffix.lower() != ".docx":
+        raise ValueError("Input must be a .docx file")
+    if not input_path.is_file():
+        raise FileNotFoundError(f"Input DOCX was not found: {input_path}")
+    _, parts = inspect_docx(input_path)
+    report: dict[str, object] = {
+        "schema_version": 1,
+        "input": str(input_path.resolve()),
+        "profile": {"derivatives": "fraction", "unit_step": "u(t)", "output": "native_word_omml"},
+        "summary": {"paragraphs": 0, "candidates": 0, "existing_equations": 0, "drawing_paragraphs": 0, "code_paragraphs": 0},
+        "candidates": [],
+    }
+    candidates: list[dict[str, object]] = []
+    summary = report["summary"]
+    assert isinstance(summary, dict)
+
+    for part_name, raw in parts.items():
+        if not TARGET_PART_RE.match(part_name):
+            continue
+        root = etree.fromstring(raw)
+        paragraphs = root.xpath(".//w:p", namespaces=NS)
+        for paragraph_index, paragraph in enumerate(paragraphs):
+            summary["paragraphs"] += 1
+            if paragraph.xpath(".//m:oMath | .//m:oMathPara", namespaces=NS):
+                summary["existing_equations"] += 1
+                continue
+            if paragraph.xpath(".//w:drawing | .//w:pict", namespaces=NS):
+                summary["drawing_paragraphs"] += 1
+                continue
+            text = paragraph_text(paragraph)
+            if not text.strip():
+                continue
+            if likely_code(text):
+                summary["code_paragraphs"] += 1
+                continue
+            for start, end, source in candidate_runs(text):
+                candidate_id = f"f{len(candidates) + 1:04d}"
+                display = text.strip() == source.strip()
+                candidate = {
+                    "id": candidate_id,
+                    "selected": True,
+                    "part": part_name,
+                    "paragraph_index": paragraph_index,
+                    "start": start,
+                    "end": end,
+                    "source": source,
+                    "linear": source,
+                    "display": display,
+                    "paragraph_text": text,
+                }
+                try:
+                    formula_to_mathml(source)
+                    candidate["parse_status"] = "ok"
+                except Exception as exc:
+                    candidate["selected"] = False
+                    candidate["parse_status"] = "review"
+                    candidate["parse_error"] = str(exc)
+                candidates.append(candidate)
+    summary["candidates"] = len(candidates)
+    report["candidates"] = candidates
+    report_path.parent.mkdir(parents=True, exist_ok=True)
+    report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    return report
+
+
+def ancestor_run(text_node: etree._Element, paragraph: etree._Element) -> etree._Element | None:
+    current = text_node.getparent()
+    while current is not None and current is not paragraph:
+        if current.tag == qname(W_NS, "r") and current.getparent() is paragraph:
+            return current
+        current = current.getparent()
+    return None
+
+
+def run_with_text_like(run: etree._Element, text: str) -> etree._Element:
+    new_run = etree.Element(qname(W_NS, "r"))
+    rpr = run.find(qname(W_NS, "rPr"))
+    if rpr is not None:
+        new_run.append(copy.deepcopy(rpr))
+    text_element = etree.SubElement(new_run, qname(W_NS, "t"))
+    if text.startswith(" ") or text.endswith(" "):
+        text_element.set(qname(XML_NS, "space"), "preserve")
+    text_element.text = text
+    return new_run
+
+
+def replace_inline_span(paragraph: etree._Element, start: int, end: int, omath: etree._Element) -> None:
+    text_nodes = paragraph.xpath(".//w:t", namespaces=NS)
+    offsets: list[tuple[etree._Element, int, int]] = []
+    cursor = 0
+    for node in text_nodes:
+        value = node.text or ""
+        offsets.append((node, cursor, cursor + len(value)))
+        cursor += len(value)
+    touched = [(node, lo, hi) for node, lo, hi in offsets if hi > start and lo < end]
+    if not touched:
+        raise FormulaError("Candidate span does not overlap any text node")
+    start_node, start_lo, _ = touched[0]
+    end_node, end_lo, _ = touched[-1]
+    start_run = ancestor_run(start_node, paragraph)
+    end_run = ancestor_run(end_node, paragraph)
+    if start_run is None or end_run is None:
+        raise FormulaError("Formula span crosses a hyperlink or unsupported nested run")
+
+    start_value = start_node.text or ""
+    end_value = end_node.text or ""
+    prefix = start_value[: max(0, start - start_lo)]
+    suffix = end_value[max(0, end - end_lo) :]
+
+    for node, lo, hi in touched:
+        value = node.text or ""
+        keep_left = value[: max(0, start - lo)] if node is start_node else ""
+        keep_right = value[max(0, end - lo) :] if node is end_node else ""
+        node.text = keep_left + keep_right
+    start_node.text = prefix
+
+    parent = paragraph
+    insert_index = parent.index(start_run) + 1
+    parent.insert(insert_index, omath)
+    if start_run is end_run and suffix:
+        start_node.text = prefix
+        parent.insert(insert_index + 1, run_with_text_like(start_run, suffix))
+
+
+def replace_display_paragraph(paragraph: etree._Element, omath: etree._Element) -> None:
+    for child in list(paragraph):
+        if child.tag != qname(W_NS, "pPr"):
+            paragraph.remove(child)
+    math_para = etree.Element(qname(M_NS, "oMathPara"))
+    math_para.append(omath)
+    paragraph.append(math_para)
+
+
+def replace_multiline_table_formula(
+    paragraph: etree._Element,
+    equations: Sequence[etree._Element],
+    suffix: str = "",
+) -> None:
+    for child in list(paragraph):
+        if child.tag != qname(W_NS, "pPr"):
+            paragraph.remove(child)
+    for index, equation in enumerate(equations):
+        if index:
+            run = etree.SubElement(paragraph, qname(W_NS, "r"))
+            etree.SubElement(run, qname(W_NS, "br"))
+        paragraph.append(equation)
+    if suffix:
+        run = etree.SubElement(paragraph, qname(W_NS, "r"))
+        text = etree.SubElement(run, qname(W_NS, "t"))
+        text.text = suffix
+
+
+def split_top_level_additive(text: str, target_length: int = 30) -> list[str]:
+    depth = 0
+    starts = [0]
+    for index, char in enumerate(text):
+        if char in "([{":
+            depth += 1
+        elif char in ")]}":
+            depth = max(0, depth - 1)
+        elif depth == 0 and char in "+-" and index > 0:
+            previous = text[index - 1]
+            if previous not in "=<>+-*/^(,":
+                starts.append(index)
+    if len(starts) == 1:
+        return [text]
+    terms = [text[starts[i] : starts[i + 1] if i + 1 < len(starts) else len(text)] for i in range(len(starts))]
+    lines: list[str] = []
+    current = ""
+    for term in terms:
+        if current and len(current) + len(term) > target_length:
+            lines.append(current)
+            current = term
+        else:
+            current += term
+    if current:
+        lines.append(current)
+    return lines
+
+
+def estimated_formula_width(text: str) -> int:
+    derivative_count = len(re.findall(r"(?:''|'|¨|˙)\s*\(", text))
+    return len(text) + derivative_count * 18
+
+
+def set_math_font_size(omath: etree._Element, half_points: int) -> None:
+    for math_run in omath.xpath(".//m:r", namespaces=NS):
+        word_rpr = math_run.find(qname(W_NS, "rPr"))
+        if word_rpr is None:
+            word_rpr = etree.Element(qname(W_NS, "rPr"))
+            math_rpr = math_run.find(qname(M_NS, "rPr"))
+            insert_at = 1 if math_rpr is not None else 0
+            math_run.insert(insert_at, word_rpr)
+        for local in ("sz", "szCs"):
+            size = word_rpr.find(qname(W_NS, local))
+            if size is None:
+                size = etree.SubElement(word_rpr, qname(W_NS, local))
+            size.set(qname(W_NS, "val"), str(half_points))
+
+
+def apply_docx(
+    input_path: Path,
+    review_path: Path,
+    output_path: Path,
+    result_path: Path,
+    xsl_path: Path,
+) -> dict[str, object]:
+    if input_path.suffix.lower() != ".docx" or output_path.suffix.lower() != ".docx":
+        raise ValueError("Input and output must be .docx files")
+    if input_path.resolve() == output_path.resolve():
+        raise ValueError("Refusing to overwrite the input DOCX")
+    review = json.loads(review_path.read_text(encoding="utf-8"))
+    candidates = [c for c in review.get("candidates", []) if c.get("selected")]
+    infos, parts = inspect_docx(input_path)
+    transform = etree.XSLT(etree.parse(str(xsl_path)))
+    result: dict[str, object] = {
+        "input": str(input_path.resolve()),
+        "output": str(output_path.resolve()),
+        "review": str(review_path.resolve()),
+        "xsl": str(xsl_path.resolve()),
+        "converted": [],
+        "skipped": [],
+    }
+
+    grouped: dict[tuple[str, int], list[dict[str, object]]] = {}
+    for candidate in candidates:
+        key = (str(candidate["part"]), int(candidate["paragraph_index"]))
+        grouped.setdefault(key, []).append(candidate)
+
+    for (part_name, paragraph_index), group in grouped.items():
+        if part_name not in parts:
+            for candidate in group:
+                result["skipped"].append({"id": candidate.get("id"), "error": "DOCX part not found"})
+            continue
+        root = etree.fromstring(parts[part_name])
+        paragraphs = root.xpath(".//w:p", namespaces=NS)
+        if paragraph_index >= len(paragraphs):
+            for candidate in group:
+                result["skipped"].append({"id": candidate.get("id"), "error": "Paragraph index out of range"})
+            continue
+        paragraph = paragraphs[paragraph_index]
+        original_text = paragraph_text(paragraph)
+        for candidate in sorted(group, key=lambda c: int(c["start"]), reverse=True):
+            try:
+                start, end = int(candidate["start"]), int(candidate["end"])
+                source = str(candidate["source"])
+                if original_text[start:end] != source:
+                    raise FormulaError("Reviewed source no longer matches the paragraph span")
+                linear = str(candidate.get("linear", source))
+                in_table = bool(paragraph.xpath("ancestor::w:tc", namespaces=NS))
+                is_display = bool(candidate.get("display")) and source.strip() == original_text.strip()
+                outside_formula = original_text[:start] + original_text[end:]
+                covers_formula_paragraph = not outside_formula.strip(TRIM_PUNCT)
+                table_lines = (
+                    split_top_level_additive(linear)
+                    if in_table and covers_formula_paragraph and estimated_formula_width(linear) > 65
+                    else [linear]
+                )
+                equations = [mathml_to_omml(formula_to_mathml(line), transform) for line in table_lines]
+                if in_table:
+                    for equation in equations:
+                        set_math_font_size(equation, 16)
+                if len(equations) > 1:
+                    replace_multiline_table_formula(paragraph, equations, original_text[end:])
+                elif is_display:
+                    omath = equations[0]
+                    replace_display_paragraph(paragraph, omath)
+                else:
+                    omath = equations[0]
+                    replace_inline_span(paragraph, start, end, omath)
+                result["converted"].append({"id": candidate.get("id"), "source": source, "part": part_name, "lines": len(equations)})
+            except Exception as exc:
+                result["skipped"].append({"id": candidate.get("id"), "source": candidate.get("source"), "error": str(exc)})
+        parts[part_name] = etree.tostring(root, xml_declaration=True, encoding="UTF-8", standalone=True)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = output_path.with_suffix(output_path.suffix + ".tmp")
+    try:
+        with zipfile.ZipFile(tmp_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+            for info in infos:
+                archive.writestr(info, parts[info.filename])
+        shutil.move(str(tmp_path), str(output_path))
+    finally:
+        tmp_path.unlink(missing_ok=True)
+    result["converted_count"] = len(result["converted"])
+    result["skipped_count"] = len(result["skipped"])
+    result_path.parent.mkdir(parents=True, exist_ok=True)
+    result_path.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+    return result

mathfmt-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: mathfmt
+Version: 0.1.0
+Summary: Typeset plain-text formulas in DOCX files as native Word equations.
+Author: Leo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gml853503962-creator/mathfmt
+Project-URL: Repository, https://github.com/gml853503962-creator/mathfmt
+Project-URL: Issues, https://github.com/gml853503962-creator/mathfmt/issues
+Keywords: docx,word,math,omml,equation,typesetting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Text Processing :: Markup :: XML
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lxml>=5.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# MathFmt
+
+[中文](#中文) | [English](#english)
+
+MathFmt turns awkward plain-text formulas in Word documents into native Word equations suitable for
+textbooks, exams, and technical reports. Processing stays on your computer.
+
+## 中文
+
+MathFmt 将 DOCX 文档中的普通文本公式转换为 Word 原生 OMML 公式，例如把 `ds(t)/dt`、
+`sqrt(x^2+1)` 和 `p1` 排版为纸质教材中常见的分式、根号与上下标。
+
+### 特点
+
+- 保留原始 DOCX，始终写入新文件。
+- 支持正文、表格、页眉、页脚和混合文本公式。
+- 自动跳过代码、图片公式和已有 Word 原生公式。
+- 提供可审核流程和保守的一键转换。
+- 完全本地运行，不上传文档。
+
+### 环境要求
+
+- Windows 10/11
+- Python 3.10 或更高版本
+- Microsoft Word/Office，并包含 `MML2OMML.XSL`
+
+MathFmt 不分发微软的 XSL 文件。它会自动检查常见 Office 安装目录，也可使用 `--xsl` 指定路径。
+
+### 安装
+
+```powershell
+pip install mathfmt
+mathfmt doctor
+```
+
+从源码开发安装：
+
+```powershell
+git clone https://github.com/gml853503962-creator/mathfmt.git
+cd mathfmt
+python -m pip install -e ".[dev]"
+```
+
+### 使用
+
+```powershell
+# 保守的一键转换
+mathfmt convert input.docx
+
+# 审核后转换
+mathfmt scan input.docx --report candidates.json
+mathfmt apply input.docx --review candidates.json --output output.docx --report result.json
+```
+
+一键转换默认生成 `input.mathfmt.docx` 和 `input.mathfmt.report.json`，不会覆盖原文件。编辑
+`candidates.json` 中的 `selected`、`source` 或 `linear` 后再执行 `apply`。如果 Office 安装在
+非标准目录，为 `apply`、`convert` 或 `doctor` 添加 `--xsl C:\path\to\MML2OMML.XSL`。
+
+### Codex Skill
+
+仓库中的 `skills/mathfmt` 可复制到 Codex 技能目录。技能依赖已安装的 `mathfmt` 命令。
+
+## English
+
+MathFmt converts plain-text formulas in DOCX files into native Word OMML equations with stacked
+fractions, radicals, superscripts, subscripts, derivatives, and standard mathematical operators.
+
+### Highlights
+
+- Never overwrites the source DOCX.
+- Handles body text, tables, headers, footers, and formulas mixed with prose.
+- Skips likely code, image formulas, and existing Word equations.
+- Offers both a review-first workflow and conservative one-step conversion.
+- Processes documents locally without uploading them.
+
+### Requirements and installation
+
+MathFmt 0.1 supports Windows, Python 3.10+, and a Microsoft Office installation containing
+`MML2OMML.XSL`. The Microsoft stylesheet is detected locally and is not distributed with MathFmt.
+
+```powershell
+pip install mathfmt
+mathfmt doctor
+mathfmt convert input.docx
+```
+
+For review-first conversion, run `scan`, edit the generated JSON, then run `apply` as shown above.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md),
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT License. Copyright (c) 2026 Leo.

mathfmt-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mathfmt/__init__.py,sha256=3pPdh3QI-DGkkCcIzF9Qs80tuHoB3rldk6L3wGJgZe4,190
+mathfmt/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+mathfmt/cli.py,sha256=qLQ_BunCTG1S4AzV4GyFgcHgTAGmJrxux50EtM0Xb7c,5073
+mathfmt/core.py,sha256=t-QTXLwZT63TfEC5vVkKW7gtvhkk806SBzB82bCF-0Y,30707
+mathfmt-0.1.0.dist-info/licenses/LICENSE,sha256=D9t3XgDm_d4jmEtPEYTNE8NBNcqsHnFK1IkUHCOXBLw,1060
+mathfmt-0.1.0.dist-info/METADATA,sha256=VTZPuSbCPirrMMJNlhauzb5EIIx11OmpeQR6gwQYBGM,4450
+mathfmt-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mathfmt-0.1.0.dist-info/entry_points.txt,sha256=ZZ8BY4-gwAGDz1vLaq68V5TY0BSk9SM34EWRI6hF1qI,45
+mathfmt-0.1.0.dist-info/top_level.txt,sha256=ZSUOpS_ciCol-UY9sp5gA39eSEirrTFSwwCpF2eKXb0,8
+mathfmt-0.1.0.dist-info/RECORD,,

mathfmt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mathfmt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mathfmt = mathfmt.cli:main

mathfmt-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mathfmt-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mathfmt