python-hwpx 5.1.1__tar.gz → 5.3.0__tar.gz

{python_hwpx-5.1.1 → python_hwpx-5.3.0}/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

{python_hwpx-5.1.1/src/python_hwpx.egg-info → python_hwpx-5.3.0}/PKG-INFO

@@ -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 → python_hwpx-5.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "5.1.1"
+version = "5.3.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -148,6 +148,7 @@ files = [
     "src/hwpx/equation/__init__.py",
     "src/hwpx/equation/tokens.py",
     "src/hwpx/equation/eqedit.py",
+    "src/hwpx/equation/authoring.py",
     "src/hwpx/equation/mathml.py",
     "src/hwpx/equation/render.py",
     "src/hwpx/tools/document_viewer.py",
@@ -202,6 +203,7 @@ include = [
     "src/hwpx/equation/__init__.py",
     "src/hwpx/equation/tokens.py",
     "src/hwpx/equation/eqedit.py",
+    "src/hwpx/equation/authoring.py",
     "src/hwpx/equation/mathml.py",
     "src/hwpx/equation/render.py",
     "src/hwpx/tools/document_viewer.py",

{python_hwpx-5.1.1 → python_hwpx-5.3.0}/src/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

{python_hwpx-5.1.1 → python_hwpx-5.3.0}/src/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"
+    )

{python_hwpx-5.1.1 → python_hwpx-5.3.0}/src/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,
         *,

{python_hwpx-5.1.1 → python_hwpx-5.3.0}/src/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",
 ]