python-hwpx 2.8__tar.gz → 2.8.2__tar.gz

{python_hwpx-2.8 → python_hwpx-2.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 2.8
+Version: 2.8.2
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License: Non-Commercial License
@@ -80,8 +80,9 @@ Dynamic: license-file
 
 ---
 
-`python-hwpx`는 한컴오피스의 [HWPX 포맷](https://www.hancom.com/)을 순수 Python으로 다루는 라이브러리입니다.
+`python-hwpx`는 한컴오피스의 [HWPX 포맷](https://www.hancom.com/)을 순수 Python으로 다루는 라이브러리이자 CLI 도구 모음입니다.
 한/글 설치 없이, OS에 관계없이 HWPX 문서의 구조를 파싱하고 콘텐츠를 조작할 수 있습니다.
+문서 편집 API뿐 아니라 스키마/패키지 검증, unpack/pack, 템플릿 분석 같은 XML-first 워크플로도 함께 제공합니다.
 
 > **pyhwpx / pyhwp와 다른 점?**
 > | | python-hwpx | pyhwpx | pyhwp |
@@ -93,7 +94,7 @@ Dynamic: license-file
 
 ## 🌍 크로스 플랫폼 지원
 
-HWPX 파일은 **ZIP + XML** 구조이므로, 한/글 프로그램 없이 Python만으로 완벽하게 읽고 쓸 수 있습니다.
+HWPX 파일은 **ZIP + XML** 구조이므로, 한/글 프로그램 없이 Python만으로 읽고 편집하는 워크플로를 구성할 수 있습니다.
 
 | 플랫폼 | 읽기 | 쓰기 | 비고 |
 |--------|------|------|------|
@@ -115,14 +116,14 @@ pip install python-hwpx
 ```python
 from hwpx import HwpxDocument
 
-# 기존 문서 열기
-doc = HwpxDocument.open("보고서.hwpx")
-
 # 빈 문서 새로 만들기
 doc = HwpxDocument.new()
 
+# 기존 문서를 수정하려면:
+# doc = HwpxDocument.open("보고서.hwpx")
+
 # 문단 추가
-doc.add_paragraph("python-hwpx로 생성한 문단입니다.")
+paragraph = doc.add_paragraph("python-hwpx로 생성한 문단입니다.")
 
 # 표 추가 (2×3)
 table = doc.add_table(rows=2, cols=3)
@@ -130,9 +131,8 @@ table.set_cell_text(0, 0, "이름")
 table.set_cell_text(0, 1, "부서")
 table.set_cell_text(0, 2, "연락처")
 
-# 메모 추가 (한/글에서 바로 표시)
-paragraph = doc.paragraphs[0]
-doc.add_memo_with_anchor("검토 필요", paragraph=paragraph)
+# 메모 추가 (기본 템플릿의 memo shape 사용)
+doc.add_memo_with_anchor("검토 필요", paragraph=paragraph, memo_shape_id_ref="0")
 
 # 저장
 doc.save_to_path("결과물.hwpx")
@@ -166,7 +166,7 @@ doc.save_to_path("결과물.hwpx")
 | 🎨 **스타일 치환** | 서식 기반 필터 | 색상/밑줄/charPrIDRef 기반 Run 검색 및 교체 |
 | 📤 **내보내기** | 텍스트/HTML/Markdown | 문서 변환 출력 |
 | ✅ **유효성 검사** | XSD + 패키지 구조 | CLI(`hwpx-validate`, `hwpx-validate-package`) 및 API |
-| 🧰 **워크플로 도구** | unpack/pack/template analyze/page guard | 템플릿 보존형 XML-first 작업 보조 |
+| 🧰 **작업 도구** | unpack/pack/분석/비교 | pack-ready 작업 디렉터리 추출과 재구성 점검 |
 | 🏗️ **저수준 XML** | 데이터클래스 매핑 | OWPML 스키마 ↔ Python 객체 직접 조작 |
 | 🔄 **네임스페이스 호환** | 자동 정규화 | HWPML 2016 → 2011 자동 변환 |
 
@@ -174,7 +174,7 @@ doc.save_to_path("결과물.hwpx")
 
 ### 📄 문서 편집
 
-문단, 표, 메모, 머리말/꼬리말을 Python 객체로 다룹니다.
+문단, 표, 메모, 머리글/바닥글을 Python 객체로 다룹니다.
 
 ```python
 # 단락 추가·삭제
@@ -186,9 +186,9 @@ new_sec = doc.add_section()          # 문서 끝에 섹션 추가
 new_sec.add_paragraph("두 번째 섹션 내용")
 doc.remove_section(1)                # 인덱스로 섹션 삭제
 
-# 머리말·꼬리말
+# 머리글·바닥글
 doc.set_header_text("기밀 문서", page_type="BOTH")
-doc.set_footer_text("— 1 —", page_type="BOTH")
+doc.set_footer_text("1 / 10", page_type="BOTH")
 
 # 표 셀 병합·분할
 table.merge_cells(0, 0, 1, 1)   # (0,0)~(1,1) 병합
@@ -201,13 +201,14 @@ table.set_cell_text(0, 0, "병합된 셀", logical=True, split_merged=True)
 from hwpx import TextExtractor, ObjectFinder
 
 # 텍스트 추출
-for section in TextExtractor("문서.hwpx"):
-    for para in section.paragraphs:
-        print(para.text)
+with TextExtractor("문서.hwpx") as extractor:
+    for section in extractor.iter_sections():
+        for para in extractor.iter_paragraphs(section):
+            print(para.text())
 
 # 특정 객체 탐색
-for obj in ObjectFinder("문서.hwpx").find("tbl"):
-    print(obj.tag, obj.attributes)
+for obj in ObjectFinder("문서.hwpx").find_all(tag="tbl"):
+    print(obj.tag, obj.path)
 ```
 
 ### 🎨 스타일 기반 텍스트 치환
@@ -270,7 +271,7 @@ python-hwpx
 │   ├── exporter         #   텍스트/HTML/Markdown 내보내기
 │   ├── validator        #   스키마 유효성 검사 (hwpx-validate CLI)
 │   ├── package_validator#   ZIP/OPC/HWPX 구조 검사
-│   ├── page_guard       #   layout-drift proxy
+│   ├── page_guard       #   구조 변화 징후 점검
 │   └── template_analyzer#   레퍼런스 문서 분석/추출
 └── hwpx.templates       # 내장 빈 문서 템플릿
 ```
@@ -289,7 +290,7 @@ hwpx-unpack 문서.hwpx ./unpacked
 hwpx-unpack 문서.hwpx ./pretty-unpacked --pretty-xml
 hwpx-pack ./unpacked ./repacked.hwpx
 
-# 레퍼런스 템플릿 분석과 pack-ready 추출
+# 레퍼런스 문서 분석과 작업 디렉터리 추출
 hwpx-analyze-template 문서.hwpx --extract-dir ./template-parts --json
 hwpx-pack ./template-parts ./template-roundtrip.hwpx
 hwpx-validate-package ./template-roundtrip.hwpx
@@ -297,15 +298,15 @@ hwpx-validate-package ./template-roundtrip.hwpx
 # plain / markdown 텍스트 추출
 hwpx-text-extract 문서.hwpx --format markdown --output 문서.md
 
-# 레이아웃 드리프트 프록시 비교
+# 문서 구조 변화 징후 비교
 hwpx-page-guard --reference 원본.hwpx --output 결과.hwpx
 ```
 
-`hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 통계를 비교해 레이아웃 드리프트 위험을 탐지하는 프록시 도구입니다.
+`hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 같은 구조 지표를 비교해 편집 전후 변화 징후를 빠르게 점검합니다.
 
-`hwpx-validate-package`는 `Contents/content.hpf` 같은 고정 경로를 강제하지 않고, `META-INF/container.xml`과 선택된 rootfile/manifest 관계를 따라가며 검사합니다. 엔진이 fallback으로 열 수 있는 비표준 패키지는 가능한 경우 경고로 구분합니다.
+`hwpx-validate-package`는 `Contents/content.hpf` 같은 고정 경로를 전제로 두지 않고, `META-INF/container.xml`과 실제 rootfile/manifest 선언을 따라가며 패키지 구조를 확인합니다. 엔진이 열 수 있는 비표준 패키지는 가능한 경우 경고로 분리해 보여줍니다.
 
-`hwpx-analyze-template --extract-dir`는 covered fixture 기준으로 `hwpx-pack`과 `hwpx-validate-package`, 그리고 엔진 open 경로에 다시 투입할 수 있는 pack-ready 작업 디렉터리를 만듭니다. 이건 재패킹 가능성을 목표로 한 것이지, 렌더링 fidelity를 보장한다는 뜻은 아닙니다.
+`hwpx-analyze-template --extract-dir`는 다시 묶고 점검하기 쉬운 작업 디렉터리를 만듭니다. 재구성과 구조 검증에 필요한 파일을 함께 꺼내는 용도이며, 편집기에서의 최종 렌더링 결과까지 보장한다는 뜻은 아닙니다.
 
 ## 문서
 

{python_hwpx-2.8 → python_hwpx-2.8.2}/README.md

@@ -13,8 +13,9 @@
 
 ---
 
-`python-hwpx`는 한컴오피스의 [HWPX 포맷](https://www.hancom.com/)을 순수 Python으로 다루는 라이브러리입니다.
+`python-hwpx`는 한컴오피스의 [HWPX 포맷](https://www.hancom.com/)을 순수 Python으로 다루는 라이브러리이자 CLI 도구 모음입니다.
 한/글 설치 없이, OS에 관계없이 HWPX 문서의 구조를 파싱하고 콘텐츠를 조작할 수 있습니다.
+문서 편집 API뿐 아니라 스키마/패키지 검증, unpack/pack, 템플릿 분석 같은 XML-first 워크플로도 함께 제공합니다.
 
 > **pyhwpx / pyhwp와 다른 점?**
 > | | python-hwpx | pyhwpx | pyhwp |
@@ -26,7 +27,7 @@
 
 ## 🌍 크로스 플랫폼 지원
 
-HWPX 파일은 **ZIP + XML** 구조이므로, 한/글 프로그램 없이 Python만으로 완벽하게 읽고 쓸 수 있습니다.
+HWPX 파일은 **ZIP + XML** 구조이므로, 한/글 프로그램 없이 Python만으로 읽고 편집하는 워크플로를 구성할 수 있습니다.
 
 | 플랫폼 | 읽기 | 쓰기 | 비고 |
 |--------|------|------|------|
@@ -48,14 +49,14 @@ pip install python-hwpx
 ```python
 from hwpx import HwpxDocument
 
-# 기존 문서 열기
-doc = HwpxDocument.open("보고서.hwpx")
-
 # 빈 문서 새로 만들기
 doc = HwpxDocument.new()
 
+# 기존 문서를 수정하려면:
+# doc = HwpxDocument.open("보고서.hwpx")
+
 # 문단 추가
-doc.add_paragraph("python-hwpx로 생성한 문단입니다.")
+paragraph = doc.add_paragraph("python-hwpx로 생성한 문단입니다.")
 
 # 표 추가 (2×3)
 table = doc.add_table(rows=2, cols=3)
@@ -63,9 +64,8 @@ table.set_cell_text(0, 0, "이름")
 table.set_cell_text(0, 1, "부서")
 table.set_cell_text(0, 2, "연락처")
 
-# 메모 추가 (한/글에서 바로 표시)
-paragraph = doc.paragraphs[0]
-doc.add_memo_with_anchor("검토 필요", paragraph=paragraph)
+# 메모 추가 (기본 템플릿의 memo shape 사용)
+doc.add_memo_with_anchor("검토 필요", paragraph=paragraph, memo_shape_id_ref="0")
 
 # 저장
 doc.save_to_path("결과물.hwpx")
@@ -99,7 +99,7 @@ doc.save_to_path("결과물.hwpx")
 | 🎨 **스타일 치환** | 서식 기반 필터 | 색상/밑줄/charPrIDRef 기반 Run 검색 및 교체 |
 | 📤 **내보내기** | 텍스트/HTML/Markdown | 문서 변환 출력 |
 | ✅ **유효성 검사** | XSD + 패키지 구조 | CLI(`hwpx-validate`, `hwpx-validate-package`) 및 API |
-| 🧰 **워크플로 도구** | unpack/pack/template analyze/page guard | 템플릿 보존형 XML-first 작업 보조 |
+| 🧰 **작업 도구** | unpack/pack/분석/비교 | pack-ready 작업 디렉터리 추출과 재구성 점검 |
 | 🏗️ **저수준 XML** | 데이터클래스 매핑 | OWPML 스키마 ↔ Python 객체 직접 조작 |
 | 🔄 **네임스페이스 호환** | 자동 정규화 | HWPML 2016 → 2011 자동 변환 |
 
@@ -107,7 +107,7 @@ doc.save_to_path("결과물.hwpx")
 
 ### 📄 문서 편집
 
-문단, 표, 메모, 머리말/꼬리말을 Python 객체로 다룹니다.
+문단, 표, 메모, 머리글/바닥글을 Python 객체로 다룹니다.
 
 ```python
 # 단락 추가·삭제
@@ -119,9 +119,9 @@ new_sec = doc.add_section()          # 문서 끝에 섹션 추가
 new_sec.add_paragraph("두 번째 섹션 내용")
 doc.remove_section(1)                # 인덱스로 섹션 삭제
 
-# 머리말·꼬리말
+# 머리글·바닥글
 doc.set_header_text("기밀 문서", page_type="BOTH")
-doc.set_footer_text("— 1 —", page_type="BOTH")
+doc.set_footer_text("1 / 10", page_type="BOTH")
 
 # 표 셀 병합·분할
 table.merge_cells(0, 0, 1, 1)   # (0,0)~(1,1) 병합
@@ -134,13 +134,14 @@ table.set_cell_text(0, 0, "병합된 셀", logical=True, split_merged=True)
 from hwpx import TextExtractor, ObjectFinder
 
 # 텍스트 추출
-for section in TextExtractor("문서.hwpx"):
-    for para in section.paragraphs:
-        print(para.text)
+with TextExtractor("문서.hwpx") as extractor:
+    for section in extractor.iter_sections():
+        for para in extractor.iter_paragraphs(section):
+            print(para.text())
 
 # 특정 객체 탐색
-for obj in ObjectFinder("문서.hwpx").find("tbl"):
-    print(obj.tag, obj.attributes)
+for obj in ObjectFinder("문서.hwpx").find_all(tag="tbl"):
+    print(obj.tag, obj.path)
 ```
 
 ### 🎨 스타일 기반 텍스트 치환
@@ -203,7 +204,7 @@ python-hwpx
 │   ├── exporter         #   텍스트/HTML/Markdown 내보내기
 │   ├── validator        #   스키마 유효성 검사 (hwpx-validate CLI)
 │   ├── package_validator#   ZIP/OPC/HWPX 구조 검사
-│   ├── page_guard       #   layout-drift proxy
+│   ├── page_guard       #   구조 변화 징후 점검
 │   └── template_analyzer#   레퍼런스 문서 분석/추출
 └── hwpx.templates       # 내장 빈 문서 템플릿
 ```
@@ -222,7 +223,7 @@ hwpx-unpack 문서.hwpx ./unpacked
 hwpx-unpack 문서.hwpx ./pretty-unpacked --pretty-xml
 hwpx-pack ./unpacked ./repacked.hwpx
 
-# 레퍼런스 템플릿 분석과 pack-ready 추출
+# 레퍼런스 문서 분석과 작업 디렉터리 추출
 hwpx-analyze-template 문서.hwpx --extract-dir ./template-parts --json
 hwpx-pack ./template-parts ./template-roundtrip.hwpx
 hwpx-validate-package ./template-roundtrip.hwpx
@@ -230,15 +231,15 @@ hwpx-validate-package ./template-roundtrip.hwpx
 # plain / markdown 텍스트 추출
 hwpx-text-extract 문서.hwpx --format markdown --output 문서.md
 
-# 레이아웃 드리프트 프록시 비교
+# 문서 구조 변화 징후 비교
 hwpx-page-guard --reference 원본.hwpx --output 결과.hwpx
 ```
 
-`hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 통계를 비교해 레이아웃 드리프트 위험을 탐지하는 프록시 도구입니다.
+`hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 같은 구조 지표를 비교해 편집 전후 변화 징후를 빠르게 점검합니다.
 
-`hwpx-validate-package`는 `Contents/content.hpf` 같은 고정 경로를 강제하지 않고, `META-INF/container.xml`과 선택된 rootfile/manifest 관계를 따라가며 검사합니다. 엔진이 fallback으로 열 수 있는 비표준 패키지는 가능한 경우 경고로 구분합니다.
+`hwpx-validate-package`는 `Contents/content.hpf` 같은 고정 경로를 전제로 두지 않고, `META-INF/container.xml`과 실제 rootfile/manifest 선언을 따라가며 패키지 구조를 확인합니다. 엔진이 열 수 있는 비표준 패키지는 가능한 경우 경고로 분리해 보여줍니다.
 
-`hwpx-analyze-template --extract-dir`는 covered fixture 기준으로 `hwpx-pack`과 `hwpx-validate-package`, 그리고 엔진 open 경로에 다시 투입할 수 있는 pack-ready 작업 디렉터리를 만듭니다. 이건 재패킹 가능성을 목표로 한 것이지, 렌더링 fidelity를 보장한다는 뜻은 아닙니다.
+`hwpx-analyze-template --extract-dir`는 다시 묶고 점검하기 쉬운 작업 디렉터리를 만듭니다. 재구성과 구조 검증에 필요한 파일을 함께 꺼내는 용도이며, 편집기에서의 최종 렌더링 결과까지 보장한다는 뜻은 아닙니다.
 
 ## 문서
 

{python_hwpx-2.8 → python_hwpx-2.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "2.8"
+version = "2.8.2"
 description = "Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }
@@ -89,6 +89,8 @@ files = [
     "src/hwpx/tools/template_analyzer.py",
     "src/hwpx/tools/text_extract_cli.py",
     "src/hwpx/tools/text_extractor.py",
+    "tests/template_automation/helpers.py",
+    "tests/template_automation/generate_fixtures.py",
 ]
 ignore_missing_imports = true
 
@@ -108,6 +110,8 @@ include = [
     "src/hwpx/tools/template_analyzer.py",
     "src/hwpx/tools/text_extract_cli.py",
     "src/hwpx/tools/text_extractor.py",
+    "tests/template_automation/helpers.py",
+    "tests/template_automation/generate_fixtures.py",
 ]
 pythonVersion = "3.10"
 typeCheckingMode = "basic"

{python_hwpx-2.8 → python_hwpx-2.8.2}/src/hwpx/oxml/document.py

@@ -47,6 +47,8 @@ logger = logging.getLogger(__name__)
 
 _HP_NS = "http://www.hancom.co.kr/hwpml/2011/paragraph"
 _HP = f"{{{_HP_NS}}}"
+_HS_NS = "http://www.hancom.co.kr/hwpml/2011/section"
+_HS = f"{{{_HS_NS}}}"
 _HH_NS = "http://www.hancom.co.kr/hwpml/2011/head"
 _HH = f"{{{_HH_NS}}}"
 
@@ -127,6 +129,7 @@ def _create_paragraph_element(
     style_id_ref: str | int | None = None,
     paragraph_attributes: Optional[dict[str, str]] = None,
     run_attributes: Optional[dict[str, str]] = None,
+    parent: ET.Element | None = None,
 ) -> ET.Element:
     """Return a paragraph element populated with a single run and text node."""
 
@@ -138,7 +141,10 @@ def _create_paragraph_element(
     if style_id_ref is not None:
         attrs["styleIDRef"] = str(style_id_ref)
 
-    paragraph = ET.Element(f"{_HP}p", attrs)
+    if parent is None:
+        paragraph = ET.Element(f"{_HP}p", attrs)
+    else:
+        paragraph = parent.makeelement(f"{_HP}p", attrs)
 
     run_attrs: dict[str, str] = dict(run_attributes or {})
     if char_pr_id_ref is not None:
@@ -146,8 +152,10 @@ def _create_paragraph_element(
     else:
         run_attrs.setdefault("charPrIDRef", "0")
 
-    run = ET.SubElement(paragraph, f"{_HP}run", run_attrs)
-    text_element = ET.SubElement(run, f"{_HP}t")
+    run = paragraph.makeelement(f"{_HP}run", run_attrs)
+    paragraph.append(run)
+    text_element = run.makeelement(f"{_HP}t", {})
+    run.append(text_element)
     text_element.text = text
     return paragraph
 
@@ -535,18 +543,22 @@ class HwpxOxmlSectionHeaderFooter:
     def _ensure_text_element(self) -> ET.Element:
         sublist = self.element.find(f"{_HP}subList")
         if sublist is None:
-            sublist = ET.SubElement(self.element, f"{_HP}subList", self._initial_sublist_attributes())
+            sublist = _append_child(
+                self.element,
+                f"{_HP}subList",
+                self._initial_sublist_attributes(),
+            )
         paragraph = sublist.find(f"{_HP}p")
         if paragraph is None:
             paragraph_attrs = dict(_DEFAULT_PARAGRAPH_ATTRS)
             paragraph_attrs["id"] = _paragraph_id()
-            paragraph = ET.SubElement(sublist, f"{_HP}p", paragraph_attrs)
+            paragraph = _append_child(sublist, f"{_HP}p", paragraph_attrs)
         run = paragraph.find(f"{_HP}run")
         if run is None:
-            run = ET.SubElement(paragraph, f"{_HP}run", {"charPrIDRef": "0"})
+            run = _append_child(paragraph, f"{_HP}run", {"charPrIDRef": "0"})
         text = run.find(f"{_HP}t")
         if text is None:
-            text = ET.SubElement(run, f"{_HP}t")
+            text = _append_child(run, f"{_HP}t")
         return text
 
     @property
@@ -851,7 +863,7 @@ class HwpxOxmlSectionProperties:
             attrs = {"applyPageType": page_type}
             if header_id is not None:
                 attrs[self._apply_id_attributes(tag)[0]] = header_id
-            apply = ET.SubElement(self.element, f"{_HP}{tag}Apply", attrs)
+            apply = _append_child(self.element, f"{_HP}{tag}Apply", attrs)
             changed = True
         else:
             if apply.get("applyPageType") != page_type:
@@ -897,7 +909,7 @@ class HwpxOxmlSectionProperties:
         element = self._find_header_footer(tag, page_type)
         changed = False
         if element is None:
-            element = ET.SubElement(
+            element = _append_child(
                 self.element,
                 f"{_HP}{tag}",
                 {"id": _object_id(), "applyPageType": page_type},
@@ -1362,7 +1374,7 @@ class HwpxOxmlMemoGroup:
         memo_attrs.setdefault("id", memo_id or _memo_id())
         if memo_shape_id_ref is not None:
             memo_attrs.setdefault("memoShapeIDRef", str(memo_shape_id_ref))
-        memo_element = ET.SubElement(self.element, f"{_HP}memo", memo_attrs)
+        memo_element = _append_child(self.element, f"{_HP}memo", memo_attrs)
         memo = HwpxOxmlMemo(memo_element, self)
         memo.set_text(text, char_pr_id_ref=char_pr_id_ref)
         self.section.mark_dirty()
@@ -1466,10 +1478,11 @@ class HwpxOxmlMemo:
         for child in list(self.element):
             if _element_local_name(child) in {"paraList", "p"}:
                 self.element.remove(child)
-        para_list = ET.SubElement(self.element, f"{_HP}paraList")
+        para_list = _append_child(self.element, f"{_HP}paraList", {})
         paragraph = _create_paragraph_element(
             desired,
             char_pr_id_ref=existing_char if existing_char is not None else "0",
+            parent=para_list,
         )
         para_list.append(paragraph)
         self.group.section.mark_dirty()
@@ -3493,11 +3506,11 @@ class HwpxOxmlSection:
         if paragraph is None:
             paragraph_attrs = dict(_DEFAULT_PARAGRAPH_ATTRS)
             paragraph_attrs["id"] = _paragraph_id()
-            paragraph = ET.SubElement(self._element, f"{_HP}p", paragraph_attrs)
+            paragraph = _append_child(self._element, f"{_HP}p", paragraph_attrs)
         run = paragraph.find(f"{_HP}run")
         if run is None:
-            run = ET.SubElement(paragraph, f"{_HP}run", {"charPrIDRef": "0"})
-        element = ET.SubElement(run, f"{_HP}secPr")
+            run = _append_child(paragraph, f"{_HP}run", {"charPrIDRef": "0"})
+        element = _append_child(run, f"{_HP}secPr")
         self._properties_cache = None
         self.mark_dirty()
         return element
@@ -3536,7 +3549,7 @@ class HwpxOxmlSection:
     def _memo_group_element(self, create: bool = False) -> ET.Element | None:
         element = self._element.find(f"{_HP}memogroup")
         if element is None and create:
-            element = ET.SubElement(self._element, f"{_HP}memogroup")
+            element = _append_child(self._element, f"{_HP}memogroup", {})
             self.mark_dirty()
         return element
 
@@ -4660,7 +4673,7 @@ class HwpxOxmlDocument:
         part_name = f"Contents/{section_id}.xml"
 
         # Build minimal section XML
-        section_element = ET.Element(f"{_HP}sec")
+        section_element = ET.Element(f"{_HS}sec")
         para_attrs = {"id": _paragraph_id(), **_DEFAULT_PARAGRAPH_ATTRS}
         para = ET.SubElement(section_element, f"{_HP}p", para_attrs)
         run = ET.SubElement(para, f"{_HP}run", {"charPrIDRef": "0"})

{python_hwpx-2.8 → python_hwpx-2.8.2}/src/python_hwpx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 2.8
+Version: 2.8.2
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License: Non-Commercial License
@@ -80,8 +80,9 @@ Dynamic: license-file
 
 ---
 
-`python-hwpx`는 한컴오피스의 [HWPX 포맷](https://www.hancom.com/)을 순수 Python으로 다루는 라이브러리입니다.
+`python-hwpx`는 한컴오피스의 [HWPX 포맷](https://www.hancom.com/)을 순수 Python으로 다루는 라이브러리이자 CLI 도구 모음입니다.
 한/글 설치 없이, OS에 관계없이 HWPX 문서의 구조를 파싱하고 콘텐츠를 조작할 수 있습니다.
+문서 편집 API뿐 아니라 스키마/패키지 검증, unpack/pack, 템플릿 분석 같은 XML-first 워크플로도 함께 제공합니다.
 
 > **pyhwpx / pyhwp와 다른 점?**
 > | | python-hwpx | pyhwpx | pyhwp |
@@ -93,7 +94,7 @@ Dynamic: license-file
 
 ## 🌍 크로스 플랫폼 지원
 
-HWPX 파일은 **ZIP + XML** 구조이므로, 한/글 프로그램 없이 Python만으로 완벽하게 읽고 쓸 수 있습니다.
+HWPX 파일은 **ZIP + XML** 구조이므로, 한/글 프로그램 없이 Python만으로 읽고 편집하는 워크플로를 구성할 수 있습니다.
 
 | 플랫폼 | 읽기 | 쓰기 | 비고 |
 |--------|------|------|------|
@@ -115,14 +116,14 @@ pip install python-hwpx
 ```python
 from hwpx import HwpxDocument
 
-# 기존 문서 열기
-doc = HwpxDocument.open("보고서.hwpx")
-
 # 빈 문서 새로 만들기
 doc = HwpxDocument.new()
 
+# 기존 문서를 수정하려면:
+# doc = HwpxDocument.open("보고서.hwpx")
+
 # 문단 추가
-doc.add_paragraph("python-hwpx로 생성한 문단입니다.")
+paragraph = doc.add_paragraph("python-hwpx로 생성한 문단입니다.")
 
 # 표 추가 (2×3)
 table = doc.add_table(rows=2, cols=3)
@@ -130,9 +131,8 @@ table.set_cell_text(0, 0, "이름")
 table.set_cell_text(0, 1, "부서")
 table.set_cell_text(0, 2, "연락처")
 
-# 메모 추가 (한/글에서 바로 표시)
-paragraph = doc.paragraphs[0]
-doc.add_memo_with_anchor("검토 필요", paragraph=paragraph)
+# 메모 추가 (기본 템플릿의 memo shape 사용)
+doc.add_memo_with_anchor("검토 필요", paragraph=paragraph, memo_shape_id_ref="0")
 
 # 저장
 doc.save_to_path("결과물.hwpx")
@@ -166,7 +166,7 @@ doc.save_to_path("결과물.hwpx")
 | 🎨 **스타일 치환** | 서식 기반 필터 | 색상/밑줄/charPrIDRef 기반 Run 검색 및 교체 |
 | 📤 **내보내기** | 텍스트/HTML/Markdown | 문서 변환 출력 |
 | ✅ **유효성 검사** | XSD + 패키지 구조 | CLI(`hwpx-validate`, `hwpx-validate-package`) 및 API |
-| 🧰 **워크플로 도구** | unpack/pack/template analyze/page guard | 템플릿 보존형 XML-first 작업 보조 |
+| 🧰 **작업 도구** | unpack/pack/분석/비교 | pack-ready 작업 디렉터리 추출과 재구성 점검 |
 | 🏗️ **저수준 XML** | 데이터클래스 매핑 | OWPML 스키마 ↔ Python 객체 직접 조작 |
 | 🔄 **네임스페이스 호환** | 자동 정규화 | HWPML 2016 → 2011 자동 변환 |
 
@@ -174,7 +174,7 @@ doc.save_to_path("결과물.hwpx")
 
 ### 📄 문서 편집
 
-문단, 표, 메모, 머리말/꼬리말을 Python 객체로 다룹니다.
+문단, 표, 메모, 머리글/바닥글을 Python 객체로 다룹니다.
 
 ```python
 # 단락 추가·삭제
@@ -186,9 +186,9 @@ new_sec = doc.add_section()          # 문서 끝에 섹션 추가
 new_sec.add_paragraph("두 번째 섹션 내용")
 doc.remove_section(1)                # 인덱스로 섹션 삭제
 
-# 머리말·꼬리말
+# 머리글·바닥글
 doc.set_header_text("기밀 문서", page_type="BOTH")
-doc.set_footer_text("— 1 —", page_type="BOTH")
+doc.set_footer_text("1 / 10", page_type="BOTH")
 
 # 표 셀 병합·분할
 table.merge_cells(0, 0, 1, 1)   # (0,0)~(1,1) 병합
@@ -201,13 +201,14 @@ table.set_cell_text(0, 0, "병합된 셀", logical=True, split_merged=True)
 from hwpx import TextExtractor, ObjectFinder
 
 # 텍스트 추출
-for section in TextExtractor("문서.hwpx"):
-    for para in section.paragraphs:
-        print(para.text)
+with TextExtractor("문서.hwpx") as extractor:
+    for section in extractor.iter_sections():
+        for para in extractor.iter_paragraphs(section):
+            print(para.text())
 
 # 특정 객체 탐색
-for obj in ObjectFinder("문서.hwpx").find("tbl"):
-    print(obj.tag, obj.attributes)
+for obj in ObjectFinder("문서.hwpx").find_all(tag="tbl"):
+    print(obj.tag, obj.path)
 ```
 
 ### 🎨 스타일 기반 텍스트 치환
@@ -270,7 +271,7 @@ python-hwpx
 │   ├── exporter         #   텍스트/HTML/Markdown 내보내기
 │   ├── validator        #   스키마 유효성 검사 (hwpx-validate CLI)
 │   ├── package_validator#   ZIP/OPC/HWPX 구조 검사
-│   ├── page_guard       #   layout-drift proxy
+│   ├── page_guard       #   구조 변화 징후 점검
 │   └── template_analyzer#   레퍼런스 문서 분석/추출
 └── hwpx.templates       # 내장 빈 문서 템플릿
 ```
@@ -289,7 +290,7 @@ hwpx-unpack 문서.hwpx ./unpacked
 hwpx-unpack 문서.hwpx ./pretty-unpacked --pretty-xml
 hwpx-pack ./unpacked ./repacked.hwpx
 
-# 레퍼런스 템플릿 분석과 pack-ready 추출
+# 레퍼런스 문서 분석과 작업 디렉터리 추출
 hwpx-analyze-template 문서.hwpx --extract-dir ./template-parts --json
 hwpx-pack ./template-parts ./template-roundtrip.hwpx
 hwpx-validate-package ./template-roundtrip.hwpx
@@ -297,15 +298,15 @@ hwpx-validate-package ./template-roundtrip.hwpx
 # plain / markdown 텍스트 추출
 hwpx-text-extract 문서.hwpx --format markdown --output 문서.md
 
-# 레이아웃 드리프트 프록시 비교
+# 문서 구조 변화 징후 비교
 hwpx-page-guard --reference 원본.hwpx --output 결과.hwpx
 ```
 
-`hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 통계를 비교해 레이아웃 드리프트 위험을 탐지하는 프록시 도구입니다.
+`hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 같은 구조 지표를 비교해 편집 전후 변화 징후를 빠르게 점검합니다.
 
-`hwpx-validate-package`는 `Contents/content.hpf` 같은 고정 경로를 강제하지 않고, `META-INF/container.xml`과 선택된 rootfile/manifest 관계를 따라가며 검사합니다. 엔진이 fallback으로 열 수 있는 비표준 패키지는 가능한 경우 경고로 구분합니다.
+`hwpx-validate-package`는 `Contents/content.hpf` 같은 고정 경로를 전제로 두지 않고, `META-INF/container.xml`과 실제 rootfile/manifest 선언을 따라가며 패키지 구조를 확인합니다. 엔진이 열 수 있는 비표준 패키지는 가능한 경우 경고로 분리해 보여줍니다.
 
-`hwpx-analyze-template --extract-dir`는 covered fixture 기준으로 `hwpx-pack`과 `hwpx-validate-package`, 그리고 엔진 open 경로에 다시 투입할 수 있는 pack-ready 작업 디렉터리를 만듭니다. 이건 재패킹 가능성을 목표로 한 것이지, 렌더링 fidelity를 보장한다는 뜻은 아닙니다.
+`hwpx-analyze-template --extract-dir`는 다시 묶고 점검하기 쉬운 작업 디렉터리를 만듭니다. 재구성과 구조 검증에 필요한 파일을 함께 꺼내는 용도이며, 편집기에서의 최종 렌더링 결과까지 보장한다는 뜻은 아닙니다.
 
 ## 문서
 

{python_hwpx-2.8 → python_hwpx-2.8.2}/tests/test_memo_and_style_editing.py

@@ -238,6 +238,24 @@ def test_add_memo_with_anchor_creates_paragraph_when_missing() -> None:
     assert field_end.get("beginIDRef") == "field-02"
 
 
+def test_add_memo_with_anchor_roundtrips_on_real_document() -> None:
+    document = HwpxDocument.new()
+    paragraph = document.add_paragraph("Quick start anchor")
+
+    memo, anchored, field_id = document.add_memo_with_anchor(
+        "Quick start memo",
+        paragraph=paragraph,
+        memo_shape_id_ref="0",
+    )
+
+    assert anchored is paragraph
+    assert memo.text == "Quick start memo"
+    assert field_id
+
+    reopened = HwpxDocument.open(document.to_bytes())
+    assert any(item.text == "Quick start memo" for item in reopened.memos)
+
+
 def test_document_ensure_run_style_creates_bold_entry() -> None:
     document, _, header = _build_document()
 

{python_hwpx-2.8 → python_hwpx-2.8.2}/tests/test_section_headers.py

@@ -141,3 +141,20 @@ def test_document_helpers_manage_header_apply_nodes() -> None:
 
     document.remove_header(section=section)
     assert sec_pr.find(f"{HP}headerApply") is None
+
+
+def test_header_footer_helpers_work_on_real_hwpx_document() -> None:
+    document = HwpxDocument.new()
+
+    document.set_header_text("Header {{HDR1}}")
+    document.set_footer_text("Footer {{FTR1}}")
+
+    reopened = HwpxDocument.open(document.to_bytes())
+
+    header = reopened.sections[0].properties.get_header()
+    footer = reopened.sections[0].properties.get_footer()
+
+    assert header is not None
+    assert footer is not None
+    assert header.text == "Header {{HDR1}}"
+    assert footer.text == "Footer {{FTR1}}"