python-hwpx 5.1.1__py3-none-any.whl → 5.3.0__py3-none-any.whl

hwpx/__init__.py

@@ -48,6 +48,10 @@ _EXPERIMENTAL_EXPORTS = {
     # 문서 프리뷰 뷰어(3.8.0 신규). 계약 유동.
     "DocumentViewer": "hwpx.tools.document_viewer",
     "render_document_viewer": "hwpx.tools.document_viewer",
+    # 수식 저작(5.2.0 신규, LaTeX -> EqEdit). 계약 유동.
+    "UnsupportedLatexError": "hwpx.equation.authoring",
+    "estimate_equation_size": "hwpx.equation.authoring",
+    "latex_to_eqedit": "hwpx.equation.authoring",
 }
 
 # Emptied in 5.0. The 4.x notice on these names said they would go in the next

hwpx/_document/shapes.py

@@ -227,3 +227,133 @@ def add_ellipse(
         line_color=line_color, line_width=line_width,
         fill_color=fill_color, treat_as_char=treat_as_char,
     )
+
+
+def add_equation(
+    doc: "HwpxDocument",
+    script: str,
+    *,
+    paragraph: HwpxOxmlParagraph | None = None,
+    section: HwpxOxmlSection | None = None,
+    section_index: int | None = None,
+    base_unit: int = 1100,
+    size: tuple[int, int] | None = None,
+    char_pr_id_ref: str | int | None = None,
+) -> HwpxOxmlInlineObject:
+    """Insert an inline equation and prove the standard reader recognizes it.
+
+    The emitted XML follows the real-Hancom ``<hp:equation>`` contract
+    (specs/054-equation-authoring/evidence/p0/equation-contract.md). After
+    insertion the equation is re-read through the standard section scan —
+    creation fails loudly if the script did not land verbatim (no
+    special-casing by design).
+    """
+    from ..equation.authoring import estimate_equation_size
+    from ..equation.eqedit import MAX_SOURCE_LENGTH
+    from ..oxml.namespaces import HP
+
+    text = (script or "").strip()
+    if not text:
+        raise ValueError("equation script must be a non-empty string")
+    if len(text) > MAX_SOURCE_LENGTH:
+        raise ValueError("equation script exceeds size limit")
+    if paragraph is None:
+        paragraph = doc.add_paragraph(
+            "", section=section, section_index=section_index,
+            include_run=False,
+        )
+    if size is None:
+        size = estimate_equation_size(text, base_unit=base_unit)
+    inline_object = paragraph.add_equation(
+        text, base_unit=base_unit, size=size, char_pr_id_ref=char_pr_id_ref,
+    )
+
+    created_id = inline_object.element.get("id", "")
+    for owning_section in doc.sections:
+        for candidate in owning_section.element.iter(f"{HP}equation"):
+            if candidate.get("id") != created_id:
+                continue
+            script_element = candidate.find(f"{HP}script")
+            if script_element is None or (script_element.text or "") != text:
+                raise RuntimeError(
+                    "created equation did not store its script verbatim"
+                )
+            return inline_object
+    raise RuntimeError(
+        "created equation was not recognized by the standard section scan"
+    )
+
+
+def add_chart(
+    doc: "HwpxDocument",
+    chart_xml: bytes | str,
+    *,
+    paragraph: HwpxOxmlParagraph | None = None,
+    section: HwpxOxmlSection | None = None,
+    section_index: int | None = None,
+    size: tuple[int, int] | None = None,
+    treat_as_char: bool = False,
+    char_pr_id_ref: str | int | None = None,
+) -> HwpxOxmlInlineObject:
+    """Add a chartML part and its ``<hp:chart>`` anchor, then prove recognition.
+
+    The part is stored under ``Chart/chartN.xml`` and addressed directly by
+    the anchor's ``chartIDRef`` — real Hancom registers chart parts in no
+    manifest and draws the chart from the ECMA-376 chartML alone
+    (specs/055-chart-authoring/evidence/p0/chart-contract.md). The chartML is
+    validated to parse and to carry the ``c:chartSpace`` root before any part
+    is written; after insertion the anchor is re-read through the standard
+    section scan — creation fails loudly if it did not land (no
+    special-casing by design).
+    """
+    from lxml import etree as _etree  # type: ignore[reportAttributeAccessIssue]  # lxml has no complete bundled typing
+
+    from ..oxml.namespaces import HP
+
+    _CHART_SPACE = "{http://schemas.openxmlformats.org/drawingml/2006/chart}chartSpace"
+
+    data = chart_xml.encode("utf-8") if isinstance(chart_xml, str) else bytes(chart_xml)
+    if not data.strip():
+        raise ValueError("chart_xml must be non-empty chartML")
+    try:
+        root = _etree.fromstring(data)
+    except _etree.XMLSyntaxError as exc:
+        raise ValueError(f"chart_xml is not well-formed XML: {exc}") from exc
+    if root.tag != _CHART_SPACE:
+        raise ValueError(
+            "chart_xml root must be the ECMA-376 c:chartSpace element, "
+            f"got {root.tag!r}"
+        )
+
+    existing = {name for name in doc._package.part_names() if name.startswith("Chart/")}
+    n = 1
+    while f"Chart/chart{n}.xml" in existing:
+        n += 1
+    part_path = f"Chart/chart{n}.xml"
+
+    if paragraph is None:
+        paragraph = doc.add_paragraph(
+            "", section=section, section_index=section_index,
+            include_run=False,
+        )
+    doc._package.write(part_path, data)
+    inline_object = paragraph.add_chart(
+        part_path,
+        size=size,
+        treat_as_char=treat_as_char,
+        char_pr_id_ref=char_pr_id_ref,
+    )
+
+    created_id = inline_object.element.get("id", "")
+    for owning_section in doc.sections:
+        for candidate in owning_section.element.iter(f"{HP}chart"):
+            if candidate.get("id") != created_id:
+                continue
+            if candidate.get("chartIDRef") != part_path:
+                raise RuntimeError(
+                    "created chart anchor does not reference its part"
+                )
+            return inline_object
+    raise RuntimeError(
+        "created chart was not recognized by the standard section scan"
+    )

hwpx/document.py

@@ -1431,6 +1431,95 @@ class HwpxDocument:
         )
 
 
+    def add_chart(
+        self,
+        chart_xml: bytes | str,
+        *,
+        paragraph: HwpxOxmlParagraph | None = None,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+        size: tuple[int, int] | None = None,
+        treat_as_char: bool = False,
+        char_pr_id_ref: str | int | None = None,
+    ) -> HwpxOxmlInlineObject:
+        """Insert a native chart from ECMA-376 chartML. **Experimental contract.**
+
+        Stores *chart_xml* as a ``Chart/chartN.xml`` package part and emits the
+        real-Hancom ``<hp:chart>`` anchor referencing it via ``chartIDRef``
+        (contract: ``specs/055-chart-authoring/evidence/p0/chart-contract.md``).
+        Hancom draws the chart from the chartML alone — no OLE fallback or
+        pre-rendered image is written. The chartML must parse and carry the
+        ``c:chartSpace`` root (typed rejection otherwise), and the created
+        anchor is re-read through the standard section scan — creation fails
+        loudly if the standard consumer would not see it.
+
+        Args:
+            chart_xml: ECMA-376 chartML document (``c:chartSpace``).
+            paragraph: Target paragraph (e.g. inside a table cell). When
+                omitted a new paragraph is appended to *section*.
+            size: Optional ``(width, height)`` HWPUNIT pair for the anchor.
+            treat_as_char: ``True`` places the chart inline in the text flow;
+                default mirrors the render-verified gold float placement.
+        """
+
+        return _shapes.add_chart(
+            self,
+            chart_xml,
+            paragraph=paragraph,
+            section=section,
+            section_index=section_index,
+            size=size,
+            treat_as_char=treat_as_char,
+            char_pr_id_ref=char_pr_id_ref,
+        )
+
+    def add_equation(
+        self,
+        script: str,
+        *,
+        paragraph: HwpxOxmlParagraph | None = None,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+        base_unit: int = 1100,
+        size: tuple[int, int] | None = None,
+        char_pr_id_ref: str | int | None = None,
+    ) -> HwpxOxmlInlineObject:
+        """Insert an inline equation from an EqEdit script. **Experimental contract.**
+
+        Emits the real-Hancom ``<hp:equation>`` shape (contract:
+        ``specs/054-equation-authoring/evidence/p0/equation-contract.md``): the
+        EqEdit source is stored verbatim in ``<hp:script>``, no layout cache is
+        written (Hancom re-lays-out on open), and the shape is inline so it
+        renders in the page flow. The created element is immediately re-read
+        through the standard section scan — creation fails loudly if the
+        standard consumer would not see it (no special-casing by design).
+
+        To author from LaTeX, convert first (typed refusal outside the
+        verified token set)::
+
+            from hwpx.equation import latex_to_eqedit
+            doc.add_equation(latex_to_eqedit(r"\\frac{a}{b}"))
+
+        Args:
+            script: EqEdit script stored as-is (e.g. ``{a} over {b}``).
+            paragraph: Target paragraph (e.g. inside a table cell). When
+                omitted a new paragraph is appended to *section*.
+            base_unit: Equation base font size in 1/100 pt.
+            size: Optional explicit ``(width, height)`` HWPUNIT pair;
+                defaults to a proportional estimate (Hancom re-measures).
+        """
+
+        return _shapes.add_equation(
+            self,
+            script,
+            paragraph=paragraph,
+            section=section,
+            section_index=section_index,
+            base_unit=base_unit,
+            size=size,
+            char_pr_id_ref=char_pr_id_ref,
+        )
+
     def set_page_size(
         self,
         *,

hwpx/equation/__init__.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Reader-direction equation support: EqEdit → LaTeX → MathML.
+"""Equation support: EqEdit → LaTeX → MathML (reader) and LaTeX → EqEdit (authoring).
 
 Clean-room re-derivation of the HULK-style EqEdit vocabulary; see NOTICE for the
 referenced projects.  ``latex2mathml`` is an optional dependency
@@ -9,6 +9,11 @@ block rather than dropping the equation.
 
 from __future__ import annotations
 
+from .authoring import (
+    UnsupportedLatexError,
+    estimate_equation_size,
+    latex_to_eqedit,
+)
 from .eqedit import (
     MAX_GROUP_DEPTH,
     MAX_SOURCE_LENGTH,
@@ -39,8 +44,11 @@ __all__ = [
     "EquationConversionError",
     "EquationRender",
     "MathMLUnavailableError",
+    "UnsupportedLatexError",
     "eqedit_to_latex",
+    "estimate_equation_size",
     "latex2mathml_available",
+    "latex_to_eqedit",
     "latex_to_mathml",
     "render_equation",
 ]

hwpx/equation/authoring.py

@@ -0,0 +1,457 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Authoring-direction LaTeX → EqEdit converter (clean-room). **Experimental.**
+
+Reverse of :func:`hwpx.equation.eqedit.eqedit_to_latex`: turns a LaTeX math
+fragment into the EqEdit script Hancom's equation editor stores inside
+``<hp:script>``.  Coverage is the verified token set only — any LaTeX command
+or environment outside it raises :class:`UnsupportedLatexError` (typed
+refusal), never a silent approximation, so callers can fail closed.
+
+The token vocabulary is the same clean-room re-derivation used by the reader
+(:mod:`hwpx.equation.tokens`); the authoring direction additionally protects
+bare identifiers that collide with EqEdit reserved words by quoting them
+(``T_{int}`` → ``T _{"int"}``) so Hancom does not typeset them as symbols.
+
+Contract provenance: specs/054-equation-authoring/evidence/p0/equation-contract.md.
+"""
+
+from __future__ import annotations
+
+from .eqedit import (
+    MAX_GROUP_DEPTH,
+    MAX_SOURCE_LENGTH,
+    EquationConversionError,
+)
+from .tokens import (
+    ACCENTS,
+    BIG_OPERATORS,
+    DELIMITERS,
+    FUNCTIONS,
+    GREEK,
+    MATRIX_ENVIRONMENTS,
+    OPERATORS,
+    STRUCTURAL,
+)
+
+
+class UnsupportedLatexError(EquationConversionError):
+    """Raised when a LaTeX fragment uses commands outside the verified set."""
+
+
+def _invert(*maps: dict[str, str]) -> dict[str, str]:
+    """LaTeX command → canonical EqEdit token (first-seen wins per map order)."""
+
+    inverse: dict[str, str] = {}
+    for mapping in maps:
+        for eqedit_token, latex_command in mapping.items():
+            inverse.setdefault(latex_command, eqedit_token)
+    return inverse
+
+
+# Commands whose only EqEdit spellings render as literal text (or wrong glyphs)
+# on the real Hancom build — render-verified 2026-07-31, specs/054 P2 token
+# battery. Emitting them would silently corrupt output, so they are excluded
+# from the inverse maps and refuse with UnsupportedLatexError instead.
+_RENDER_REJECTED = frozenset(
+    {"\\limsup", "\\liminf", "\\widehat", "\\widetilde"}
+)
+
+# Word-token maps first so lowercase word forms win (``times`` over ``TIMES``);
+# explicit preferences below override where the render oracle verified a
+# different spelling than the reader's first-seen entry.
+_LATEX_TO_EQEDIT: dict[str, str] = {
+    latex: eqedit
+    for latex, eqedit in _invert(GREEK, OPERATORS, FUNCTIONS, BIG_OPERATORS).items()
+    if latex not in _RENDER_REJECTED
+}
+_LATEX_TO_EQEDIT.update(
+    {
+        # Gold scripts spell these symbolically (equation-contract.md §4).
+        "\\pm": "+-",
+        "\\mp": "-+",
+        # Render-verified spellings (P2 token battery): the word ``to`` kills
+        # the rest of the equation, ``leftrightarrow`` draws a plain arrow,
+        # lowercase ``forall`` and ``iint``/``iiint`` come out as literal text.
+        "\\to": "->",
+        "\\rightarrow": "->",
+        "\\leftrightarrow": "<->",
+        "\\forall": "FORALL",
+        "\\iint": "dint",
+        "\\iiint": "tint",
+        # Common LaTeX aliases sharing a verified target.
+        "\\le": "leq",
+        "\\ge": "geq",
+        "\\ne": "neq",
+        "\\dots": "cdots",
+    }
+)
+_LATEX_ACCENTS: dict[str, str] = {
+    latex: eqedit
+    for latex, eqedit in _invert(ACCENTS).items()
+    if latex not in _RENDER_REJECTED
+}
+# LaTeX delimiter commands usable after \left / \right.
+_LATEX_DELIMITERS: dict[str, str] = {
+    latex: eqedit
+    for eqedit, latex in DELIMITERS.items()
+    if latex.startswith("\\")
+    # Prefer the symbol spellings (``{`` not ``LBRACE``) — both read back.
+    and eqedit not in {"LBRACE", "RBRACE", "LANGLE", "RANGLE"}
+}
+_TEXT_COMMANDS = frozenset({"\\text", "\\mathrm", "\\textrm", "\\mbox"})
+# LaTeX environment name → render-verified EqEdit builder word. ``Bmatrix`` /
+# ``Vmatrix`` have no verified spelling on the real build (P2 battery R10/R11)
+# and refuse; the determinant matrix is EqEdit ``dmatrix`` (R12).
+_ENV_TO_EQEDIT: dict[str, str] = {
+    "matrix": "matrix",
+    "pmatrix": "pmatrix",
+    "bmatrix": "bmatrix",
+    "vmatrix": "dmatrix",
+    "cases": "cases",
+}
+
+# Bare identifier runs that would collide with EqEdit vocabulary must be quoted
+# so Hancom keeps them literal (reserved-word protection).
+_RESERVED_WORDS = (
+    frozenset(GREEK)
+    | frozenset(OPERATORS)
+    | frozenset(FUNCTIONS)
+    | frozenset(BIG_OPERATORS)
+    | frozenset(ACCENTS)
+    | frozenset(MATRIX_ENVIRONMENTS)
+    | STRUCTURAL
+)
+
+_SINGLE_CHAR_PASSTHROUGH = frozenset("+-=<>,.;:!|/()[]'")
+
+
+class _LatexLexer:
+    def __init__(self, source: str) -> None:
+        self._source = source
+        self._pos = 0
+        self.tokens: list[str] = []
+        self._lex()
+
+    def _lex(self) -> None:
+        source = self._source
+        i = 0
+        n = len(source)
+        while i < n:
+            ch = source[i]
+            if ch.isspace():
+                i += 1
+            elif ch == "\\":
+                i = self._lex_command(i)
+            elif ch in "{}^_&":
+                self.tokens.append(ch)
+                i += 1
+            elif ch.isdigit() or ch == ".":
+                j = i
+                while j < n and (source[j].isdigit() or source[j] == "."):
+                    j += 1
+                self.tokens.append(source[i:j])
+                i = j
+            elif ch.isalpha():
+                j = i
+                while j < n and source[j].isalpha():
+                    j += 1
+                self.tokens.append(source[i:j])
+                i = j
+            elif ch in _SINGLE_CHAR_PASSTHROUGH:
+                self.tokens.append(ch)
+                i += 1
+            else:
+                raise UnsupportedLatexError(
+                    f"unsupported character in LaTeX input: {ch!r}"
+                )
+
+    def _lex_command(self, i: int) -> int:
+        source = self._source
+        n = len(source)
+        if i + 1 >= n:
+            raise UnsupportedLatexError("dangling backslash at end of input")
+        nxt = source[i + 1]
+        if nxt == "\\":
+            self.tokens.append("\\\\")
+            return i + 2
+        if not nxt.isalpha():
+            # Escaped single character: \{ \} \% \& \$ \| \, ...
+            self.tokens.append("\\" + nxt)
+            return i + 2
+        j = i + 1
+        while j < n and source[j].isalpha():
+            j += 1
+        self.tokens.append(source[i:j])
+        return j
+
+
+class _LatexParser:
+    """Recursive-descent LaTeX → EqEdit token emitter (verified set only)."""
+
+    def __init__(self, tokens: list[str]) -> None:
+        self._tokens = tokens
+        self._pos = 0
+
+    def _peek(self) -> str | None:
+        return self._tokens[self._pos] if self._pos < len(self._tokens) else None
+
+    def _next(self) -> str | None:
+        token = self._peek()
+        if token is not None:
+            self._pos += 1
+        return token
+
+    def _expect(self, expected: str) -> None:
+        token = self._next()
+        if token != expected:
+            raise UnsupportedLatexError(
+                f"expected {expected!r}, found {token!r} — unbalanced LaTeX group"
+            )
+
+    # -- grammar -------------------------------------------------------------
+    def parse(self) -> str:
+        parts = self._sequence(depth=0, stop=frozenset())
+        if self._peek() is not None:
+            raise UnsupportedLatexError(
+                f"unbalanced LaTeX group near {self._peek()!r}"
+            )
+        return " ".join(parts)
+
+    def _sequence(self, *, depth: int, stop: frozenset[str]) -> list[str]:
+        if depth > MAX_GROUP_DEPTH:
+            raise EquationConversionError("equation nesting depth exceeded")
+        parts: list[str] = []
+        while True:
+            token = self._peek()
+            if token is None or token in stop:
+                break
+            if token in ("^", "_"):
+                self._next()
+                script = self._group_or_atom(depth)
+                parts.append(f"{token}{{{script}}}")
+                continue
+            parts.append(self._atom(depth))
+        return parts
+
+    def _group_or_atom(self, depth: int) -> str:
+        """A script/argument body, brace-stripped (rebraced by the caller)."""
+
+        if self._peek() == "{":
+            self._next()
+            inner = self._sequence(depth=depth + 1, stop=frozenset({"}"}))
+            self._expect("}")
+            return " ".join(inner)
+        return self._atom(depth)
+
+    def _atom(self, depth: int) -> str:
+        token = self._next()
+        if token is None:
+            return ""
+        if token == "{":
+            inner = self._sequence(depth=depth + 1, stop=frozenset({"}"}))
+            self._expect("}")
+            return "{" + " ".join(inner) + "}"
+        if token == "}":
+            raise UnsupportedLatexError("unbalanced closing brace in LaTeX input")
+        if token == "\\frac" or token == "\\dfrac" or token == "\\tfrac":
+            numerator = self._group_or_atom(depth)
+            denominator = self._group_or_atom(depth)
+            return f"{{{numerator}}} over {{{denominator}}}"
+        if token == "\\sqrt":
+            if self._peek() == "[":
+                self._next()
+                index_parts = self._sequence(depth=depth + 1, stop=frozenset({"]"}))
+                self._expect("]")
+                radicand = self._group_or_atom(depth)
+                return f"root {{{' '.join(index_parts)}}} of {{{radicand}}}"
+            return f"sqrt {{{self._group_or_atom(depth)}}}"
+        if token in _TEXT_COMMANDS:
+            return self._text_literal()
+        if token == "\\begin":
+            return self._environment(depth)
+        if token == "\\left":
+            return self._left_right(depth)
+        if token in ("\\right", "\\end"):
+            raise UnsupportedLatexError(f"{token} without a matching opener")
+        if token in _LATEX_ACCENTS:
+            return f"{_LATEX_ACCENTS[token]} {{{self._group_or_atom(depth)}}}"
+        if token in _LATEX_TO_EQEDIT:
+            return _LATEX_TO_EQEDIT[token]
+        if token == "\\\\":
+            raise UnsupportedLatexError(
+                "row break (\\\\) is only supported inside a matrix/cases environment"
+            )
+        if token.startswith("\\") and len(token) == 2 and not token[1].isalpha():
+            return self._escaped_char(token[1])
+        if token.startswith("\\"):
+            raise UnsupportedLatexError(f"unsupported LaTeX command: {token}")
+        if token == "&":
+            raise UnsupportedLatexError(
+                "alignment (&) is only supported inside a matrix/cases environment"
+            )
+        return self._plain_token(token)
+
+    def _escaped_char(self, char: str) -> str:
+        if char in "{}":
+            # EqEdit spells literal braces as the LBRACE/RBRACE words.
+            return "LBRACE" if char == "{" else "RBRACE"
+        if char in "%$&":
+            return char
+        raise UnsupportedLatexError(f"unsupported LaTeX escape: \\{char}")
+
+    def _plain_token(self, token: str) -> str:
+        if token.isalpha() and token in _RESERVED_WORDS:
+            # Reserved-word protection: keep the identifier literal in Hancom.
+            return f'"{token}"'
+        return token
+
+    def _text_literal(self) -> str:
+        self._expect("{")
+        parts: list[str] = []
+        while True:
+            token = self._peek()
+            if token is None:
+                raise UnsupportedLatexError("unterminated \\text{...} literal")
+            if token == "}":
+                self._next()
+                break
+            if token in ("{", "\\\\") or (
+                isinstance(token, str) and token.startswith("\\") and len(token) > 2
+            ):
+                raise UnsupportedLatexError(
+                    "\\text{...} supports plain characters only"
+                )
+            self._next()
+            parts.append(token[1] if token.startswith("\\") else token)
+        literal = " ".join(parts)
+        if '"' in literal:
+            raise UnsupportedLatexError('\\text{...} may not contain a quote (")')
+        return f'"{literal}"'
+
+    def _environment(self, depth: int) -> str:
+        self._expect("{")
+        name = self._next()
+        if name == "}":
+            raise UnsupportedLatexError("empty \\begin{} environment name")
+        self._expect("}")
+        builder = _ENV_TO_EQEDIT.get(name or "")
+        if builder is None:
+            raise UnsupportedLatexError(f"unsupported LaTeX environment: {name}")
+        rows: list[list[str]] = [[]]
+        current: list[str] = []
+
+        def flush_cell() -> None:
+            rows[-1].append(" ".join(current))
+            current.clear()
+
+        while True:
+            token = self._peek()
+            if token is None:
+                raise UnsupportedLatexError(f"unterminated environment: {name}")
+            if token == "\\end":
+                self._next()
+                self._expect("{")
+                end_name = self._next()
+                self._expect("}")
+                if end_name != name:
+                    raise UnsupportedLatexError(
+                        f"environment mismatch: \\begin{{{name}}} closed by "
+                        f"\\end{{{end_name}}}"
+                    )
+                break
+            if token == "&":
+                self._next()
+                flush_cell()
+                continue
+            if token == "\\\\":
+                self._next()
+                flush_cell()
+                rows.append([])
+                continue
+            if token in ("^", "_"):
+                self._next()
+                current.append(f"{token}{{{self._group_or_atom(depth)}}}")
+                continue
+            current.append(self._atom(depth))
+        flush_cell()
+        body = " # ".join(
+            " & ".join(cell for cell in row) for row in rows if any(row)
+        )
+        return f"{builder} {{{body}}}"
+
+    def _left_right(self, depth: int) -> str:
+        open_token = self._next()
+        open_delim = self._delimiter(open_token)
+        body = self._sequence(depth=depth + 1, stop=frozenset({"\\right"}))
+        if self._peek() != "\\right":
+            raise UnsupportedLatexError("\\left without a matching \\right")
+        self._next()
+        close_token = self._next()
+        close_delim = self._delimiter(close_token)
+        inner = " ".join(body)
+        return f"LEFT {open_delim} {inner} RIGHT {close_delim}"
+
+    def _delimiter(self, token: str | None) -> str:
+        if token is None:
+            raise UnsupportedLatexError("missing \\left/\\right delimiter")
+        if token in _LATEX_DELIMITERS:
+            return _LATEX_DELIMITERS[token]
+        if token in ("\\{", "\\}"):
+            return "LBRACE" if token == "\\{" else "RBRACE"
+        if token in DELIMITERS and len(token) == 1:
+            return token
+        raise UnsupportedLatexError(f"unsupported \\left/\\right delimiter: {token}")
+
+
+def _strip_math_delimiters(latex: str) -> str:
+    text = latex.strip()
+    for fence in ("$$", "$"):
+        if text.startswith(fence) and text.endswith(fence) and len(text) > 2 * len(fence):
+            return text[len(fence) : -len(fence)].strip()
+    return text
+
+
+def latex_to_eqedit(latex: str) -> str:
+    """Convert a LaTeX math fragment to an EqEdit ``<hp:script>`` string.
+
+    Surrounding ``$...$`` / ``$$...$$`` fences are stripped for convenience.
+    Anything outside the verified token set raises
+    :class:`UnsupportedLatexError` — no silent approximation.
+
+    Raises:
+        UnsupportedLatexError: unsupported command/environment/character.
+        EquationConversionError: size or nesting-depth guard exceeded.
+    """
+
+    if len(latex) > MAX_SOURCE_LENGTH:
+        raise EquationConversionError("LaTeX input exceeds size limit")
+    text = _strip_math_delimiters(latex)
+    if "$" in text:
+        raise UnsupportedLatexError("interior $ math delimiters are not supported")
+    if not text:
+        raise UnsupportedLatexError("empty LaTeX input")
+    tokens = _LatexLexer(text).tokens
+    return _LatexParser(tokens).parse()
+
+
+def estimate_equation_size(script: str, *, base_unit: int = 1100) -> tuple[int, int]:
+    """Heuristic ``(width, height)`` in HWPUNIT for ``<hp:sz>``.
+
+    Hancom re-measures the shape when the document is opened (P0 evidence:
+    a fixed size rendered correctly), so this only needs to be a sane
+    placeholder, mirroring the gold documents' proportions.
+    """
+
+    visible = len(script.replace("{", "").replace("}", "").replace(" ", ""))
+    rows = 1 + script.count("#")
+    tall = any(word in script for word in ("over", "sqrt", "int", "sum", "prod", "lim"))
+    width = int(base_unit * 0.45 * max(6, visible))
+    height = int(base_unit * (2.5 if tall else 1.6) * max(1, rows))
+    return width, height
+
+
+__all__ = [
+    "UnsupportedLatexError",
+    "estimate_equation_size",
+    "latex_to_eqedit",
+]

hwpx/equation/tokens.py

@@ -102,6 +102,9 @@ OPERATORS: dict[str, str] = {
     "cap": r"\cap",
     "emptyset": r"\emptyset",
     "forall": r"\forall",
+    # Real-Hancom EqEdit spells ∀ in ALLCAPS; lowercase renders as literal text
+    # (render-verified 2026-07-31, specs/054 P2 token battery R05).
+    "FORALL": r"\forall",
     "exists": r"\exists",
     "neg": r"\neg",
     "land": r"\land",
@@ -176,6 +179,11 @@ BIG_OPERATORS: dict[str, str] = {
     "int": r"\int",
     "iint": r"\iint",
     "iiint": r"\iiint",
+    # Real-Hancom EqEdit spellings for ∬/∭ (render-verified 2026-07-31,
+    # specs/054 P2 token battery R06/R07; ``iint``/``iiint`` render as
+    # literal text on the real build).
+    "dint": r"\iint",
+    "tint": r"\iiint",
     "oint": r"\oint",
     "sum": r"\sum",
     "prod": r"\prod",
@@ -213,6 +221,10 @@ MATRIX_ENVIRONMENTS: dict[str, str] = {
     "Bmatrix": "Bmatrix",
     "vmatrix": "vmatrix",
     "Vmatrix": "Vmatrix",
+    # Real-Hancom EqEdit determinant matrix |...| (render-verified 2026-07-31,
+    # specs/054 P2 token battery R12; ``vmatrix``/``Vmatrix`` render as
+    # literal text on the real build).
+    "dmatrix": "vmatrix",
     "cases": "cases",
 }
 

hwpx/experimental.py

@@ -13,6 +13,11 @@
 
 from __future__ import annotations
 
+from .equation.authoring import (
+    UnsupportedLatexError,
+    estimate_equation_size,
+    latex_to_eqedit,
+)
 from .ingest import (
     ConversionAttempt,
     DocumentConverter,
@@ -45,4 +50,7 @@ __all__ = [
     "render_layout_preview",
     "DocumentViewer",
     "render_document_viewer",
+    "UnsupportedLatexError",
+    "estimate_equation_size",
+    "latex_to_eqedit",
 ]

hwpx/oxml/paragraph.py

@@ -834,6 +834,164 @@ class HwpxOxmlParagraph:
         self.section.mark_dirty()
         return HwpxOxmlInlineObject(ctrl1, self)
 
+    def add_chart(
+        self,
+        chart_id_ref: str,
+        *,
+        size: tuple[int, int] | None = None,
+        treat_as_char: bool = False,
+        char_pr_id_ref: str | int | None = None,
+        run_attributes: dict[str, str] | None = None,
+    ) -> HwpxOxmlInlineObject:
+        """Insert a native ``<hp:chart>`` anchor referencing a chartML part.
+
+        Emits the real-Hancom chart anchor (contract reverse-engineered in
+        specs/055-chart-authoring/evidence/p0/chart-contract.md): the chart
+        content lives in an ECMA-376 chartML part addressed directly by
+        ``chartIDRef`` (real Hancom registers the part in no manifest), and
+        Hancom lays the chart out from the chartML alone — no OLE fallback or
+        pre-rendered image is required.
+
+        Args:
+            chart_id_ref: Package path of the chartML part
+                (e.g. ``Chart/chart1.xml``).
+            size: Optional ``(width, height)`` HWPUNIT pair for ``<hp:sz>``;
+                defaults to the gold document's 32250x18750.
+            treat_as_char: ``True`` places the chart inline in the text flow;
+                the default mirrors the gold float placement.
+        """
+        reference = chart_id_ref.strip()
+        if not reference:
+            raise ValueError("chart_id_ref must be a non-empty package path")
+        width, height = size if size is not None else (32250, 18750)
+        run = self._create_run_for_object(
+            run_attributes, char_pr_id_ref=char_pr_id_ref
+        )
+        chart = _append_child(run, f"{_HP}chart", {
+            "id": _object_id(),
+            "zOrder": "0",
+            "numberingType": "PICTURE",
+            "textWrap": "TOP_AND_BOTTOM" if treat_as_char else "SQUARE",
+            "textFlow": "BOTH_SIDES",
+            "lock": "0",
+            "dropcapstyle": "None",
+            "chartIDRef": reference,
+        })
+        _append_child(chart, f"{_HP}sz", {
+            "width": str(width),
+            "widthRelTo": "ABSOLUTE",
+            "height": str(height),
+            "heightRelTo": "ABSOLUTE",
+            "protect": "0",
+        })
+        _append_child(chart, f"{_HP}pos", {
+            "treatAsChar": "1" if treat_as_char else "0",
+            "affectLSpacing": "0",
+            "flowWithText": "1",
+            "allowOverlap": "0",
+            "holdAnchorAndSO": "0",
+            "vertRelTo": "PARA",
+            "horzRelTo": "PARA" if treat_as_char else "COLUMN",
+            "vertAlign": "TOP",
+            "horzAlign": "LEFT",
+            "vertOffset": "0",
+            "horzOffset": "0",
+        })
+        _append_child(chart, f"{_HP}outMargin", {
+            "left": "0",
+            "right": "0",
+            "top": "0",
+            "bottom": "0",
+        })
+        self.section.mark_dirty()
+        return HwpxOxmlInlineObject(chart, self)
+
+    def add_equation(
+        self,
+        script: str,
+        *,
+        base_unit: int = 1100,
+        size: tuple[int, int] | None = None,
+        char_pr_id_ref: str | int | None = None,
+        run_attributes: dict[str, str] | None = None,
+    ) -> HwpxOxmlInlineObject:
+        """Insert an inline ``<hp:equation>`` carrying an EqEdit *script*.
+
+        Emits the real-Hancom equation shape (contract reverse-engineered in
+        specs/054-equation-authoring/evidence/p0/equation-contract.md): the
+        EqEdit source lives in the ``<hp:script>`` child, no lineseg cache is
+        written (Hancom re-lays-out on open), and the shape is inline
+        (``treatAsChar="1"``) so it renders in the page flow.
+
+        Args:
+            script: EqEdit script stored verbatim (e.g. ``{a} over {b}``).
+            base_unit: Equation base font size in 1/100 pt (gold: 1100/1200).
+            size: Optional explicit ``(width, height)`` HWPUNIT pair for
+                ``<hp:sz>``; when omitted a proportional placeholder is
+                written — Hancom re-measures on open (P0 evidence).
+        """
+        text = script.strip()
+        if not text:
+            raise ValueError("equation script must be a non-empty string")
+        if base_unit <= 0:
+            raise ValueError("base_unit must be positive")
+        if size is None:
+            visible = len(text.replace("{", "").replace("}", "").replace(" ", ""))
+            width = int(base_unit * 0.45 * max(6, visible))
+            height = int(base_unit * 2.5)
+        else:
+            width, height = size
+        run = self._create_run_for_object(
+            run_attributes, char_pr_id_ref=char_pr_id_ref
+        )
+        equation = _append_child(run, f"{_HP}equation", {
+            "id": _object_id(),
+            "zOrder": "0",
+            "numberingType": "EQUATION",
+            "textWrap": "TOP_AND_BOTTOM",
+            "textFlow": "BOTH_SIDES",
+            "lock": "0",
+            "dropcapstyle": "None",
+            "version": "Equation Version 60",
+            "baseLine": str(max(1, round(base_unit * 69 / 1200))),
+            "textColor": "#000000",
+            "baseUnit": str(base_unit),
+            "lineMode": "CHAR",
+            "font": "HYhwpEQ",
+        })
+        _append_child(equation, f"{_HP}sz", {
+            "width": str(width),
+            "widthRelTo": "ABSOLUTE",
+            "height": str(height),
+            "heightRelTo": "ABSOLUTE",
+            "protect": "0",
+        })
+        _append_child(equation, f"{_HP}pos", {
+            "treatAsChar": "1",
+            "affectLSpacing": "0",
+            "flowWithText": "1",
+            "allowOverlap": "0",
+            "holdAnchorAndSO": "0",
+            "vertRelTo": "PARA",
+            "horzRelTo": "PARA",
+            "vertAlign": "TOP",
+            "horzAlign": "LEFT",
+            "vertOffset": "0",
+            "horzOffset": "0",
+        })
+        _append_child(equation, f"{_HP}outMargin", {
+            "left": "56",
+            "right": "56",
+            "top": "0",
+            "bottom": "0",
+        })
+        comment = _append_child(equation, f"{_HP}shapeComment", {})
+        comment.text = "수식입니다."
+        script_element = _append_child(equation, f"{_HP}script", {})
+        script_element.text = text
+        self.section.mark_dirty()
+        return HwpxOxmlInlineObject(equation, self)
+
     def add_form_field(
         self,
         name: str,

{python_hwpx-5.1.1.dist-info → python_hwpx-5.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 5.1.1
+Version: 5.3.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0

{python_hwpx-5.1.1.dist-info → python_hwpx-5.3.0.dist-info}/RECORD

@@ -1,8 +1,8 @@
-hwpx/__init__.py,sha256=C63jP28R_TnVNTQifvWgOXwKg273JUpLwAa-8Z0B4dQ,15706
+hwpx/__init__.py,sha256=WmlWHk6vfjr2HQa6Dzp6rmIXIUJXKWKDZJZ-LBpL3Nc,15936
 hwpx/body_patch.py,sha256=XfwrTMThS9vPLA62PDnEleCGuvYv61URxelbD_LHe8w,25730
-hwpx/document.py,sha256=fjFEO12_bBnDLHmAwD-CfHNYWbnvK0jHdWWthhtpEl4,62237
+hwpx/document.py,sha256=ly12zmjR96_4itGwJw9xljDI3sowmrSsZZfHHn4Znio,65995
 hwpx/errors.py,sha256=l3QK2Izwkpm25ar7QnNQvyg0yosoLfQt7kW5wn5MCG0,3033
-hwpx/experimental.py,sha256=H8fBrmGf0BzoDS6dqwBpUChUestUgOpO7XjMEBXsssg,1499
+hwpx/experimental.py,sha256=BfD3fvXDgiEEm8G66TuUe_OPETitGwFU0VurUXUuV9Q,1693
 hwpx/mutation_report.py,sha256=6hurhDdgGiONeLIeWZJT8lwLtWJZ1VHp1l6G0zy0mQo,19409
 hwpx/package.py,sha256=0rKjGCJbPQvrVBIy07Jpjsu3fI7HhbqFCGWTiTDsJpo,1141
 hwpx/patch.py,sha256=J4RrVr5s3pW9hN5EKYvUytXI_4f7NEdxV5oUsIdZkgw,25546
@@ -16,14 +16,15 @@ hwpx/_document/layout.py,sha256=TicBhdxXW2lQkLyG5bg6PHW-OP-X4oWdP6XAgAXw8mg,2308
 hwpx/_document/media.py,sha256=kamsFJZ4K9aoKhjyztMHC64MVFR_ZQ50rDVgouZqxFA,11592
 hwpx/_document/memos.py,sha256=_tscEhNfPe9-iAkcEtJGjwHTN42_lx4stFoPrgJxk3o,7481
 hwpx/_document/persistence.py,sha256=NgWeFmm6jWV11194kdx32lwRQ6dyqiQYnc1ZBzJcIbE,16003
-hwpx/_document/shapes.py,sha256=UpPNEdfOlrEKMD5TahemQBHPOm6qgnHFxjZGEZ27xUk,6684
+hwpx/_document/shapes.py,sha256=NC3eaA4H2cXDdTi3REMaSZifXqwpChAhS4LPGCSDUc0,11702
 hwpx/_document/tracked.py,sha256=1sQ9Q3-_wOAH2SQPbJQAeCG9E9HjV3y1gCORzrPUEPo,5010
 hwpx/data/Skeleton.hwpx,sha256=yR-3epkzo-VkWiV3ji0rmemBN-2ZVypdHdKe8MD9TJg,7490
-hwpx/equation/__init__.py,sha256=t012hR5Tc07DiC_niYtUpE4WI5-2zNVUuwRRVn2QfXw,1118
+hwpx/equation/__init__.py,sha256=0wks0_pS_tBokCVMeWUJGE6tbW35Ptc0I5Z_36FY-Jo,1328
+hwpx/equation/authoring.py,sha256=s8wJWNEEFJ2oS4xbs4-Hyv7Dlml_mSQrljdy0hbzpjU,16786
 hwpx/equation/eqedit.py,sha256=FjRNwc_JVC01yprqLFk5N6Nm5qCow2K2x-u3Dw7Wmio,11314
 hwpx/equation/mathml.py,sha256=mbmAojF-4e9cMEQQvgHx5wvp_dG3Mb_sPjqH7SpOaxQ,2150
 hwpx/equation/render.py,sha256=g698YmVWsfG4V-QNROXmSK0za-npJ4Z7xIe6Y5DZ1g0,2874
-hwpx/equation/tokens.py,sha256=9HJZrZAIc9CM-GsZv_SNrqyr7JPVKC4hvVw6jEJPESE,6474
+hwpx/equation/tokens.py,sha256=RyFyqj3rMllFB5k4d2XO2L8CkiIySb573evJ-fwujhY,7097
 hwpx/form_fit/__init__.py,sha256=l1HcFge4u_wL2vogB-VxSMrb-8h7zUT_IgTWMtnH9CM,1779
 hwpx/form_fit/apply.py,sha256=X2q7K-mLku4AXxm4-xP80QGzhBlpzpqA_Ade8aPXzNY,3450
 hwpx/form_fit/engine.py,sha256=2W5ePGnpaLDoVPH8RxKdRfVx3r3usy26RBWj0jU1fpE,21553
@@ -55,7 +56,7 @@ hwpx/oxml/memo.py,sha256=QlmuELEzywnmywgjm94S3vzJB8wPpoFOmI8KVuzoNPw,9484
 hwpx/oxml/namespaces.py,sha256=c7JfdOdJbzrhyHvjbxoeeeloRE3xPuoB7v3YI8SmKDk,6524
 hwpx/oxml/numbering.py,sha256=9a0ARGW1DkKsTF7mEEXM4FA5loQmzIBuqE4APA8UFIQ,669
 hwpx/oxml/objects.py,sha256=8ErDXWvkjLm3FTsx0Z_IovUXbiv2uc-j0B5Y2-OtihA,20864
-hwpx/oxml/paragraph.py,sha256=tjsPttiYAu0d92C3O78pt-7h9gJa1cPRs9qP7iY-6wQ,40865
+hwpx/oxml/paragraph.py,sha256=p9M22WLPt3_mjmQZGrpSS9agRDKAXwSvnKJGnCUgc48,47075
 hwpx/oxml/parser.py,sha256=pIfyNdW3WdFkCcE8JFY7hn1fobRbMngzfhVZICvWeVs,2937
 hwpx/oxml/run.py,sha256=F939J1W6zQjr-JQ1Z8-nKh2s7NQ_0Okov4QJAEyw_5M,15503
 hwpx/oxml/schema.py,sha256=ElR3_IIhhPPZEqJtNKMNCHA-VFVLdhL454W_4spuvlc,1284
@@ -103,10 +104,10 @@ hwpx/tools/toc_fidelity.py,sha256=rvoKH8QJ65WNVrxS0d-i2AtODvBy-4O8NRudfQ244v4,19
 hwpx/tools/validator.py,sha256=U856izL9NcJZOiKDYoCpwOSaFNQ2Un8Jn4pzL20A96Q,7100
 hwpx/tools/_schemas/header.xsd,sha256=mJXuFMuHGT1JnFFaluUpYUglwjMCNlfbFCRVM26eHXE,664
 hwpx/tools/_schemas/section.xsd,sha256=MgvavVHG05RDfUnVPxVU10H4FQOja5ON04_m9Uk_m7E,522
-python_hwpx-5.1.1.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-5.1.1.dist-info/licenses/NOTICE,sha256=KJgtwIIzrXoA0j3PUhwp78ZtnucocEoB7jiuwoL4i7o,3060
-python_hwpx-5.1.1.dist-info/METADATA,sha256=K_jKvQjMhwByWju_P3C9_TIyGyqJQVTvGfns4Y2viPI,13162
-python_hwpx-5.1.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_hwpx-5.1.1.dist-info/entry_points.txt,sha256=JUKRxbly9UaeHV7YzOea23y8IiqSTcrhUlooP3fS_Zc,405
-python_hwpx-5.1.1.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-5.1.1.dist-info/RECORD,,
+python_hwpx-5.3.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
+python_hwpx-5.3.0.dist-info/licenses/NOTICE,sha256=auRgKYGdrOgWrj4kZfAuXQnqgDnx5myI9TI17IztIzQ,3466
+python_hwpx-5.3.0.dist-info/METADATA,sha256=ve8a6QxqNSMJ6H-PbMfQOS6OpFREBe8Xfe1jEWER33U,13162
+python_hwpx-5.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_hwpx-5.3.0.dist-info/entry_points.txt,sha256=JUKRxbly9UaeHV7YzOea23y8IiqSTcrhUlooP3fS_Zc,405
+python_hwpx-5.3.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-5.3.0.dist-info/RECORD,,

{python_hwpx-5.1.1.dist-info → python_hwpx-5.3.0.dist-info}/licenses/NOTICE

@@ -30,9 +30,15 @@ reimplemented from public references, without copying source code:
   structure and roundtrip fixtures.
 
 - OpenBapul/hml-equation-parser (Apache-2.0): HULK-style EqEdit <-> LaTeX token
-  mapping, referenced for reader-direction <hp:equation> script rendering. The
-  token maps are a clean-room re-derivation from the public EqEdit grammar; no
-  source code was copied, translated, or vendored.
+  mapping, referenced for reader-direction <hp:equation> script rendering and
+  for the authoring-direction LaTeX -> EqEdit conversion. The token maps are a
+  clean-room re-derivation from the public EqEdit grammar; no source code was
+  copied, translated, or vendored.
+- chrisryugj/kordoc (MIT): the authoring-direction approach for native
+  <hp:equation> generation — the XML shell contract, reserved-word quoting,
+  and untrusted-input guards (source-size and recursion-depth caps) were
+  referenced as behavior evidence. Clean-room Python implementation; no source
+  code was copied, translated, or vendored.
 
 These form-fill and equation references were used as behavior evidence only. The
 implementation is a clean-room Python implementation; no source code was