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

{python_hwpx-5.2.0/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.2.0
+Version: 5.3.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0

{python_hwpx-5.2.0 → python_hwpx-5.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "5.2.0"
+version = "5.3.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"

{python_hwpx-5.2.0 → python_hwpx-5.3.0}/src/hwpx/_document/shapes.py

@@ -282,3 +282,78 @@ def add_equation(
     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.2.0 → python_hwpx-5.3.0}/src/hwpx/document.py

@@ -1431,6 +1431,48 @@ 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,

{python_hwpx-5.2.0 → python_hwpx-5.3.0}/src/hwpx/oxml/paragraph.py

@@ -834,6 +834,78 @@ 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,

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

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

{python_hwpx-5.2.0 → python_hwpx-5.3.0}/src/python_hwpx.egg-info/SOURCES.txt

@@ -120,6 +120,7 @@ tests/test_authoring_quality_corpus.py
 tests/test_blind_eval_fixture.py
 tests/test_byte_patch_identity.py
 tests/test_cell_line_spacing.py
+tests/test_chart_authoring.py
 tests/test_comment_node_robustness.py
 tests/test_corpus_read_fidelity.py
 tests/test_coverage_promotion.py

python_hwpx-5.3.0/tests/test_chart_authoring.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import io
+import zipfile
+from pathlib import Path
+
+from hwpx import HwpxDocument
+from hwpx.tools.package_validator import validate_editor_open_safety
+
+import pytest
+
+HP = "{http://www.hancom.co.kr/hwpml/2011/paragraph}"
+FIXTURES = Path(__file__).parent / "fixtures"
+GOLD_HANCOM = FIXTURES / "hwpxlib_corpus" / "error__20230426__HwpxTest1.hwpx"
+
+CHART_HEAD = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>'
+    '<c:chartSpace xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" '
+    'xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" '
+    'xmlns:c="http://schemas.openxmlformats.org/drawingml/2006/chart">'
+    "<c:chart><c:plotArea><c:layout/>"
+)
+PIE_CHARTML = (
+    CHART_HEAD
+    + '<c:pieChart><c:varyColors val="1"/><c:ser><c:idx val="0"/><c:order val="0"/>'
+    '<c:cat><c:strRef><c:f>Sheet1!$A$2:$A$3</c:f><c:strCache><c:ptCount val="2"/>'
+    '<c:pt idx="0"><c:v>A</c:v></c:pt><c:pt idx="1"><c:v>B</c:v></c:pt></c:strCache></c:strRef></c:cat>'
+    '<c:val><c:numRef><c:f>Sheet1!$B$2:$B$3</c:f><c:numCache><c:formatCode>General</c:formatCode>'
+    '<c:ptCount val="2"/><c:pt idx="0"><c:v>60</c:v></c:pt><c:pt idx="1"><c:v>40</c:v></c:pt>'
+    "</c:numCache></c:numRef></c:val></c:ser></c:pieChart>"
+    "</c:plotArea></c:chart></c:chartSpace>"
+)
+
+
+def _roundtrip(doc: HwpxDocument) -> tuple[HwpxDocument, bytes]:
+    buffer = io.BytesIO()
+    doc.save_to_stream(buffer)
+    payload = buffer.getvalue()
+    return HwpxDocument.open(io.BytesIO(payload)), payload
+
+
+def _anchors(doc: HwpxDocument):
+    found = []
+    for section in doc.sections:
+        found.extend(section.element.iter(f"{HP}chart"))
+    return found
+
+
+class TestGoldContractShape:
+    """The emitted anchor must match the real-Hancom chart contract
+    (specs/055-chart-authoring/evidence/p0/chart-contract.md)."""
+
+    def test_anchor_attributes_and_part(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_chart(PIE_CHARTML)
+        (anchor,) = _anchors(doc)
+        assert anchor.get("chartIDRef") == "Chart/chart1.xml"
+        assert anchor.get("numberingType") == "PICTURE"
+        assert anchor.get("textWrap") == "SQUARE"
+        assert anchor.get("id")
+        local_names = [child.tag.rsplit("}", 1)[-1] for child in anchor]
+        assert local_names == ["sz", "pos", "outMargin"]
+        assert anchor.find(f"{HP}pos").get("treatAsChar") == "0"
+
+    def test_part_written_verbatim_and_unregistered(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_chart(PIE_CHARTML)
+        _reopened, payload = _roundtrip(doc)
+        with zipfile.ZipFile(io.BytesIO(payload)) as package:
+            assert package.read("Chart/chart1.xml") == PIE_CHARTML.encode("utf-8")
+            hpf = package.read("Contents/content.hpf").decode("utf-8")
+        # Real Hancom registers chart parts in no manifest (gold contract).
+        assert "chart1" not in hpf
+
+    def test_part_paths_allocate_sequentially(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_chart(PIE_CHARTML)
+        doc.add_chart(PIE_CHARTML)
+        refs = [anchor.get("chartIDRef") for anchor in _anchors(doc)]
+        assert refs == ["Chart/chart1.xml", "Chart/chart2.xml"]
+
+    def test_inline_placement(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_chart(PIE_CHARTML, treat_as_char=True, size=(20000, 12000))
+        (anchor,) = _anchors(doc)
+        assert anchor.get("textWrap") == "TOP_AND_BOTTOM"
+        pos = anchor.find(f"{HP}pos")
+        assert pos.get("treatAsChar") == "1"
+        sz = anchor.find(f"{HP}sz")
+        assert (sz.get("width"), sz.get("height")) == ("20000", "12000")
+
+
+class TestSelfRoundtrip:
+    def test_reopen_keeps_anchor_and_part_bytes(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_chart(PIE_CHARTML)
+        reopened, _payload = _roundtrip(doc)
+        (anchor,) = _anchors(reopened)
+        assert anchor.get("chartIDRef") == "Chart/chart1.xml"
+        # patch-grade resave must keep the chart part byte-identical
+        _again, payload2 = _roundtrip(reopened)
+        with zipfile.ZipFile(io.BytesIO(payload2)) as package:
+            assert package.read("Chart/chart1.xml") == PIE_CHARTML.encode("utf-8")
+
+    def test_chart_in_table_cell(self) -> None:
+        doc = HwpxDocument.new()
+        table = doc.add_table(2, 2)
+        cell_paragraph = table.cell(0, 0).paragraphs[0]
+        doc.add_chart(PIE_CHARTML, paragraph=cell_paragraph)
+        reopened, _payload = _roundtrip(doc)
+        (anchor,) = _anchors(reopened)
+        ancestors = []
+        parent = anchor.getparent()
+        while parent is not None:
+            ancestors.append(parent.tag.rsplit("}", 1)[-1])
+            parent = parent.getparent()
+        assert "tc" in ancestors
+
+    def test_byte_preservation_of_unrelated_parts(self) -> None:
+        doc = HwpxDocument.open(GOLD_HANCOM)
+        with zipfile.ZipFile(GOLD_HANCOM) as package:
+            before = {name: package.read(name) for name in package.namelist()}
+        doc.add_chart(PIE_CHARTML)
+        buffer = io.BytesIO()
+        doc.save_to_stream(buffer)
+        with zipfile.ZipFile(io.BytesIO(buffer.getvalue())) as package:
+            after = {name: package.read(name) for name in package.namelist()}
+        changed = {
+            name for name in before if name in after and before[name] != after[name]
+        }
+        assert changed <= {"Contents/section0.xml"}
+        # The gold file already carries Chart/chart1.xml — ours must not clobber it.
+        assert after["Chart/chart1.xml"] == before["Chart/chart1.xml"]
+        assert _anchors(HwpxDocument.open(io.BytesIO(buffer.getvalue())))[-1].get(
+            "chartIDRef"
+        ) == "Chart/chart2.xml"
+
+    def test_open_safety(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_chart(PIE_CHARTML)
+        buffer = io.BytesIO()
+        doc.save_to_stream(buffer)
+        report = validate_editor_open_safety(buffer.getvalue())
+        assert report.ok, report
+
+    def test_gold_fixture_anchor_still_reads(self) -> None:
+        doc = HwpxDocument.open(GOLD_HANCOM)
+        anchors = _anchors(doc)
+        assert anchors
+        assert anchors[0].get("chartIDRef") == "Chart/chart1.xml"
+
+
+class TestValidation:
+    def test_empty_chartml_rejected(self) -> None:
+        doc = HwpxDocument.new()
+        with pytest.raises(ValueError):
+            doc.add_chart("   ")
+
+    def test_malformed_xml_rejected_before_any_write(self) -> None:
+        doc = HwpxDocument.new()
+        with pytest.raises(ValueError):
+            doc.add_chart("<c:chartSpace")
+        assert _anchors(doc) == []
+        buffer = io.BytesIO()
+        doc.save_to_stream(buffer)
+        with zipfile.ZipFile(io.BytesIO(buffer.getvalue())) as package:
+            assert not [n for n in package.namelist() if n.startswith("Chart/")]
+
+    def test_wrong_root_rejected(self) -> None:
+        doc = HwpxDocument.new()
+        with pytest.raises(ValueError, match="chartSpace"):
+            doc.add_chart("<not-a-chart/>")