python-hwpx 2.16.0__py3-none-any.whl → 2.17.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] = []

hwpx/oxml/body.py

@@ -43,6 +43,11 @@ _TRACK_CHANGE_MARK_NAMES = {
     "deleteEnd",
 }
 
+_TRACK_CHANGE_TYPES = {
+    "insert": "insert",
+    "delete": "delete",
+}
+
 PreservedElement = Union[
     GenericElement,
     "CommentElement",
@@ -263,10 +268,150 @@ def _qualified_tag(tag: Optional[str], name: str) -> str:
     return f"{_DEFAULT_HP}{name}"
 
 
+def _tag_namespace(tag: Optional[str]) -> Optional[str]:
+    if not tag or not tag.startswith("{") or "}" not in tag:
+        return None
+    return tag[1:].split("}", 1)[0]
+
+
+def _child_tag_like(parent_tag: Optional[str], name: str) -> str:
+    namespace = _tag_namespace(parent_tag)
+    if namespace:
+        return f"{{{namespace}}}{name}"
+    return _qualified_tag(None, name)
+
+
 def _bool_to_str(value: bool) -> str:
     return "true" if value else "false"
 
 
+def _bool_to_flag(value: bool) -> str:
+    return "1" if value else "0"
+
+
+def create_track_change_mark(
+    change_type: str,
+    *,
+    is_begin: bool,
+    tc_id: int,
+    mark_id: int,
+    para_end: bool | None = None,
+) -> TrackChangeMark:
+    """Create a typed inline tracked-change boundary mark."""
+
+    normalized = _TRACK_CHANGE_TYPES.get(change_type.strip().lower())
+    if normalized is None:
+        raise ValueError("change_type must be 'insert' or 'delete'")
+    name = f"{normalized}{'Begin' if is_begin else 'End'}"
+    return TrackChangeMark(
+        tag=_qualified_tag(None, name),
+        name=name,
+        change_type=normalized,
+        is_begin=is_begin,
+        para_end=para_end,
+        tc_id=int(tc_id),
+        id=int(mark_id),
+    )
+
+
+def append_tracked_insert_to_run(
+    run: Run,
+    text: str,
+    *,
+    tc_id: int,
+    mark_id: int,
+) -> None:
+    """Append tracked inserted *text* to the last text span in *run*."""
+
+    if not text:
+        raise ValueError("tracked insert text must be non-empty")
+
+    if run.text_spans:
+        span = run.text_spans[-1]
+    else:
+        span = TextSpan(tag=_child_tag_like(run.tag, "t"), leading_text="")
+        run.text_spans.append(span)
+        run.content.append(span)
+
+    span.marks.append(
+        TextMarkup(
+            create_track_change_mark("insert", is_begin=True, tc_id=tc_id, mark_id=mark_id),
+            text,
+        )
+    )
+    span.marks.append(
+        TextMarkup(
+            create_track_change_mark(
+                "insert",
+                is_begin=False,
+                tc_id=tc_id,
+                mark_id=mark_id,
+                para_end=False,
+            )
+        )
+    )
+
+
+def wrap_tracked_delete_in_span(
+    span: TextSpan,
+    *,
+    tc_id: int,
+    mark_id: int,
+    match: str | None = None,
+) -> bool:
+    """Wrap a whole span or a substring in tracked delete marks."""
+
+    if match == "":
+        raise ValueError("match must be a non-empty string")
+
+    begin = TextMarkup(
+        create_track_change_mark("delete", is_begin=True, tc_id=tc_id, mark_id=mark_id)
+    )
+    end = TextMarkup(
+        create_track_change_mark(
+            "delete",
+            is_begin=False,
+            tc_id=tc_id,
+            mark_id=mark_id,
+            para_end=False,
+        )
+    )
+
+    if match is None:
+        if not span.text:
+            return False
+        leading = span.leading_text
+        span.leading_text = ""
+        begin.trailing_text = leading
+        span.marks.insert(0, begin)
+        span.marks.append(end)
+        return True
+
+    index = span.leading_text.find(match)
+    if index >= 0:
+        before = span.leading_text[:index]
+        after = span.leading_text[index + len(match) :]
+        span.leading_text = before
+        begin.trailing_text = match
+        end.trailing_text = after
+        span.marks[0:0] = [begin, end]
+        return True
+
+    for mark_index, markup in enumerate(span.marks):
+        index = markup.trailing_text.find(match)
+        if index < 0:
+            continue
+        before = markup.trailing_text[:index]
+        after = markup.trailing_text[index + len(match) :]
+        markup.trailing_text = before
+        begin.trailing_text = match
+        end.trailing_text = after
+        span.marks[mark_index + 1 : mark_index + 1] = [begin, end]
+        return True
+
+    return False
+
+
 def parse_track_change_mark(node: etree._Element) -> TrackChangeMark:
     attrs = {key: value for key, value in node.attrib.items()}
     para_end = parse_bool(attrs.pop("paraend", None))
@@ -670,13 +815,14 @@ def _preserved_element_to_xml(element: PreservedElement) -> etree._Element:
 
 
 def _track_change_mark_to_xml(mark: TrackChangeMark) -> etree._Element:
-    attrs = dict(mark.attributes)
-    if mark.para_end is not None:
-        attrs["paraend"] = _bool_to_str(mark.para_end)
-    if mark.tc_id is not None:
-        attrs["TcId"] = str(mark.tc_id)
+    attrs: Dict[str, str] = {}
     if mark.id is not None:
         attrs["Id"] = str(mark.id)
+    if mark.tc_id is not None:
+        attrs["TcId"] = str(mark.tc_id)
+    if mark.para_end is not None:
+        attrs["paraend"] = _bool_to_flag(mark.para_end)
+    attrs.update(mark.attributes)
     return etree.Element(_qualified_tag(mark.tag, mark.name), attrs)
 
 
@@ -789,6 +935,8 @@ __all__ = [
     "TextSpan",
     "TrackChangeMark",
     "TransformMatrix",
+    "append_tracked_insert_to_run",
+    "create_track_change_mark",
     "parse_comment_element",
     "parse_control_element",
     "parse_form_combo_box_element",
@@ -806,6 +954,7 @@ __all__ = [
     "parse_transform_matrix_element",
     "serialize_paragraph",
     "serialize_run",
+    "wrap_tracked_delete_in_span",
 ]
 
 logger = logging.getLogger(__name__)

hwpx/oxml/header.py

@@ -5,6 +5,7 @@ import logging
 import base64
 import binascii
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from typing import Dict, List, Mapping, Optional
 
 from lxml import etree
@@ -578,7 +579,7 @@ class TrackChangeAuthor:
     id: Optional[int]
     raw_id: Optional[str]
     name: Optional[str]
-    mark: Optional[bool]
+    mark: Optional[bool | int]
     color: Optional[str]
     attributes: Dict[str, str] = field(default_factory=dict)
 
@@ -701,6 +702,128 @@ class Header:
             return None
         return self.ref_list.track_change_authors.author_by_id(author_id_ref)
 
+    def add_track_change(
+        self,
+        change_type: str,
+        *,
+        author_name: str = "AI Agent",
+        date: str | None = None,
+    ) -> int:
+        """Append tracked-change metadata and return the new change id."""
+
+        normalized_type = normalize_track_change_type(change_type)
+        resolved_author = author_name.strip() or "AI Agent"
+
+        if self.ref_list is None:
+            self.ref_list = RefList()
+        ref_list = self.ref_list
+
+        if ref_list.track_change_authors is None:
+            ref_list.track_change_authors = TrackChangeAuthorList(item_cnt=0, authors=[])
+        author_list = ref_list.track_change_authors
+
+        author = next(
+            (candidate for candidate in author_list.authors if candidate.name == resolved_author),
+            None,
+        )
+        if author is None:
+            author_id = _next_track_change_author_id(author_list.authors)
+            author = TrackChangeAuthor(
+                id=author_id,
+                raw_id=None,
+                name=resolved_author,
+                mark=author_id,
+                color=None,
+            )
+            author_list.authors.append(author)
+        else:
+            author_id = _resolved_id(author.id, author.raw_id)
+        author_list.item_cnt = len(author_list.authors)
+
+        if ref_list.track_changes is None:
+            ref_list.track_changes = TrackChangeList(item_cnt=0, changes=[])
+        change_list = ref_list.track_changes
+
+        change_id = _next_track_change_id(change_list.changes)
+        change_list.changes.append(
+            TrackChange(
+                id=change_id,
+                raw_id=None,
+                change_type=normalized_type,
+                date=format_track_change_date(date),
+                author_id=author_id,
+                char_shape_id=None,
+                para_shape_id=None,
+                hide=False,
+            )
+        )
+        change_list.item_cnt = len(change_list.changes)
+
+        if self.track_change_config is None:
+            self.track_change_config = TrackChangeConfig(flags=1)
+        else:
+            self.track_change_config.flags = (self.track_change_config.flags or 0) | 1
+        return change_id
+
+
+def format_track_change_date(value: str | None = None) -> str:
+    if value is not None:
+        return value
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def normalize_track_change_type(change_type: str) -> str:
+    normalized = change_type.strip().lower()
+    aliases = {
+        "insert": "Insert",
+        "delete": "Delete",
+        "charshape": "CharShape",
+        "char_shape": "CharShape",
+        "char-shape": "CharShape",
+    }
+    resolved = aliases.get(normalized)
+    if resolved is None:
+        raise ValueError("change_type must be 'Insert', 'Delete', or 'CharShape'")
+    return resolved
+
+
+def _resolved_id(identifier: int | None, raw_id: str | None) -> int:
+    if identifier is not None:
+        return identifier
+    if raw_id is not None:
+        return int(raw_id)
+    raise ValueError("tracked-change reference is missing an id")
+
+
+def _next_numeric_id(values: list[int]) -> int:
+    return 1 if not values else max(values) + 1
+
+
+def _next_track_change_id(changes: List[TrackChange]) -> int:
+    ids: list[int] = []
+    for change in changes:
+        if change.id is not None:
+            ids.append(change.id)
+        elif change.raw_id is not None:
+            try:
+                ids.append(int(change.raw_id))
+            except ValueError:
+                continue
+    return _next_numeric_id(ids)
+
+
+def _next_track_change_author_id(authors: List[TrackChangeAuthor]) -> int:
+    ids: list[int] = []
+    for author in authors:
+        if author.id is not None:
+            ids.append(author.id)
+        elif author.raw_id is not None:
+            try:
+                ids.append(int(author.raw_id))
+            except ValueError:
+                continue
+    return _next_numeric_id(ids)
+
 
 def parse_begin_num(node: etree._Element) -> BeginNum:
     return BeginNum(
@@ -1226,11 +1349,12 @@ def parse_track_change_author(node: etree._Element) -> TrackChangeAuthor:
     attributes = {
         key: value for key, value in node.attrib.items() if key not in known_attrs
     }
+    mark = _parse_track_change_author_mark(node.get("mark"))
     return TrackChangeAuthor(
         id=parse_int(node.get("id")),
         raw_id=node.get("id"),
         name=node.get("name"),
-        mark=parse_bool(node.get("mark")),
+        mark=mark,
         color=node.get("color"),
         attributes=attributes,
     )
@@ -1301,7 +1425,7 @@ def parse_header_element(node: etree._Element) -> Header:
             header.doc_option = parse_doc_option(child)
         elif name == "metaTag":
             header.meta_tag = text_or_none(child)
-        elif name == "trackchangeConfig":
+        elif name in {"trackchageConfig", "trackchangeConfig"}:
             header.track_change_config = parse_track_change_config(child)
         else:
             header.other_elements.setdefault(name, []).append(parse_generic_element(child))
@@ -1309,6 +1433,74 @@ def parse_header_element(node: etree._Element) -> Header:
     return header
 
 
+def _parse_track_change_author_mark(value: str | None) -> bool | int | None:
+    if value is None:
+        return None
+    try:
+        return parse_bool(value)
+    except ValueError:
+        return parse_int(value, allow_none=False)
+
+
+def _set_optional_int_attr(
+    attributes: Dict[str, str],
+    name: str,
+    value: int | None,
+) -> None:
+    if value is not None:
+        attributes[name] = str(value)
+
+
+def _set_optional_str_attr(
+    attributes: Dict[str, str],
+    name: str,
+    value: str | None,
+) -> None:
+    if value is not None:
+        attributes[name] = value
+
+
+def _set_optional_flag_attr(
+    attributes: Dict[str, str],
+    name: str,
+    value: bool | None,
+) -> None:
+    if value is not None:
+        attributes[name] = "1" if value else "0"
+
+
+def track_change_to_xml(change: TrackChange) -> etree._Element:
+    attributes = dict(change.attributes)
+    _set_optional_str_attr(attributes, "type", change.change_type)
+    _set_optional_str_attr(attributes, "date", change.date)
+    _set_optional_int_attr(attributes, "authorID", change.author_id)
+    _set_optional_int_attr(attributes, "charShapeID", change.char_shape_id)
+    _set_optional_int_attr(attributes, "paraShapeID", change.para_shape_id)
+    _set_optional_flag_attr(attributes, "hide", change.hide)
+    _set_optional_int_attr(attributes, "id", change.id)
+    if change.raw_id is not None and change.id is None:
+        attributes["id"] = change.raw_id
+    return etree.Element(f"{{http://www.hancom.co.kr/hwpml/2011/head}}trackChange", attributes)
+
+
+def track_change_author_to_xml(author: TrackChangeAuthor) -> etree._Element:
+    attributes = dict(author.attributes)
+    _set_optional_str_attr(attributes, "name", author.name)
+    if author.mark is not None:
+        if isinstance(author.mark, bool):
+            attributes["mark"] = "1" if author.mark else "0"
+        else:
+            attributes["mark"] = str(author.mark)
+    _set_optional_int_attr(attributes, "id", author.id)
+    if author.raw_id is not None and author.id is None:
+        attributes["id"] = author.raw_id
+    _set_optional_str_attr(attributes, "color", author.color)
+    return etree.Element(
+        f"{{http://www.hancom.co.kr/hwpml/2011/head}}trackChangeAuthor",
+        attributes,
+    )
+
+
 __all__ = [
     "BeginNum",
     "BorderFillList",
@@ -1350,7 +1542,9 @@ __all__ = [
     "TrackChangeAuthorList",
     "TrackChangeConfig",
     "TrackChangeList",
+    "format_track_change_date",
     "memo_shape_from_attributes",
+    "normalize_track_change_type",
     "parse_begin_num",
     "parse_bullet",
     "parse_bullet_para_head",
@@ -1379,6 +1573,8 @@ __all__ = [
     "parse_track_change_author",
     "parse_track_change_authors",
     "parse_track_changes",
+    "track_change_author_to_xml",
+    "track_change_to_xml",
 ]
 
 logger = logging.getLogger(__name__)

hwpx/tools/redline.py

@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Redline authoring verification helpers."""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from os import PathLike, fspath
+from typing import Any
+
+from hwpx.document import HwpxDocument
+from hwpx.oxml.body import TrackChangeMark
+from hwpx.visual.oracle import RenderBackend, resolve_oracle, visual_check
+
+REDLINE_VERIFY_REPORT_VERSION = "redline-verify-v1"
+_DEMO_DATE = "2026-06-30T00:00:00Z"
+
+
+def verify_redline(
+    before_hwpx: str | PathLike[str],
+    after_hwpx: str | PathLike[str],
+    *,
+    oracle: RenderBackend | None = None,
+) -> dict[str, Any]:
+    """Verify authored redline structure and fold in the VisualComplete report."""
+
+    warnings: list[str] = []
+    document: HwpxDocument | None = None
+    structural_opens_clean = False
+    try:
+        document = HwpxDocument.open(after_hwpx)
+        structural_opens_clean = True
+    except Exception as exc:
+        warnings.append(f"after document did not reopen structurally: {exc}")
+
+    change_count = 0
+    changes_by_type: dict[str, int] = {}
+    marks_linked = False
+    display_enabled = False
+
+    if document is not None:
+        changes = document.track_changes
+        changes_by_id = {
+            int(change.id): change
+            for change in changes.values()
+            if change.id is not None
+        }
+        change_count = len(changes_by_id)
+        type_counter = Counter(_normalise_change_type(change.change_type) for change in changes_by_id.values())
+        changes_by_type = dict(sorted(type_counter.items()))
+
+        if not changes_by_id:
+            warnings.append("after document has no header trackChanges entries")
+
+        body_marks = _collect_track_change_marks(document)
+        marks_linked = _marks_are_linked(body_marks, changes_by_id)
+        if not body_marks:
+            warnings.append("after document has no body insert/delete track-change marks")
+        elif not marks_linked:
+            warnings.append("body track-change marks are not fully linked to header trackChanges by TcId")
+
+        display_enabled = _track_change_display_enabled(document)
+        if not display_enabled:
+            warnings.append("trackChangeConfig display flag is not enabled")
+
+    backend = oracle if oracle is not None else resolve_oracle()
+    visual_report = visual_check(
+        fspath(before_hwpx),
+        fspath(after_hwpx),
+        oracle=backend,
+    )
+    warnings.extend(visual_report.warnings)
+    warnings.extend(f"visual error: {error}" for error in visual_report.errors)
+    warnings.extend(_visual_signal_warnings(visual_report))
+
+    render_checked = bool(visual_report.render_checked)
+    opens_clean: bool | None
+    if render_checked:
+        opens_clean = True
+    elif visual_report.errors:
+        opens_clean = False
+    else:
+        opens_clean = None
+
+    return {
+        "report_version": REDLINE_VERIFY_REPORT_VERSION,
+        "changeCount": change_count,
+        "changesByType": changes_by_type,
+        "marksLinked": marks_linked,
+        "displayEnabled": display_enabled,
+        "opensClean": opens_clean if structural_opens_clean else False,
+        "render_checked": render_checked,
+        "visual_ok": visual_report.ok if render_checked else None,
+        "warnings": warnings,
+    }
+
+
+def author_demo_redline(doc: HwpxDocument) -> HwpxDocument:
+    """Apply one tracked insert and one tracked delete to *doc*."""
+
+    paragraph = doc.add_paragraph("redline delete target", char_pr_id_ref="0")
+    doc.add_tracked_insert(paragraph, " inserted", date=_DEMO_DATE)
+    doc.add_tracked_delete(paragraph, match="delete", date=_DEMO_DATE)
+    return doc
+
+
+def _normalise_change_type(value: str | None) -> str:
+    text = str(value or "").strip()
+    if not text:
+        return "Unknown"
+    lowered = text.lower()
+    aliases = {
+        "insert": "Insert",
+        "delete": "Delete",
+        "charshape": "CharShape",
+        "parashape": "ParaShape",
+    }
+    return aliases.get(lowered, text[:1].upper() + text[1:].lower())
+
+
+def _collect_track_change_marks(document: HwpxDocument) -> list[TrackChangeMark]:
+    marks: list[TrackChangeMark] = []
+    for paragraph in document.paragraphs:
+        for run in paragraph.runs:
+            model = run.to_model()
+            for span in model.text_spans:
+                for markup in span.marks:
+                    if isinstance(markup.element, TrackChangeMark):
+                        marks.append(markup.element)
+    return marks
+
+
+def _marks_are_linked(
+    marks: list[TrackChangeMark],
+    changes_by_id: dict[int, Any],
+) -> bool:
+    if not marks or not changes_by_id:
+        return False
+
+    mark_names_by_change: dict[int, set[str]] = defaultdict(set)
+    for mark in marks:
+        if mark.tc_id is None or mark.tc_id not in changes_by_id:
+            return False
+        mark_type = _normalise_change_type(mark.change_type)
+        change_type = _normalise_change_type(changes_by_id[mark.tc_id].change_type)
+        if mark_type != change_type:
+            return False
+        mark_names_by_change[mark.tc_id].add(mark.name)
+
+    for change_id, change in changes_by_id.items():
+        change_type = _normalise_change_type(change.change_type)
+        if change_type not in {"Insert", "Delete"}:
+            continue
+        names = mark_names_by_change.get(change_id, set())
+        if f"{change_type.lower()}Begin" not in names or f"{change_type.lower()}End" not in names:
+            return False
+    return True
+
+
+def _track_change_display_enabled(document: HwpxDocument) -> bool:
+    for header in document.headers:
+        config = header.to_model().track_change_config
+        if config is not None and config.flags is not None and config.flags & 1:
+            return True
+    return False
+
+
+def _visual_signal_warnings(report: Any) -> list[str]:
+    warnings: list[str] = []
+    if report.unexpected_diff_outside_mask:
+        warnings.append("visual signal: unexpected_diff_outside_mask")
+    if report.overlap_detected:
+        warnings.append("visual signal: overlap_detected")
+    if report.overflow_detected:
+        warnings.append("visual signal: overflow_detected")
+    if report.table_break_detected:
+        warnings.append("visual signal: table_break_detected")
+    if report.page_count_changed:
+        warnings.append("visual signal: page_count_changed")
+    return warnings
+
+
+__all__ = [
+    "REDLINE_VERIFY_REPORT_VERSION",
+    "author_demo_redline",
+    "verify_redline",
+]

{python_hwpx-2.16.0.dist-info → python_hwpx-2.17.0.dist-info}/METADATA

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

{python_hwpx-2.16.0.dist-info → python_hwpx-2.17.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 hwpx/__init__.py,sha256=ikzGacbkMN7PhNFVb5h3UhtpfSZ1Smr_cKu0OdSaOes,5052
 hwpx/authoring.py,sha256=_AUGOzwmiHHuO08HZhGCEd6eCHCZV0yXeBaYKMsJJ34,125020
-hwpx/document.py,sha256=zck0NXTj4k_RwBPi72iWgerG67v66TYLofLR8duNXXY,103182
+hwpx/document.py,sha256=M_f1KDkyQNuK8LN-jyLTe4mnQQaMLcPh7vQx0Eg7wYk,107048
 hwpx/form_fill.py,sha256=VUIU53Qa9Ho2aP72biDvJwnDW7ngdAzu3PSd5A7d1JM,9908
 hwpx/package.py,sha256=0rKjGCJbPQvrVBIy07Jpjsu3fI7HhbqFCGWTiTDsJpo,1141
 hwpx/patch.py,sha256=8G1wgGVgCp0KyhQb-y0ZI2FJEatCwLt_JpepHJmYhYQ,23799
@@ -72,13 +72,13 @@ hwpx/opc/package.py,sha256=4Ydaw-1uyTZ7DwNZ89ICJ7CHYwUGzeGR-FbZiyJ5XWk,35484
 hwpx/opc/relationships.py,sha256=tPWLHRMlw0Spvtwou2jCDRfHdcm9FEKKLd95YVHLwYI,6971
 hwpx/opc/security.py,sha256=hsA73sZxUoGIgy2zue9EnV7ChHMfasnplmqzxFs3Mp4,4419
 hwpx/opc/xml_utils.py,sha256=L_fHY1-D5I_TfdRkDQV-bn55EnXc6AqEDWItfMpawVs,3840
-hwpx/oxml/__init__.py,sha256=yBQG1XEelO432SjFvvz_QSJP_82L6zvrMHo9w22k6xc,5018
-hwpx/oxml/_document_impl.py,sha256=L7qtWwJRbNb8smJy64iY3HEWRw0XSqpxqWZ9SmL6qNY,240584
-hwpx/oxml/body.py,sha256=Hhk6DbgM4rSTEXWgMaWudCg-EwPTUnx2AJQVDZ2YVic,26667
+hwpx/oxml/__init__.py,sha256=7koxG5Xc6ia1dWmAqUJJETkAL5wzamSrNVcKuiUH58I,5466
+hwpx/oxml/_document_impl.py,sha256=teZ-5dIaeu2DwIARiBop5u61bSuUkE3ND-lkRkZbBGk,249701
+hwpx/oxml/body.py,sha256=3PzGiYmm03si5OVjGtS-R_tT1rWmsYwE8Ds8ZLhIIio,30609
 hwpx/oxml/canonical_defaults.py,sha256=WHAK7u_W-PDv3P3N1-1-aWAoiUgBh4x-UybFL4NqW-w,3791
 hwpx/oxml/common.py,sha256=TJkafzg7x4T3J29tZchRZk57ZTsrM9PEiqGT3rX3w5o,1044
 hwpx/oxml/document.py,sha256=9_gJgk-Zyoeqft3OB-sce4MQLo-UejR79e1fDEsC7b0,1154
-hwpx/oxml/header.py,sha256=oKq_pSnRBy5MB6xKjdsZUjN87hJ0hojc-2KVPng-aic,43573
+hwpx/oxml/header.py,sha256=m878yWuMv9dRA4enaHHBjPEsL6QECBJLhfsQetJ7l2I,50017
 hwpx/oxml/header_part.py,sha256=nIMsH3gHdKP_BB5g4LwFwCqmMzjnyY5y40vitQMSPwc,237
 hwpx/oxml/memo.py,sha256=BxfNt8k7_A0eUcZ3uu97t5rM5OA315pR7lCEHVkS8b8,304
 hwpx/oxml/namespaces.py,sha256=c7JfdOdJbzrhyHvjbxoeeeloRE3xPuoB7v3YI8SmKDk,6524
@@ -117,6 +117,7 @@ hwpx/tools/package_reconcile.py,sha256=y1Hl7hbPh4YaV59LTdDLzQwgn4g1qEnFmSjmajnrE
 hwpx/tools/package_validator.py,sha256=AA5wy6YgwlU6BTq1p2qCbCVCM8lmIBLhPANKCfaPb-s,29369
 hwpx/tools/page_guard.py,sha256=nDAVPcvrnuyDxVTA_j22wiYD7CXAD6XlzsMzaz3h_q8,9701
 hwpx/tools/recover.py,sha256=EOVAzMFAqR9YAT3sinZKCdjSkKygo4dKrs6T6SbGA7o,4963
+hwpx/tools/redline.py,sha256=p6aMVDBOrkqywlrlxqhB-5ZjCEtgrCNa8cYeRMJlprk,6478
 hwpx/tools/repair.py,sha256=wYO4Zd8ZMwkbYy2_EPz0eyqvTCrzcAyvbEsVE1P87Zk,11197
 hwpx/tools/report_parser.py,sha256=3Daqn2hqIcj5pG1qUxeYbvWr7CvdhwzatWvxCCcnSZg,4307
 hwpx/tools/report_utils.py,sha256=6HYEeQc3ZxTpxbwF11s47uZ-KmV4tsHPE1MV4491KDE,4434
@@ -145,10 +146,10 @@ hwpx/visual/diff.py,sha256=0X5T9IgwRZU3td-7vnPrlowovtGud7P_ymq0KVehlKk,5677
 hwpx/visual/masks.py,sha256=oXhgynAb4uKjJtZ2BGHHdAjyvWGqSFlZFQ-iJxzHiuo,1832
 hwpx/visual/oracle.py,sha256=QXAyc0xVIjLPWUHM2rBjsustQTmwfoW2Xkb9iX9ai2E,21786
 hwpx/visual/report.py,sha256=2RhXN1KBYOZTim9FNpeUhaaDHR7oFxI6Z2DLUkDIiwE,1717
-python_hwpx-2.16.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-2.16.0.dist-info/licenses/NOTICE,sha256=k48h6EaGQE8Y1c0dS9sIOOcz4YqkbcImWClF7pBOgsg,2473
-python_hwpx-2.16.0.dist-info/METADATA,sha256=drWhBw2ZwdxyyKj2OkCcY_rUZWYNyFlBr-cIoC1vaNs,19982
-python_hwpx-2.16.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_hwpx-2.16.0.dist-info/entry_points.txt,sha256=4U6WXYWHxEiWp2VRHo97fvOYNh7ebu6roonk7chxKcY,453
-python_hwpx-2.16.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-2.16.0.dist-info/RECORD,,
+python_hwpx-2.17.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
+python_hwpx-2.17.0.dist-info/licenses/NOTICE,sha256=k48h6EaGQE8Y1c0dS9sIOOcz4YqkbcImWClF7pBOgsg,2473
+python_hwpx-2.17.0.dist-info/METADATA,sha256=PnLwDDOUcJkC-b4pK-qryUc1p5ru2zbssEpBfhmjaV0,19982
+python_hwpx-2.17.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_hwpx-2.17.0.dist-info/entry_points.txt,sha256=4U6WXYWHxEiWp2VRHo97fvOYNh7ebu6roonk7chxKcY,453
+python_hwpx-2.17.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-2.17.0.dist-info/RECORD,,