python-hwpx 5.4.0__tar.gz → 5.5.0__tar.gz

{python_hwpx-5.4.0/src/python_hwpx.egg-info → python_hwpx-5.5.0}/PKG-INFO

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

{python_hwpx-5.4.0 → python_hwpx-5.5.0}/pyproject.toml

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

{python_hwpx-5.4.0 → python_hwpx-5.5.0}/src/hwpx/oxml/memo.py

@@ -14,7 +14,6 @@ from ._document_primitives import (
     _default_sublist_attributes,
     _element_local_name,
     _memo_id,
-    _paragraph_id,
     _sanitize_text,
 )
 
@@ -213,14 +212,35 @@ class HwpxOxmlNote:
 
     @text.setter
     def text(self, value: str) -> None:
-        """Replace the note body text."""
+        """Replace the note body text.
+
+        The gold-shaped body (각주/미주 style paragraph with the leading
+        ``<hp:autoNum>`` control real Hancom requires to render the note) is
+        preserved: only text content is replaced.
+        """
         sublist = self.element.find(f"{_HP}subList")
         if sublist is None:
-            sublist = _append_child(self.element, f"{_HP}subList", _default_sublist_attributes())
-        for p in sublist.findall(f"{_HP}p"):
+            attrs = _default_sublist_attributes()
+            attrs["vertAlign"] = "TOP"
+            sublist = _append_child(self.element, f"{_HP}subList", attrs)
+        paragraphs = sublist.findall(f"{_HP}p")
+        template = paragraphs[0] if paragraphs else None
+        p_attrs = (
+            dict(template.attrib)
+            if template is not None
+            else {"id": "0", **_DEFAULT_PARAGRAPH_ATTRS}
+        )
+        first_run = template.find(f"{_HP}run") if template is not None else None
+        run_attrs = dict(first_run.attrib) if first_run is not None else {"charPrIDRef": "0"}
+        auto_num = (
+            first_run.find(f"{_HP}ctrl") if first_run is not None else None
+        )
+        for p in paragraphs:
             sublist.remove(p)
-        paragraph = _append_child(sublist, f"{_HP}p", {"id": _paragraph_id(), **_DEFAULT_PARAGRAPH_ATTRS})
-        run = _append_child(paragraph, f"{_HP}run", {"charPrIDRef": "0"})
+        paragraph = _append_child(sublist, f"{_HP}p", p_attrs)
+        run = _append_child(paragraph, f"{_HP}run", run_attrs)
+        if auto_num is not None:
+            run.append(auto_num)
         t = _append_child(run, f"{_HP}t", {})
         t.text = _sanitize_text(value)
         self.paragraph.section.mark_dirty()

{python_hwpx-5.4.0 → python_hwpx-5.5.0}/src/hwpx/oxml/paragraph.py

@@ -23,7 +23,6 @@ from ._document_primitives import (
     _default_sublist_attributes,
     _is_tab_control_element,
     _object_id,
-    _paragraph_id,
     _sanitize_text,
 )
 from .memo import HwpxOxmlNote
@@ -1183,6 +1182,61 @@ class HwpxOxmlParagraph:
     # Footnote / Endnote helpers
     # ------------------------------------------------------------------
 
+    _NOTE_STYLE_NAMES = {"footNote": ("각주", "Footnote"), "endNote": ("미주", "Endnote")}
+    _NOTE_STYLE_FALLBACK = {"footNote": ("15", "10", "3"), "endNote": ("16", "10", "3")}
+
+    def _note_style_refs(self, tag: str) -> tuple[str, str, str]:
+        """(styleIDRef, paraPrIDRef, charPrIDRef) for the note body paragraph.
+
+        Real Hancom puts note bodies on the 각주/미주 paragraph styles. Resolve
+        by style name from the header so documents with re-numbered styles stay
+        correct; fall back to the fixed template coordinates.
+        """
+
+        korean, english = self._NOTE_STYLE_NAMES[tag]
+        document = self.section.document
+        headers = cast(
+            "Sequence[object]",
+            getattr(document, "_headers", []) if document is not None else [],
+        )
+        for header in headers:
+            styles = getattr(header, "_styles_element", None)
+            container = cast(
+                "ET.Element | None", styles() if callable(styles) else None
+            )
+            if container is None:
+                continue
+            for style in container:
+                if style.get("name") == korean or style.get("engName") == english:
+                    return (
+                        style.get("id") or self._NOTE_STYLE_FALLBACK[tag][0],
+                        style.get("paraPrIDRef") or self._NOTE_STYLE_FALLBACK[tag][1],
+                        style.get("charPrIDRef") or self._NOTE_STYLE_FALLBACK[tag][2],
+                    )
+        return self._NOTE_STYLE_FALLBACK[tag]
+
+    def _note_suffix_char(self, tag: str) -> str:
+        """The note suffix character from secPr, defaulting to ")"."""
+
+        properties = self.section._section_properties_element()
+        if properties is not None:
+            pr = properties.find(f"{_HP}{tag}Pr")
+            if pr is not None:
+                fmt = pr.find(f"{_HP}autoNumFormat")
+                if fmt is not None and fmt.get("suffixChar"):
+                    return fmt.get("suffixChar", ")")
+        return ")"
+
+    def _next_note_number(self, tag: str) -> int:
+        """Document-continuous note number, counted per note type."""
+
+        document = self.section.document
+        sections = document.sections if document is not None else [self.section]
+        count = 0
+        for section in sections:
+            count += sum(1 for _ in section.element.iter(f"{_HP}{tag}"))
+        return count + 1
+
     def _add_note(
         self,
         tag: str,
@@ -1191,17 +1245,54 @@ class HwpxOxmlParagraph:
         run_attributes: dict[str, str] | None = None,
         char_pr_id_ref: str | int | None = None,
     ) -> HwpxOxmlNote:
-        """Insert a ``<hp:footNote>`` or ``<hp:endNote>`` element."""
+        """Insert a ``<hp:footNote>`` or ``<hp:endNote>`` element.
 
-        run = self._create_run_for_object(run_attributes, char_pr_id_ref=char_pr_id_ref)
-        note_element = _append_child(run, f"{_HP}{tag}", {"instId": _object_id()})
-        sublist = _append_child(note_element, f"{_HP}subList", _default_sublist_attributes())
-        p_attrs = {"id": _paragraph_id(), **_DEFAULT_PARAGRAPH_ATTRS}
+        Emits the real-Hancom shape (gold-reversed): the note element is
+        wrapped in ``<hp:ctrl>`` inside a body run, carries ``number`` and
+        ``suffixChar``, and its body paragraph uses the 각주/미주 style with a
+        leading ``<hp:autoNum>`` control — without these real Hancom does not
+        render the note at all.
+        """
+
+        number = self._next_note_number(tag)
+        suffix = self._note_suffix_char(tag)
+        style_ref, para_pr_ref, note_char_ref = self._note_style_refs(tag)
+        if char_pr_id_ref is not None:
+            note_char_ref = str(char_pr_id_ref)
+
+        runs = self._run_elements()
+        if run_attributes is None and runs:
+            run = runs[-1]
+        else:
+            run = self._create_run_for_object(run_attributes, char_pr_id_ref=char_pr_id_ref)
+        ctrl = _append_child(run, f"{_HP}ctrl", {})
+        note_element = _append_child(
+            ctrl,
+            f"{_HP}{tag}",
+            {
+                "number": str(number),
+                "suffixChar": str(ord(suffix[0])) if suffix else "41",
+                "instId": _object_id(),
+            },
+        )
+        sublist_attrs = _default_sublist_attributes()
+        sublist_attrs["vertAlign"] = "TOP"
+        sublist = _append_child(note_element, f"{_HP}subList", sublist_attrs)
+        p_attrs = dict(_DEFAULT_PARAGRAPH_ATTRS)
+        p_attrs.update({"id": "0", "paraPrIDRef": para_pr_ref, "styleIDRef": style_ref})
         paragraph = _append_child(sublist, f"{_HP}p", p_attrs)
-        # 본문 run의 charPrIDRef도 인자를 따라가도록 적용 (host run과 동일 스타일).
-        # None이면 "0"(default).
-        body_cpr = "0" if char_pr_id_ref is None else str(char_pr_id_ref)
-        note_run = _append_child(paragraph, f"{_HP}run", {"charPrIDRef": body_cpr})
+        note_run = _append_child(paragraph, f"{_HP}run", {"charPrIDRef": note_char_ref})
+        num_ctrl = _append_child(note_run, f"{_HP}ctrl", {})
+        auto_num = _append_child(
+            num_ctrl,
+            f"{_HP}autoNum",
+            {"num": str(number), "numType": "FOOTNOTE" if tag == "footNote" else "ENDNOTE"},
+        )
+        _append_child(
+            auto_num,
+            f"{_HP}autoNumFormat",
+            {"type": "DIGIT", "userChar": "", "prefixChar": "", "suffixChar": suffix, "supscript": "0"},
+        )
         t = _append_child(note_run, f"{_HP}t", {})
         t.text = _sanitize_text(text)
         self.section.mark_dirty()

{python_hwpx-5.4.0 → python_hwpx-5.5.0}/src/hwpx/tools/markdown_export.py

@@ -228,7 +228,7 @@ def _md_push_text(state: _MdParagraphState, cpr, text) -> None:
         state.items.append((cpr, text))
 
 
-def _md_handle_ctrl_child(child, state: _MdParagraphState, base_cp, chars) -> None:
+def _md_handle_ctrl_child(child, state: _MdParagraphState, base_cp, chars, doc=None, notes_out=None) -> None:
     for gc in child:
         gctag = _local_name(gc)
         if gctag == "fieldBegin" and gc.get("type") == "HYPERLINK":
@@ -236,6 +236,9 @@ def _md_handle_ctrl_child(child, state: _MdParagraphState, base_cp, chars) -> No
             state.link_url = gc.get("name", "")
         elif gctag == "fieldEnd":
             _md_flush_link(state, base_cp, chars)
+        elif gctag in ("footNote", "endNote"):
+            # 실한컴 계약: 각주/미주는 run 안 <hp:ctrl>에 래핑되어 있다.
+            _md_handle_note_child(gc, gctag, state, base_cp, chars, doc, notes_out)
 
 
 def _md_handle_note_child(
@@ -271,8 +274,9 @@ def _p_element_to_md(p_el, doc, notes_out: list | None = None) -> str:
                 if child.text:
                     _md_push_text(state, cpr, child.text)
             elif tag == "ctrl":
-                _md_handle_ctrl_child(child, state, base_cp, chars)
+                _md_handle_ctrl_child(child, state, base_cp, chars, doc, notes_out)
             elif tag in ("footNote", "endNote"):
+                # 구식(5.4 이전 자사 방출) 호환: run 직속 각주도 계속 읽는다.
                 _md_handle_note_child(child, tag, state, base_cp, chars, doc, notes_out)
 
     _md_flush_items(state, base_cp, chars)

{python_hwpx-5.4.0 → python_hwpx-5.5.0}/src/hwpx/tools/text_extractor.py

@@ -483,6 +483,20 @@ class TextExtractor:
         annotations: Optional[AnnotationOptions],
         preserve_breaks: bool,
     ) -> None:
+        # 실한컴 계약: 각주/미주는 <hp:ctrl> 래핑으로 나타난다 — annotations
+        # 유무와 무관하게 노트 분기로 위임한다(구식 run 직속도 별도 분기 유지).
+        for note_tag in ("footNote", "endNote"):
+            note = _first_child_by_local(element, note_tag)
+            if note is not None:
+                self._handle_note(
+                    note,
+                    fragments,
+                    note_tag,
+                    annotations=annotations,
+                    preserve_breaks=preserve_breaks,
+                )
+                return
+
         if annotations is None:
             return
 

{python_hwpx-5.4.0 → python_hwpx-5.5.0/src/python_hwpx.egg-info}/PKG-INFO

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

{python_hwpx-5.4.0 → python_hwpx-5.5.0}/src/python_hwpx.egg-info/SOURCES.txt

@@ -171,6 +171,7 @@ tests/test_moved_surface_hints.py
 tests/test_mutation_report.py
 tests/test_namespace_handling.py
 tests/test_new_features.py
+tests/test_note_authoring_contract.py
 tests/test_opc_package.py
 tests/test_open_safety_corpus.py
 tests/test_oxml_modularization.py

python_hwpx-5.5.0/tests/test_note_authoring_contract.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import io
+
+from hwpx import HwpxDocument
+from hwpx.tools.markdown_export import export_markdown
+
+HP = "{http://www.hancom.co.kr/hwpml/2011/paragraph}"
+
+
+def _roundtrip(doc: HwpxDocument) -> HwpxDocument:
+    buffer = io.BytesIO()
+    doc.save_to_stream(buffer)
+    buffer.seek(0)
+    return HwpxDocument.open(buffer)
+
+
+class TestGoldShapedEmission:
+    """Real-Hancom footnote contract (specs/058 gold reverse): without the
+    ctrl wrapper, autoNum, and note styles Hancom does not render notes."""
+
+    def test_note_is_ctrl_wrapped_inside_the_host_run(self) -> None:
+        doc = HwpxDocument.new()
+        para = doc.add_paragraph("본문 앵커 문장")
+        para.add_footnote("각주 본문")
+        host_run = para.element.findall(f"{HP}run")[-1]
+        ctrl = host_run.find(f"{HP}ctrl")
+        assert ctrl is not None
+        assert ctrl.find(f"{HP}footNote") is not None
+        assert host_run.find(f"{HP}footNote") is None
+
+    def test_note_numbering_is_continuous_per_type(self) -> None:
+        doc = HwpxDocument.new()
+        p1 = doc.add_paragraph("첫 문단")
+        p2 = doc.add_paragraph("둘째 문단")
+        f1 = p1.add_footnote("하나")
+        f2 = p2.add_footnote("둘")
+        e1 = p2.add_endnote("미주 하나")
+        assert f1.element.get("number") == "1"
+        assert f2.element.get("number") == "2"
+        assert e1.element.get("number") == "1"
+
+    def test_note_body_carries_style_autonum_and_suffix(self) -> None:
+        doc = HwpxDocument.new()
+        para = doc.add_paragraph("앵커")
+        note = para.add_footnote("각주 텍스트")
+        el = note.element
+        assert el.get("suffixChar") == "41"
+        sub = el.find(f"{HP}subList")
+        assert sub.get("vertAlign") == "TOP"
+        body_p = sub.find(f"{HP}p")
+        assert body_p.get("styleIDRef") == "15"
+        assert body_p.get("paraPrIDRef") == "10"
+        run = body_p.find(f"{HP}run")
+        assert run.get("charPrIDRef") == "3"
+        auto = run.find(f"{HP}ctrl/{HP}autoNum")
+        assert auto.get("numType") == "FOOTNOTE"
+        assert auto.get("num") == "1"
+        fmt = auto.find(f"{HP}autoNumFormat")
+        assert fmt.get("suffixChar") == ")"
+
+    def test_endnote_uses_endnote_style_and_numtype(self) -> None:
+        doc = HwpxDocument.new()
+        note = doc.add_paragraph("앵커").add_endnote("미주")
+        body_p = note.element.find(f"{HP}subList/{HP}p")
+        assert body_p.get("styleIDRef") == "16"
+        auto = body_p.find(f"{HP}run/{HP}ctrl/{HP}autoNum")
+        assert auto.get("numType") == "ENDNOTE"
+
+    def test_text_setter_preserves_the_gold_body(self) -> None:
+        doc = HwpxDocument.new()
+        note = doc.add_paragraph("앵커").add_footnote("원래 텍스트")
+        note.text = "고친 텍스트"
+        body_p = note.element.find(f"{HP}subList/{HP}p")
+        assert body_p.get("styleIDRef") == "15"
+        run = body_p.find(f"{HP}run")
+        assert run.find(f"{HP}ctrl/{HP}autoNum") is not None
+        assert run.find(f"{HP}t").text == "고친 텍스트"
+
+
+class TestReaderCoversBothShapes:
+    def test_markdown_reads_gold_shaped_notes(self) -> None:
+        doc = HwpxDocument.new()
+        para = doc.add_paragraph("누리호 발사 성공")
+        para.add_footnote("한국형 발사체")
+        md = export_markdown(_roundtrip(doc))
+        assert "[^fn" in md
+        assert "한국형 발사체" in md
+
+    def test_markdown_still_reads_legacy_run_direct_notes(self) -> None:
+        # 5.4 이전 자사 방출(run 직속 footNote) 호환 유지
+        doc = HwpxDocument.new()
+        para = doc.add_paragraph("본문")
+        run = para.element.makeelement(f"{HP}run", {"charPrIDRef": "0"})
+        para.element.append(run)
+        note = run.makeelement(f"{HP}footNote", {"instId": "9999"})
+        run.append(note)
+        sub = note.makeelement(f"{HP}subList", {"id": "", "vertAlign": "TOP"})
+        note.append(sub)
+        body_p = sub.makeelement(f"{HP}p", {"id": "0", "paraPrIDRef": "0", "styleIDRef": "0"})
+        sub.append(body_p)
+        body_run = body_p.makeelement(f"{HP}run", {"charPrIDRef": "0"})
+        body_p.append(body_run)
+        t = body_run.makeelement(f"{HP}t", {})
+        t.text = "구식 각주 본문"
+        body_run.append(t)
+        md = export_markdown(_roundtrip(doc))
+        assert "구식 각주 본문" in md
+
+    def test_notes_survive_roundtrip_and_are_discoverable(self) -> None:
+        doc = HwpxDocument.new()
+        para = doc.add_paragraph("앵커 문장")
+        para.add_footnote("왕복 각주")
+        reopened = _roundtrip(doc)
+        notes = [
+            el
+            for section in reopened.sections
+            for el in section.element.iter(f"{HP}footNote")
+        ]
+        assert len(notes) == 1
+        assert notes[0].get("number") == "1"