Release 2.8.2

airmang · airmang · commit 662cb112b3af · 2026-03-08T23:43:11.000+09:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 모든 중요한 변경 사항은 이 문서에 기록됩니다. 형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)과 [Semantic Versioning](https://semver.org/lang/ko/)을 따릅니다.
 
+## [2.8.2] - 2026-03-08
+### 변경
+- README를 현재 공개 API와 CLI 범위에 맞춰 정리했습니다. Quick start, 텍스트 추출, 객체 검색 예시를 실제 호출 방식 기준으로 수정했습니다.
+- `add_memo()`/`add_memo_with_anchor()`가 `HwpxDocument.new()`로 만든 실제 `lxml` 기반 문서에서도 동작하도록 memo XML 생성 경로를 엔진 호환 방식으로 정리했습니다.
+- 실제 빈 문서 템플릿에서 메모 추가 후 roundtrip 되는 회귀 테스트를 추가했습니다.
+
 ## [2.8.1] - 2026-03-08
 ### 추가
 - 템플릿 자동화 회귀 스위트를 추가했습니다 (`tests/template_automation/`). 단순 토큰, 반복 토큰, split-run, 공백 정규화, 표/머리글/바닥글/다중 섹션, 체크박스 토글, extract-repack, 비표준 rootfile 패턴을 대표 fixture + 시나리오 계약으로 점검합니다.
@@ -12,7 +18,6 @@
 - 섹션 속성(`secPr`)이 비어 있을 때 보강 생성하는 경로를 XML 엔진 호환 방식으로 정리했습니다.
 - `add_section()`이 새 섹션을 잘못된 네임스페이스로 만들던 문제를 수정했습니다.
 - mypy/pyright gradual scope에 이번에 추가한 template automation helper/generator 모듈을 포함했습니다.
-
 ## [2.8] - 2026-03-08
 ### 변경
 - `HwpxPackage`와 OXML 로딩/저장이 rootfile/manifest-relative 경로를 실제로 따르도록 정렬했습니다.
diff --git a/README.md b/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,24 +49,23 @@ 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)
 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,15 +99,15 @@ doc.save_to_path("결과물.hwpx")
 | 🎨 **스타일 치환** | 서식 기반 필터 | 색상/밑줄/charPrIDRef 기반 Run 검색 및 교체 |
 | 📤 **내보내기** | 텍스트/HTML/Markdown | 문서 변환 출력 |
 | ✅ **유효성 검사** | XSD + 패키지 구조 | CLI(`hwpx-validate`, `hwpx-validate-package`) 및 API |
-| 🧰 **작업 도구** | unpack/pack/분석/비교 | 패키지 점검과 재구성 작업 보조 |
+| 🧰 **작업 도구** | unpack/pack/분석/비교 | pack-ready 작업 디렉터리 추출과 재구성 점검 |
 | 🏗️ **저수준 XML** | 데이터클래스 매핑 | OWPML 스키마 ↔ Python 객체 직접 조작 |
 | 🔄 **네임스페이스 호환** | 자동 정규화 | HWPML 2016 → 2011 자동 변환 |
 
 ## 기능 상세
 
 ### 📄 문서 편집
 
-문단, 표, 메모, 머리말/꼬리말을 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)
 ```
 
 ### 🎨 스타일 기반 텍스트 치환
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "2.8.1"
+version = "2.8.2"
 description = "Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }
diff --git a/src/hwpx/oxml/document.py b/src/hwpx/oxml/document.py
@@ -129,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."""
 
@@ -140,16 +141,21 @@ 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:
         run_attrs.setdefault("charPrIDRef", str(char_pr_id_ref))
     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
 
@@ -1368,7 +1374,7 @@ def add_memo(
         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()
@@ -1472,10 +1478,11 @@ def set_text(
         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()
@@ -3542,7 +3549,7 @@ def paragraphs(self) -> list[HwpxOxmlParagraph]:
     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
 
diff --git a/tests/test_memo_and_style_editing.py b/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()
 
