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

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"
+    )

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,

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.dist-info → python_hwpx-5.3.0.dist-info}/METADATA

@@ -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.dist-info → python_hwpx-5.3.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 hwpx/__init__.py,sha256=WmlWHk6vfjr2HQa6Dzp6rmIXIUJXKWKDZJZ-LBpL3Nc,15936
 hwpx/body_patch.py,sha256=XfwrTMThS9vPLA62PDnEleCGuvYv61URxelbD_LHe8w,25730
-hwpx/document.py,sha256=3N90Ra8krX4Skj5WUTDl4ezHf1q0yaBQCKqficnR1p8,64169
+hwpx/document.py,sha256=ly12zmjR96_4itGwJw9xljDI3sowmrSsZZfHHn4Znio,65995
 hwpx/errors.py,sha256=l3QK2Izwkpm25ar7QnNQvyg0yosoLfQt7kW5wn5MCG0,3033
 hwpx/experimental.py,sha256=BfD3fvXDgiEEm8G66TuUe_OPETitGwFU0VurUXUuV9Q,1693
 hwpx/mutation_report.py,sha256=6hurhDdgGiONeLIeWZJT8lwLtWJZ1VHp1l6G0zy0mQo,19409
@@ -16,7 +16,7 @@ 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=XoCp41A6AmemOv9tGSMXRyu7sE7SMVBSzXSZfkelKWA,8825
+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=0wks0_pS_tBokCVMeWUJGE6tbW35Ptc0I5Z_36FY-Jo,1328
@@ -56,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=U-bGkgMs3wiEBE1TXW6jSJj0SYwzN9xtWeOyOhLLJt0,44238
+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
@@ -104,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.2.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-5.2.0.dist-info/licenses/NOTICE,sha256=auRgKYGdrOgWrj4kZfAuXQnqgDnx5myI9TI17IztIzQ,3466
-python_hwpx-5.2.0.dist-info/METADATA,sha256=dTDpJNzdORyUZnVj8fANpARJ74j3QOekvJ9Mu_O5mYc,13162
-python_hwpx-5.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_hwpx-5.2.0.dist-info/entry_points.txt,sha256=JUKRxbly9UaeHV7YzOea23y8IiqSTcrhUlooP3fS_Zc,405
-python_hwpx-5.2.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-5.2.0.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,,