python-hwpx 2.16.0__py3-none-any.whl → 2.18.0__py3-none-any.whl

hwpx/document.py

@@ -116,6 +116,7 @@ _FORM_FIELD_PARAM_NAMES = {
     "guide",
 }
 _TEXT_ILLEGAL = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\ufffe\uffff]")
+_TRACKED_TEXT_ILLEGAL = re.compile(r"[\x00-\x08\x09\x0b\x0c\x0d\x0e-\x1f\ufffe\uffff]")
 
 
 def _local_name(node_or_tag: Any) -> str:
@@ -131,6 +132,10 @@ def _sanitize_field_text(value: str) -> str:
     return _TEXT_ILLEGAL.sub("", value)
 
 
+def _sanitize_tracked_text(value: str) -> str:
+    return _TRACKED_TEXT_ILLEGAL.sub("", value)
+
+
 def _field_type_tokens(*values: str | None) -> set[str]:
     tokens: set[str] = set()
     for value in values:
@@ -558,6 +563,111 @@ class HwpxDocument:
 
         return self._root.track_change_author(author_id_ref)
 
+    def add_track_change(
+        self,
+        change_type: str,
+        *,
+        author_name: str = "AI Agent",
+        date: str | None = None,
+    ) -> int:
+        """Add tracked-change header metadata and return the new change id."""
+
+        return self._root.add_track_change(
+            change_type,
+            author_name=author_name,
+            date=date,
+        )
+
+    @staticmethod
+    def _paragraph_has_deletable_text(
+        paragraph: HwpxOxmlParagraph,
+        match: str | None,
+    ) -> bool:
+        for run in paragraph.runs:
+            model = run.to_model()
+            run_text = "".join(span.text for span in model.text_spans)
+            if match is None:
+                if run_text:
+                    return True
+            elif match in run_text:
+                return True
+        return False
+
+    def add_tracked_insert(
+        self,
+        paragraph: HwpxOxmlParagraph,
+        text: str,
+        *,
+        author: str = "AI Agent",
+        date: str | None = None,
+        char_pr_id_ref: str | int | None = None,
+    ) -> int:
+        """Append tracked inserted *text* to *paragraph* and return its change id."""
+
+        sanitized = _sanitize_tracked_text(text)
+        if not sanitized:
+            raise ValueError("tracked insert text must be non-empty")
+        change_id = self.add_track_change("Insert", author_name=author, date=date)
+        mark_id = self._root.next_track_change_mark_id()
+        paragraph.add_tracked_insert(
+            sanitized,
+            change_id=change_id,
+            mark_id=mark_id,
+            char_pr_id_ref=char_pr_id_ref,
+        )
+        return change_id
+
+    def add_tracked_delete(
+        self,
+        paragraph: HwpxOxmlParagraph,
+        *,
+        match: str | None = None,
+        author: str = "AI Agent",
+        date: str | None = None,
+    ) -> int:
+        """Wrap paragraph text or the first matching substring in delete marks."""
+
+        if match == "":
+            raise ValueError("match must be a non-empty string")
+        if not self._paragraph_has_deletable_text(paragraph, match):
+            if match is None:
+                raise ValueError("paragraph contains no text to delete")
+            raise ValueError("match text was not found in the paragraph")
+
+        change_id = self.add_track_change("Delete", author_name=author, date=date)
+        mark_id = self._root.next_track_change_mark_id()
+        paragraph.add_tracked_delete(
+            change_id=change_id,
+            first_mark_id=mark_id,
+            match=match,
+        )
+        return change_id
+
+    def add_tracked_replace(
+        self,
+        paragraph: HwpxOxmlParagraph,
+        old: str,
+        new: str,
+        *,
+        author: str = "AI Agent",
+        date: str | None = None,
+    ) -> tuple[int, int]:
+        """Represent a replacement as tracked delete of *old* plus tracked insert of *new*."""
+
+        delete_change_id = self.add_tracked_delete(
+            paragraph,
+            match=old,
+            author=author,
+            date=date,
+        )
+        insert_change_id = self.add_tracked_insert(
+            paragraph,
+            new,
+            author=author,
+            date=date,
+        )
+        return delete_change_id, insert_change_id
+
     @property
     def memos(self) -> list[HwpxOxmlMemo]:
         """Return all memo entries declared in every section."""
@@ -659,7 +769,11 @@ class HwpxDocument:
         _append_element(parameters, f"{_HP}integerParam", {"name": "Number"}).text = str(max(1, number))
         _append_element(parameters, f"{_HP}stringParam", {"name": "CreateDateTime"}).text = created_value
         _append_element(parameters, f"{_HP}stringParam", {"name": "Author"}).text = author_value
-        _append_element(parameters, f"{_HP}stringParam", {"name": "MemoShapeID"}).text = memo_shape_id
+        # Hancom's own files use ``MemoShapeIDRef`` (65535 = the built-in default memo
+        # shape) — an empty/absent ref leaves the memo box unlinked.
+        _append_element(parameters, f"{_HP}stringParam", {"name": "MemoShapeIDRef"}).text = (
+            memo_shape_id or "65535"
+        )
 
         sub_list = _append_element(
             field_begin,
@@ -684,7 +798,10 @@ class HwpxDocument:
             },
         )
         sub_run = _append_element(sub_para, f"{_HP}run", {"charPrIDRef": char_ref})
-        _append_element(sub_run, f"{_HP}t").text = memo.id or field_value
+        # The MEMO field's subList holds the comment TEXT — this is what Hancom shows
+        # in the margin memo box. (Previously this emitted ``memo.id``, so Hancom
+        # rendered the numeric id instead of the comment.)
+        _append_element(sub_run, f"{_HP}t").text = memo.text or ""
 
         run_end = paragraph_element.makeelement(f"{_HP}run", {"charPrIDRef": char_ref})
         ctrl_end = _append_element(run_end, f"{_HP}ctrl")

hwpx/oxml/__init__.py

@@ -10,10 +10,13 @@ from .body import (
     Run,
     Section,
     TextSpan,
+    append_tracked_insert_to_run,
+    create_track_change_mark,
     parse_paragraph_element,
     parse_run_element,
     parse_section_element,
     parse_text_span,
+    wrap_tracked_delete_in_span,
 )
 from .common import GenericElement, parse_generic_element
 
@@ -74,7 +77,9 @@ from .header import (
     TrackChangeAuthorList,
     TrackChangeConfig,
     TrackChangeList,
+    format_track_change_date,
     memo_shape_from_attributes,
+    normalize_track_change_type,
     parse_begin_num,
     parse_bullet,
     parse_bullet_para_head,
@@ -98,6 +103,8 @@ from .header import (
     parse_track_change_author,
     parse_track_change_authors,
     parse_track_changes,
+    track_change_author_to_xml,
+    track_change_to_xml,
 )
 from .parser import element_to_model, parse_header_xml, parse_section_xml
 from .schema import load_schema
@@ -173,7 +180,10 @@ __all__ = [
     "TrackChangeList",
     "TextSpan",
     "XmlSource",
+    "append_tracked_insert_to_run",
+    "create_track_change_mark",
     "element_to_model",
+    "format_track_change_date",
     "load_schema",
     "parse_begin_num",
     "parse_bullet",
@@ -202,9 +212,13 @@ __all__ = [
     "parse_track_change_author",
     "parse_track_change_authors",
     "parse_track_changes",
+    "normalize_track_change_type",
     "parse_section_element",
     "parse_section_xml",
     "parse_text_span",
+    "track_change_author_to_xml",
+    "track_change_to_xml",
+    "wrap_tracked_delete_in_span",
 ]
 
 logger = logging.getLogger(__name__)

hwpx/oxml/_document_impl.py

@@ -17,6 +17,7 @@ from . import body
 from .common import GenericElement
 from .header import (
     Bullet,
+    Header,
     MemoProperties,
     MemoShape,
     ParagraphProperty,
@@ -26,10 +27,14 @@ from .header import (
     memo_shape_from_attributes,
     parse_bullets,
     parse_border_fills,
+    parse_header_element,
     parse_paragraph_properties,
     parse_styles,
+    parse_track_change_config,
     parse_track_change_authors,
     parse_track_changes,
+    track_change_author_to_xml,
+    track_change_to_xml,
 )
 from .namespaces import (
     HWPML_COMPAT_ROOT_NAMESPACES,
@@ -1566,8 +1571,11 @@ class HwpxOxmlRun:
     def apply_model(self, model: "body.Run") -> None:
         new_node = body.serialize_run(model)
         xml_bytes = LET.tostring(new_node)
-        replacement = ET.fromstring(xml_bytes)
         parent = self.paragraph.element
+        if isinstance(parent, LET._Element):
+            replacement = LET.fromstring(xml_bytes)
+        else:
+            replacement = ET.fromstring(xml_bytes)
         run_children = list(parent)
         index = run_children.index(self.element)
         parent.remove(self.element)
@@ -3598,8 +3606,11 @@ class HwpxOxmlParagraph:
     def apply_model(self, model: "body.Paragraph") -> None:
         new_node = body.serialize_paragraph(model)
         xml_bytes = LET.tostring(new_node)
-        replacement = ET.fromstring(xml_bytes)
         parent = self.section.element
+        if isinstance(parent, LET._Element):
+            replacement = LET.fromstring(xml_bytes)
+        else:
+            replacement = ET.fromstring(xml_bytes)
         paragraph_children = list(parent)
         index = paragraph_children.index(self.element)
         parent.remove(self.element)
@@ -3628,6 +3639,99 @@ class HwpxOxmlParagraph:
         """Return the runs contained in this paragraph."""
         return [HwpxOxmlRun(run, self) for run in self._run_elements()]
 
+    def _last_text_run_for_tracked_insert(
+        self,
+        *,
+        char_pr_id_ref: str | int | None = None,
+    ) -> HwpxOxmlRun:
+        desired_char = None if char_pr_id_ref is None else str(char_pr_id_ref)
+        runs = self.runs
+
+        if desired_char is not None:
+            for run in reversed(runs):
+                if run.char_pr_id_ref != desired_char:
+                    continue
+                if run.to_model().text_spans:
+                    return run
+            return self.add_run("", char_pr_id_ref=desired_char)
+
+        for run in reversed(runs):
+            if run.to_model().text_spans:
+                return run
+        return self.add_run("", char_pr_id_ref=self.char_pr_id_ref or "0")
+
+    def add_tracked_insert(
+        self,
+        text: str,
+        *,
+        change_id: int,
+        mark_id: int,
+        char_pr_id_ref: str | int | None = None,
+    ) -> None:
+        sanitized = _sanitize_text(text)
+        if not sanitized:
+            raise ValueError("tracked insert text must be non-empty")
+
+        run = self._last_text_run_for_tracked_insert(char_pr_id_ref=char_pr_id_ref)
+        model = run.to_model()
+        body.append_tracked_insert_to_run(
+            model,
+            sanitized,
+            tc_id=change_id,
+            mark_id=mark_id,
+        )
+        run.apply_model(model)
+
+    def add_tracked_delete(
+        self,
+        *,
+        change_id: int,
+        first_mark_id: int,
+        match: str | None = None,
+    ) -> int:
+        if match == "":
+            raise ValueError("match must be a non-empty string")
+
+        next_mark_id = first_mark_id
+        if match is not None:
+            for run in self.runs:
+                model = run.to_model()
+                if match not in "".join(span.text for span in model.text_spans):
+                    continue
+                for span in model.text_spans:
+                    if body.wrap_tracked_delete_in_span(
+                        span,
+                        tc_id=change_id,
+                        mark_id=next_mark_id,
+                        match=match,
+                    ):
+                        run.apply_model(model)
+                        return next_mark_id + 1
+                raise ValueError("match crosses inline markup and cannot be wrapped safely")
+            raise ValueError("match text was not found in the paragraph")
+
+        modified = False
+        for run in self.runs:
+            model = run.to_model()
+            changed = False
+            for span in model.text_spans:
+                if not span.text:
+                    continue
+                body.wrap_tracked_delete_in_span(
+                    span,
+                    tc_id=change_id,
+                    mark_id=next_mark_id,
+                )
+                next_mark_id += 1
+                changed = True
+            if changed:
+                run.apply_model(model)
+                modified = True
+
+        if not modified:
+            raise ValueError("paragraph contains no text to delete")
+        return next_mark_id
+
     @property
     def text(self) -> str:
         """Return the concatenated textual content of this paragraph."""
@@ -4710,6 +4814,15 @@ class HwpxOxmlHeader:
     def attach_document(self, document: "HwpxOxmlDocument") -> None:
         self._document = document
 
+    def to_model(self) -> Header:
+        return parse_header_element(self._convert_to_lxml(self._element))
+
+    @staticmethod
+    def _coerce_serialized_child(parent: ET.Element, child: LET._Element) -> ET.Element:
+        if isinstance(parent, LET._Element):
+            return child
+        return ET.fromstring(LET.tostring(child, encoding="utf-8"))
+
     def _begin_num_element(self, create: bool = False) -> ET.Element | None:
         element = self._element.find(f"{_HH}beginNum")
         if element is None and create:
@@ -5383,18 +5496,116 @@ class HwpxOxmlHeader:
             return None
         return ref_list.find(f"{_HH}styles")
 
-    def _track_changes_element(self) -> ET.Element | None:
-        ref_list = self._ref_list_element()
+    def _track_changes_element(self, create: bool = False) -> ET.Element | None:
+        ref_list = self._ref_list_element(create=create)
         if ref_list is None:
             return None
         return ref_list.find(f"{_HH}trackChanges")
 
-    def _track_change_authors_element(self) -> ET.Element | None:
-        ref_list = self._ref_list_element()
+    def _track_changes_element_or_create(self) -> ET.Element:
+        ref_list = self._ref_list_element(create=True)
+        if ref_list is None:  # pragma: no cover - defensive branch
+            raise RuntimeError("failed to create <refList> element")
+        element = ref_list.find(f"{_HH}trackChanges")
+        if element is None:
+            element = ref_list.makeelement(f"{_HH}trackChanges", {"itemCnt": "0"})
+            ref_list.append(element)
+            self.mark_dirty()
+        return element
+
+    def _track_change_authors_element(self, create: bool = False) -> ET.Element | None:
+        ref_list = self._ref_list_element(create=create)
         if ref_list is None:
             return None
         return ref_list.find(f"{_HH}trackChangeAuthors")
 
+    def _track_change_authors_element_or_create(self) -> ET.Element:
+        ref_list = self._ref_list_element(create=True)
+        if ref_list is None:  # pragma: no cover - defensive branch
+            raise RuntimeError("failed to create <refList> element")
+        element = ref_list.find(f"{_HH}trackChangeAuthors")
+        if element is None:
+            element = ref_list.makeelement(f"{_HH}trackChangeAuthors", {"itemCnt": "0"})
+            ref_list.append(element)
+            self.mark_dirty()
+        return element
+
+    def _track_change_config_element(self, create: bool = False) -> ET.Element | None:
+        for child in self._element:
+            if tag_local_name(child.tag) in {"trackchageConfig", "trackchangeConfig"}:
+                return child
+        if not create:
+            return None
+        element = self._element.makeelement(f"{_HH}trackchageConfig", {"flags": "0"})
+        self._element.append(element)
+        self.mark_dirty()
+        return element
+
+    @property
+    def track_change_config(self):
+        element = self._track_change_config_element()
+        if element is None:
+            return None
+        return parse_track_change_config(self._convert_to_lxml(element))
+
+    def add_track_change(
+        self,
+        change_type: str,
+        *,
+        author_name: str = "AI Agent",
+        date: str | None = None,
+    ) -> int:
+        model = self.to_model()
+        change_id = model.add_track_change(
+            change_type,
+            author_name=author_name,
+            date=date,
+        )
+        if model.ref_list is None or model.ref_list.track_changes is None:
+            raise RuntimeError("failed to create tracked-change metadata")
+
+        change = next(
+            candidate
+            for candidate in model.ref_list.track_changes.changes
+            if candidate.id == change_id
+        )
+        changes_element = self._track_changes_element_or_create()
+        changes_element.append(
+            self._coerce_serialized_child(changes_element, track_change_to_xml(change))
+        )
+        changes_element.set("itemCnt", str(model.ref_list.track_changes.item_cnt or 0))
+
+        authors = model.ref_list.track_change_authors
+        if authors is not None and change.author_id is not None:
+            author = authors.author_by_id(change.author_id)
+            if author is not None:
+                authors_element = self._track_change_authors_element_or_create()
+                existing_ids = {
+                    child.get("id")
+                    for child in authors_element.findall(f"{_HH}trackChangeAuthor")
+                }
+                author_ids = {str(author.id)} if author.id is not None else set()
+                if author.raw_id is not None:
+                    author_ids.add(author.raw_id)
+                if not existing_ids.intersection(author_ids):
+                    authors_element.append(
+                        self._coerce_serialized_child(
+                            authors_element,
+                            track_change_author_to_xml(author),
+                        )
+                    )
+                authors_element.set("itemCnt", str(authors.item_cnt or 0))
+
+        config_element = self._track_change_config_element(create=True)
+        if config_element is None:  # pragma: no cover - defensive branch
+            raise RuntimeError("failed to create <trackchageConfig> element")
+        flags = 1
+        if model.track_change_config is not None and model.track_change_config.flags is not None:
+            flags = model.track_change_config.flags
+        config_element.set("flags", str(flags | 1))
+        self.mark_dirty()
+        return change_id
+
     def find_basic_border_fill_id(self) -> str | None:
         element = self._border_fills_element()
         if element is None:
@@ -6341,6 +6552,41 @@ class HwpxOxmlDocument:
     ) -> TrackChangeAuthor | None:
         return HwpxOxmlHeader._lookup_by_id(self.track_change_authors, author_id_ref)
 
+    def add_track_change(
+        self,
+        change_type: str,
+        *,
+        author_name: str = "AI Agent",
+        date: str | None = None,
+    ) -> int:
+        if not self._headers:
+            raise ValueError("document does not contain any headers")
+        return self._headers[0].add_track_change(
+            change_type,
+            author_name=author_name,
+            date=date,
+        )
+
+    def next_track_change_mark_id(self) -> int:
+        max_id = 0
+        for section in self._sections:
+            for element in section.element.iter():
+                if tag_local_name(element.tag) not in {
+                    "insertBegin",
+                    "insertEnd",
+                    "deleteBegin",
+                    "deleteEnd",
+                }:
+                    continue
+                raw_id = element.get("Id")
+                if raw_id is None:
+                    continue
+                try:
+                    max_id = max(max_id, int(raw_id))
+                except ValueError:
+                    continue
+        return max_id + 1
+
     @property
     def paragraphs(self) -> list[HwpxOxmlParagraph]:
         paragraphs: list[HwpxOxmlParagraph] = []