python-hwpx 1.3__tar.gz → 1.4__tar.gz

{python-hwpx-1.3/src/python_hwpx.egg-info → python-hwpx-1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-hwpx
-Version: 1.3
+Version: 1.4
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License: Non-Commercial License
@@ -39,6 +39,7 @@ Requires-Dist: pytest>=7.4; extra == "test"
 - **타입이 지정된 본문 모델** – `hwpx.oxml.body`는 표·컨트롤·인라인 도형·변경 추적 태그를 데이터 클래스에 매핑하고, `HwpxOxmlParagraph.model`/`HwpxOxmlRun.model`로 이를 조회·수정한 뒤 XML로 되돌릴 수 있도록 지원합니다.
 - **메모와 필드 앵커** – `add_memo_with_anchor()`로 메모를 생성하면서 MEMO 필드 컨트롤을 자동 삽입해 한/글에서 바로 표시되도록 합니다.
 - **헤더 참조 목록 탐색** – 글머리표, 문단 속성, 스타일, 변경 추적 항목, 작성자 정보를 데이터클래스로 파싱하고 `document.bullets`·`document.styles` 같은 조회 헬퍼로 ID 기반 검색을 단순화했습니다.
+- **바탕쪽·이력·버전 파트 제어** – 매니페스트에 포함된 master-page/history/version 파트를 `document.master_pages`, `document.histories`, `document.version`으로 직접 편집하고 저장합니다.
 - **스타일 기반 텍스트 치환** – 런 서식(색상, 밑줄, `charPrIDRef`)으로 필터링해 텍스트를 선택적으로 교체하거나 삭제합니다. 하이라이트
   마커나 태그로 분리된 문자열도 서식을 유지한 채 치환합니다.
 - **텍스트 추출 파이프라인** – `hwpx.tools.text_extractor.TextExtractor`는 하이라이트, 각주, 컨트롤을 원하는 방식으로 표현하며 문단 텍스트를 반환합니다.

{python-hwpx-1.3 → python-hwpx-1.4}/README.md

@@ -9,6 +9,7 @@
 - **타입이 지정된 본문 모델** – `hwpx.oxml.body`는 표·컨트롤·인라인 도형·변경 추적 태그를 데이터 클래스에 매핑하고, `HwpxOxmlParagraph.model`/`HwpxOxmlRun.model`로 이를 조회·수정한 뒤 XML로 되돌릴 수 있도록 지원합니다.
 - **메모와 필드 앵커** – `add_memo_with_anchor()`로 메모를 생성하면서 MEMO 필드 컨트롤을 자동 삽입해 한/글에서 바로 표시되도록 합니다.
 - **헤더 참조 목록 탐색** – 글머리표, 문단 속성, 스타일, 변경 추적 항목, 작성자 정보를 데이터클래스로 파싱하고 `document.bullets`·`document.styles` 같은 조회 헬퍼로 ID 기반 검색을 단순화했습니다.
+- **바탕쪽·이력·버전 파트 제어** – 매니페스트에 포함된 master-page/history/version 파트를 `document.master_pages`, `document.histories`, `document.version`으로 직접 편집하고 저장합니다.
 - **스타일 기반 텍스트 치환** – 런 서식(색상, 밑줄, `charPrIDRef`)으로 필터링해 텍스트를 선택적으로 교체하거나 삭제합니다. 하이라이트
   마커나 태그로 분리된 문자열도 서식을 유지한 채 치환합니다.
 - **텍스트 추출 파이프라인** – `hwpx.tools.text_extractor.TextExtractor`는 하이라이트, 각주, 컨트롤을 원하는 방식으로 표현하며 문단 텍스트를 반환합니다.

{python-hwpx-1.3 → python-hwpx-1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "1.3"
+version = "1.4"
 description = "Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "Non-Commercial License" }

{python-hwpx-1.3 → python-hwpx-1.4}/src/hwpx/document.py

@@ -13,13 +13,16 @@ from .oxml import (
     Bullet,
     HwpxOxmlDocument,
     HwpxOxmlHeader,
+    HwpxOxmlHistory,
     HwpxOxmlInlineObject,
+    HwpxOxmlMasterPage,
     HwpxOxmlMemo,
     HwpxOxmlParagraph,
     HwpxOxmlRun,
     HwpxOxmlSection,
     HwpxOxmlSectionHeaderFooter,
     HwpxOxmlTable,
+    HwpxOxmlVersion,
     MemoShape,
     ParagraphProperty,
     RunStyle,
@@ -89,6 +92,21 @@ class HwpxDocument:
         """Return the header parts referenced by the document."""
         return self._root.headers
 
+    @property
+    def master_pages(self) -> List[HwpxOxmlMasterPage]:
+        """Return the master-page parts declared in the manifest."""
+        return self._root.master_pages
+
+    @property
+    def histories(self) -> List[HwpxOxmlHistory]:
+        """Return document history parts referenced by the manifest."""
+        return self._root.histories
+
+    @property
+    def version(self) -> HwpxOxmlVersion | None:
+        """Return the version metadata part if present."""
+        return self._root.version
+
     @property
     def memo_shapes(self) -> dict[str, MemoShape]:
         """Return memo shapes available in the header reference lists."""

{python-hwpx-1.3 → python-hwpx-1.4}/src/hwpx/oxml/__init__.py

@@ -19,7 +19,9 @@ from .document import (
     DocumentNumbering,
     HwpxOxmlDocument,
     HwpxOxmlHeader,
+    HwpxOxmlHistory,
     HwpxOxmlInlineObject,
+    HwpxOxmlMasterPage,
     HwpxOxmlMemo,
     HwpxOxmlMemoGroup,
     HwpxOxmlParagraph,
@@ -30,6 +32,7 @@ from .document import (
     HwpxOxmlTable,
     HwpxOxmlTableCell,
     HwpxOxmlTableRow,
+    HwpxOxmlVersion,
     PageMargins,
     PageSize,
     RunStyle,
@@ -126,7 +129,9 @@ __all__ = [
     "DocumentNumbering",
     "HwpxOxmlDocument",
     "HwpxOxmlHeader",
+    "HwpxOxmlHistory",
     "HwpxOxmlInlineObject",
+    "HwpxOxmlMasterPage",
     "HwpxOxmlMemo",
     "HwpxOxmlMemoGroup",
     "HwpxOxmlParagraph",
@@ -137,6 +142,7 @@ __all__ = [
     "HwpxOxmlTable",
     "HwpxOxmlTableCell",
     "HwpxOxmlTableRow",
+    "HwpxOxmlVersion",
     "KeyDerivation",
     "KeyEncryption",
     "LinkInfo",

{python-hwpx-1.3 → python-hwpx-1.4}/src/hwpx/oxml/document.py

@@ -1999,6 +1999,61 @@ class HwpxOxmlParagraph:
             self.section.mark_dirty()
 
 
+class _HwpxOxmlSimplePart:
+    """Common base for standalone XML parts that are not sections or headers."""
+
+    def __init__(
+        self,
+        part_name: str,
+        element: ET.Element,
+        document: "HwpxOxmlDocument" | None = None,
+    ):
+        self.part_name = part_name
+        self._element = element
+        self._document = document
+        self._dirty = False
+
+    @property
+    def element(self) -> ET.Element:
+        return self._element
+
+    @property
+    def document(self) -> "HwpxOxmlDocument" | None:
+        return self._document
+
+    def attach_document(self, document: "HwpxOxmlDocument") -> None:
+        self._document = document
+
+    @property
+    def dirty(self) -> bool:
+        return self._dirty
+
+    def mark_dirty(self) -> None:
+        self._dirty = True
+
+    def reset_dirty(self) -> None:
+        self._dirty = False
+
+    def replace_element(self, element: ET.Element) -> None:
+        self._element = element
+        self.mark_dirty()
+
+    def to_bytes(self) -> bytes:
+        return _serialize_xml(self._element)
+
+
+class HwpxOxmlMasterPage(_HwpxOxmlSimplePart):
+    """Represents a master page part in the package."""
+
+
+class HwpxOxmlHistory(_HwpxOxmlSimplePart):
+    """Represents a document history part."""
+
+
+class HwpxOxmlVersion(_HwpxOxmlSimplePart):
+    """Represents the ``version.xml`` part."""
+
+
 class HwpxOxmlSection:
     """Represents the contents of a section XML part."""
 
@@ -2540,16 +2595,29 @@ class HwpxOxmlDocument:
         manifest: ET.Element,
         sections: Sequence[HwpxOxmlSection],
         headers: Sequence[HwpxOxmlHeader],
+        *,
+        master_pages: Sequence[HwpxOxmlMasterPage] | None = None,
+        histories: Sequence[HwpxOxmlHistory] | None = None,
+        version: HwpxOxmlVersion | None = None,
     ):
         self._manifest = manifest
         self._sections = list(sections)
         self._headers = list(headers)
+        self._master_pages = list(master_pages or [])
+        self._histories = list(histories or [])
+        self._version = version
         self._char_property_cache: dict[str, RunStyle] | None = None
 
         for section in self._sections:
             section.attach_document(self)
         for header in self._headers:
             header.attach_document(self)
+        for master_page in self._master_pages:
+            master_page.attach_document(self)
+        for history in self._histories:
+            history.attach_document(self)
+        if self._version is not None:
+            self._version.attach_document(self)
 
     @classmethod
     def from_package(cls, package: "HwpxPackage") -> "HwpxOxmlDocument":
@@ -2561,12 +2629,35 @@ class HwpxOxmlDocument:
         manifest = package.get_xml(package.MANIFEST_PATH)
         section_paths = package.section_paths()
         header_paths = package.header_paths()
+        master_page_paths = package.master_page_paths()
+        history_paths = package.history_paths()
+        version_path = package.version_path()
 
         sections = [
             HwpxOxmlSection(path, package.get_xml(path)) for path in section_paths
         ]
         headers = [HwpxOxmlHeader(path, package.get_xml(path)) for path in header_paths]
-        return cls(manifest, sections, headers)
+        master_pages = [
+            HwpxOxmlMasterPage(path, package.get_xml(path))
+            for path in master_page_paths
+            if package.has_part(path)
+        ]
+        histories = [
+            HwpxOxmlHistory(path, package.get_xml(path))
+            for path in history_paths
+            if package.has_part(path)
+        ]
+        version = None
+        if version_path and package.has_part(version_path):
+            version = HwpxOxmlVersion(version_path, package.get_xml(version_path))
+        return cls(
+            manifest,
+            sections,
+            headers,
+            master_pages=master_pages,
+            histories=histories,
+            version=version,
+        )
 
     @property
     def manifest(self) -> ET.Element:
@@ -2580,6 +2671,18 @@ class HwpxOxmlDocument:
     def headers(self) -> List[HwpxOxmlHeader]:
         return list(self._headers)
 
+    @property
+    def master_pages(self) -> List[HwpxOxmlMasterPage]:
+        return list(self._master_pages)
+
+    @property
+    def histories(self) -> List[HwpxOxmlHistory]:
+        return list(self._histories)
+
+    @property
+    def version(self) -> HwpxOxmlVersion | None:
+        return self._version
+
     def _ensure_char_property_cache(self) -> dict[str, RunStyle]:
         if self._char_property_cache is None:
             mapping: dict[str, RunStyle] = {}
@@ -2812,6 +2915,14 @@ class HwpxOxmlDocument:
                 headers_dirty = True
         if headers_dirty:
             self.invalidate_char_property_cache()
+        for master_page in self._master_pages:
+            if master_page.dirty:
+                updates[master_page.part_name] = master_page.to_bytes()
+        for history in self._histories:
+            if history.dirty:
+                updates[history.part_name] = history.to_bytes()
+        if self._version is not None and self._version.dirty:
+            updates[self._version.part_name] = self._version.to_bytes()
         return updates
 
     def reset_dirty(self) -> None:
@@ -2820,3 +2931,9 @@ class HwpxOxmlDocument:
             section.reset_dirty()
         for header in self._headers:
             header.reset_dirty()
+        for master_page in self._master_pages:
+            master_page.reset_dirty()
+        for history in self._histories:
+            history.reset_dirty()
+        if self._version is not None:
+            self._version.reset_dirty()

{python-hwpx-1.3 → python-hwpx-1.4}/src/hwpx/package.py

@@ -11,6 +11,21 @@ from zipfile import ZIP_DEFLATED, ZipFile
 _OPF_NS = "http://www.idpf.org/2007/opf/"
 
 
+def _normalized_manifest_value(element: ET.Element) -> str:
+    values = [
+        element.attrib.get("id", ""),
+        element.attrib.get("href", ""),
+        element.attrib.get("media-type", ""),
+        element.attrib.get("properties", ""),
+    ]
+    return " ".join(part.lower() for part in values if part)
+
+
+def _manifest_matches(element: ET.Element, *candidates: str) -> bool:
+    normalized = _normalized_manifest_value(element)
+    return any(candidate in normalized for candidate in candidates if candidate)
+
+
 def _ensure_bytes(value: bytes | str | ET.Element) -> bytes:
     if isinstance(value, bytes):
         return value
@@ -38,6 +53,10 @@ class HwpxPackage:
         self._spine_cache: list[str] | None = None
         self._section_paths_cache: list[str] | None = None
         self._header_paths_cache: list[str] | None = None
+        self._master_page_paths_cache: list[str] | None = None
+        self._history_paths_cache: list[str] | None = None
+        self._version_path_cache: str | None = None
+        self._version_path_cache_resolved = False
 
     # -- construction ----------------------------------------------------
     @classmethod
@@ -85,6 +104,12 @@ class HwpxPackage:
             self._spine_cache = None
             self._section_paths_cache = None
             self._header_paths_cache = None
+            self._master_page_paths_cache = None
+            self._history_paths_cache = None
+            self._version_path_cache = None
+            self._version_path_cache_resolved = False
+        elif part_name == "version.xml":
+            self._version_path_cache_resolved = False
 
     def get_xml(self, part_name: str) -> ET.Element:
         return ET.fromstring(self.get_part(part_name))
@@ -101,6 +126,11 @@ class HwpxPackage:
             self._manifest_tree = self.get_xml(self.MANIFEST_PATH)
         return self._manifest_tree
 
+    def _manifest_items(self) -> list[ET.Element]:
+        manifest = self.manifest_tree()
+        ns = {"opf": _OPF_NS}
+        return list(manifest.findall("./opf:manifest/opf:item", ns))
+
     def _resolve_spine_paths(self) -> list[str]:
         if self._spine_cache is None:
             manifest = self.manifest_tree()
@@ -155,6 +185,64 @@ class HwpxPackage:
             self._header_paths_cache = paths
         return list(self._header_paths_cache)
 
+    def master_page_paths(self) -> list[str]:
+        if self._master_page_paths_cache is None:
+            from pathlib import PurePosixPath
+
+            paths = [
+                item.attrib.get("href", "")
+                for item in self._manifest_items()
+                if _manifest_matches(item, "masterpage", "master-page")
+                and item.attrib.get("href")
+            ]
+
+            if not paths:
+                paths = [
+                    name
+                    for name in self._parts.keys()
+                    if "master" in PurePosixPath(name).name.lower()
+                    and "page" in PurePosixPath(name).name.lower()
+                ]
+
+            self._master_page_paths_cache = paths
+        return list(self._master_page_paths_cache)
+
+    def history_paths(self) -> list[str]:
+        if self._history_paths_cache is None:
+            from pathlib import PurePosixPath
+
+            paths = [
+                item.attrib.get("href", "")
+                for item in self._manifest_items()
+                if _manifest_matches(item, "history")
+                and item.attrib.get("href")
+            ]
+
+            if not paths:
+                paths = [
+                    name
+                    for name in self._parts.keys()
+                    if "history" in PurePosixPath(name).name.lower()
+                ]
+
+            self._history_paths_cache = paths
+        return list(self._history_paths_cache)
+
+    def version_path(self) -> str | None:
+        if not self._version_path_cache_resolved:
+            path: str | None = None
+            for item in self._manifest_items():
+                if _manifest_matches(item, "version"):
+                    href = item.attrib.get("href", "").strip()
+                    if href:
+                        path = href
+                        break
+            if path is None and self.has_part("version.xml"):
+                path = "version.xml"
+            self._version_path_cache = path
+            self._version_path_cache_resolved = True
+        return self._version_path_cache
+
     # -- saving ----------------------------------------------------------
     def save(
         self,

{python-hwpx-1.3 → python-hwpx-1.4/src/python_hwpx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-hwpx
-Version: 1.3
+Version: 1.4
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License: Non-Commercial License
@@ -39,6 +39,7 @@ Requires-Dist: pytest>=7.4; extra == "test"
 - **타입이 지정된 본문 모델** – `hwpx.oxml.body`는 표·컨트롤·인라인 도형·변경 추적 태그를 데이터 클래스에 매핑하고, `HwpxOxmlParagraph.model`/`HwpxOxmlRun.model`로 이를 조회·수정한 뒤 XML로 되돌릴 수 있도록 지원합니다.
 - **메모와 필드 앵커** – `add_memo_with_anchor()`로 메모를 생성하면서 MEMO 필드 컨트롤을 자동 삽입해 한/글에서 바로 표시되도록 합니다.
 - **헤더 참조 목록 탐색** – 글머리표, 문단 속성, 스타일, 변경 추적 항목, 작성자 정보를 데이터클래스로 파싱하고 `document.bullets`·`document.styles` 같은 조회 헬퍼로 ID 기반 검색을 단순화했습니다.
+- **바탕쪽·이력·버전 파트 제어** – 매니페스트에 포함된 master-page/history/version 파트를 `document.master_pages`, `document.histories`, `document.version`으로 직접 편집하고 저장합니다.
 - **스타일 기반 텍스트 치환** – 런 서식(색상, 밑줄, `charPrIDRef`)으로 필터링해 텍스트를 선택적으로 교체하거나 삭제합니다. 하이라이트
   마커나 태그로 분리된 문자열도 서식을 유지한 채 치환합니다.
 - **텍스트 추출 파이프라인** – `hwpx.tools.text_extractor.TextExtractor`는 하이라이트, 각주, 컨트롤을 원하는 방식으로 표현하며 문단 텍스트를 반환합니다.

{python-hwpx-1.3 → python-hwpx-1.4}/tests/test_integration_hwpx_compatibility.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import io
+import xml.etree.ElementTree as ET
 from pathlib import Path
 from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
 
@@ -9,6 +10,7 @@ import pytest
 from hwpx.document import HwpxDocument
 from hwpx.package import HwpxPackage
 from hwpx.tools import load_default_schemas, validate_document
+from hwpx.templates import blank_document_bytes
 
 _MIMETYPE = b"application/hwp+zip"
 _VERSION_XML = (
@@ -137,3 +139,90 @@ def test_fixture_validates_against_reference_schemas(
 
     bytes_report = validate_document(sample_document_bytes)
     assert bytes_report.ok, "Generated sample failed schema validation from bytes"
+
+
+def test_master_page_history_and_version_round_trip(tmp_path: Path) -> None:
+    package = HwpxPackage.open(blank_document_bytes())
+
+    manifest = package.manifest_tree()
+    ns = {"opf": "http://www.idpf.org/2007/opf/"}
+    manifest_list = manifest.find(f"{{{ns['opf']}}}manifest")
+    assert manifest_list is not None
+
+    def add_manifest_item(item_id: str, href: str) -> None:
+        ET.SubElement(
+            manifest_list,
+            f"{{{ns['opf']}}}item",
+            {"id": item_id, "href": href, "media-type": "application/xml"},
+        )
+
+    add_manifest_item("master-page-0", "Contents/masterPages/masterPage0.xml")
+    add_manifest_item("history", "Contents/history.xml")
+    add_manifest_item("version", "version.xml")
+    package.set_xml(package.MANIFEST_PATH, manifest)
+
+    hm_ns = "http://www.hancom.co.kr/hwpml/2011/master-page"
+    master_root = ET.Element(f"{{{hm_ns}}}masterPage")
+    ET.SubElement(
+        master_root,
+        f"{{{hm_ns}}}masterPageItem",
+        {"id": "0", "type": "BOTH", "name": "초기 바탕쪽"},
+    )
+    package.set_xml("Contents/masterPages/masterPage0.xml", master_root)
+
+    hhs_ns = "http://www.hancom.co.kr/hwpml/2011/history"
+    history_root = ET.Element(f"{{{hhs_ns}}}history")
+    history_entry = ET.SubElement(history_root, f"{{{hhs_ns}}}historyEntry", {"id": "0"})
+    comment = ET.SubElement(history_entry, f"{{{hhs_ns}}}comment")
+    comment.text = "초기 내역"
+    package.set_xml("Contents/history.xml", history_root)
+
+    document = HwpxDocument.from_package(package)
+
+    assert len(document.master_pages) == 1
+    assert len(document.histories) == 1
+    version_part = document.version
+    assert version_part is not None
+
+    master_page = document.master_pages[0]
+    master_item = master_page.element.find(f"{{{hm_ns}}}masterPageItem")
+    assert master_item is not None
+    master_item.set("name", "검토용 바탕쪽")
+    master_page.mark_dirty()
+
+    history_part = document.histories[0]
+    history_comment = history_part.element.find(
+        f"{{{hhs_ns}}}historyEntry/{{{hhs_ns}}}comment"
+    )
+    assert history_comment is not None
+    history_comment.text = "업데이트된 변경 기록"
+    history_part.mark_dirty()
+
+    version_part.element.set("appVersion", "15.0.0.100 WIN32")
+    version_part.mark_dirty()
+
+    output_path = tmp_path / "master_history_roundtrip.hwpx"
+    document.save(output_path)
+
+    reopened = HwpxDocument.open(output_path)
+    assert reopened.master_pages
+    assert reopened.histories
+    reopened_version = reopened.version
+    assert reopened_version is not None
+
+    reopened_master_item = reopened.master_pages[0].element.find(
+        f"{{{hm_ns}}}masterPageItem"
+    )
+    assert reopened_master_item is not None
+    assert reopened_master_item.get("name") == "검토용 바탕쪽"
+
+    reopened_history_comment = reopened.histories[0].element.find(
+        f"{{{hhs_ns}}}historyEntry/{{{hhs_ns}}}comment"
+    )
+    assert reopened_history_comment is not None
+    assert reopened_history_comment.text == "업데이트된 변경 기록"
+
+    assert reopened_version.element.get("appVersion") == "15.0.0.100 WIN32"
+    assert "Contents/masterPages/masterPage0.xml" in reopened.package.master_page_paths()
+    assert "Contents/history.xml" in reopened.package.history_paths()
+    assert reopened.package.version_path() == "version.xml"