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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 2.7.1
+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       # 내장 빈 문서 템플릿
 ```
@@ -284,21 +285,28 @@ hwpx-validate 문서.hwpx
 # ZIP/OPC/HWPX 패키지 구조 검사
 hwpx-validate-package 문서.hwpx
 
-# HWPX 풀기 / 다시 묶기
+# HWPX 풀기 / 다시 묶기 (기본값: XML/HWPF 바이트 보존)
 hwpx-unpack 문서.hwpx ./unpacked
+hwpx-unpack 문서.hwpx ./pretty-unpacked --pretty-xml
 hwpx-pack ./unpacked ./repacked.hwpx
 
-# 레퍼런스 템플릿 분석과 파트 추출
+# 레퍼런스 문서 분석과 작업 디렉터리 추출
 hwpx-analyze-template 문서.hwpx --extract-dir ./template-parts --json
+hwpx-pack ./template-parts ./template-roundtrip.hwpx
+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 선언을 따라가며 패키지 구조를 확인합니다. 엔진이 열 수 있는 비표준 패키지는 가능한 경우 경고로 분리해 보여줍니다.
+
+`hwpx-analyze-template --extract-dir`는 다시 묶고 점검하기 쉬운 작업 디렉터리를 만듭니다. 재구성과 구조 검증에 필요한 파일을 함께 꺼내는 용도이며, 편집기에서의 최종 렌더링 결과까지 보장한다는 뜻은 아닙니다.
 
 ## 문서
 

{python_hwpx-2.7.1 → 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       # 내장 빈 문서 템플릿
 ```
@@ -217,21 +218,28 @@ hwpx-validate 문서.hwpx
 # ZIP/OPC/HWPX 패키지 구조 검사
 hwpx-validate-package 문서.hwpx
 
-# HWPX 풀기 / 다시 묶기
+# HWPX 풀기 / 다시 묶기 (기본값: XML/HWPF 바이트 보존)
 hwpx-unpack 문서.hwpx ./unpacked
+hwpx-unpack 문서.hwpx ./pretty-unpacked --pretty-xml
 hwpx-pack ./unpacked ./repacked.hwpx
 
-# 레퍼런스 템플릿 분석과 파트 추출
+# 레퍼런스 문서 분석과 작업 디렉터리 추출
 hwpx-analyze-template 문서.hwpx --extract-dir ./template-parts --json
+hwpx-pack ./template-parts ./template-roundtrip.hwpx
+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 선언을 따라가며 패키지 구조를 확인합니다. 엔진이 열 수 있는 비표준 패키지는 가능한 경우 경고로 분리해 보여줍니다.
+
+`hwpx-analyze-template --extract-dir`는 다시 묶고 점검하기 쉬운 작업 디렉터리를 만듭니다. 재구성과 구조 검증에 필요한 파일을 함께 꺼내는 용도이며, 편집기에서의 최종 렌더링 결과까지 보장한다는 뜻은 아닙니다.
 
 ## 문서
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "2.7.1"
+version = "2.8.2"
 description = "Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }
@@ -78,7 +78,20 @@ testpaths = ["tests"]
 
 [tool.mypy]
 python_version = "3.10"
-files = ["src/hwpx/document.py", "src/hwpx/oxml/document.py"]
+files = [
+    "src/hwpx/document.py",
+    "src/hwpx/oxml/document.py",
+    "src/hwpx/opc/package.py",
+    "src/hwpx/opc/relationships.py",
+    "src/hwpx/tools/archive_cli.py",
+    "src/hwpx/tools/package_validator.py",
+    "src/hwpx/tools/page_guard.py",
+    "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
 
 [[tool.mypy.overrides]]
@@ -86,7 +99,20 @@ module = ["hwpx.document", "hwpx.oxml.document"]
 ignore_errors = true
 
 [tool.pyright]
-include = ["src/hwpx/document.py", "src/hwpx/oxml/document.py"]
+# Keep basic pyright focused on OPC/tooling modules that currently pass
+# without suppressing their real diagnostics.
+include = [
+    "src/hwpx/opc/package.py",
+    "src/hwpx/opc/relationships.py",
+    "src/hwpx/tools/archive_cli.py",
+    "src/hwpx/tools/package_validator.py",
+    "src/hwpx/tools/page_guard.py",
+    "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 = "off"
+typeCheckingMode = "basic"
 reportMissingTypeStubs = false

{python_hwpx-2.7.1 → python_hwpx-2.8.2}/src/hwpx/opc/package.py

@@ -7,12 +7,21 @@ import io
 import os
 import tempfile
 from dataclasses import dataclass
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import BinaryIO, Iterable, Iterator, Mapping, MutableMapping
 from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile, ZipInfo
 
-from lxml import etree
+from lxml import etree  # type: ignore[reportAttributeAccessIssue]
 
+from .relationships import (
+    MAIN_ROOTFILE_MEDIA_TYPE,
+    OPF_NS,
+    is_header_part_name,
+    is_section_part_name,
+    normalize_part_name,
+    parse_container_rootfiles,
+    parse_manifest_relationships,
+)
 from .xml_utils import (
     extract_xml_declaration,
     iter_declared_namespaces,
@@ -24,8 +33,6 @@ __all__ = ["HwpxPackage", "HwpxPackageError", "HwpxStructureError", "RootFile",
 
 logger = logging.getLogger(__name__)
 
-_OPF_NS = "http://www.idpf.org/2007/opf/"
-
 
 class HwpxPackageError(Exception):
     """Base error raised for issues related to :class:`HwpxPackage`."""
@@ -169,25 +176,10 @@ class HwpxPackage:
         except Exception:
             logger.exception("container.xml 파싱에 실패했습니다.")
             raise
-        rootfiles = []
-        for elem in root.findall(".//{*}rootfile"):
-            full_path_attr = elem.get("full-path")
-            full_path = full_path_attr or elem.get("fullPath") or elem.get("full_path")
-            if full_path and not full_path_attr:
-                logger.warning(
-                    "container.xml rootfile이 비표준 경로 속성명을 사용했습니다: %s",
-                    elem.attrib,
-                )
-            if not full_path:
-                raise HwpxStructureError("container.xml contains a rootfile without 'full-path'.")
-            media_type_attr = elem.get("media-type")
-            media_type = media_type_attr or elem.get("mediaType") or elem.get("media_type")
-            if media_type and not media_type_attr:
-                logger.warning(
-                    "container.xml rootfile이 비표준 media-type 속성명을 사용했습니다: %s",
-                    elem.attrib,
-                )
-            rootfiles.append(RootFile(full_path, media_type))
+        rootfiles = [
+            RootFile(ref.full_path, ref.media_type)
+            for ref in parse_container_rootfiles(root)
+        ]
         if not rootfiles:
             raise HwpxStructureError("container.xml does not declare any rootfiles.")
         return rootfiles
@@ -201,10 +193,6 @@ class HwpxPackage:
     def _validate_structure(self) -> None:
         for rootfile in self._rootfiles:
             rootfile.ensure_exists(self._files)
-        if not any(path.startswith(("Contents/", "Content/")) for path in self._files):
-            raise HwpxStructureError(
-                "HWPX package does not contain a 'Contents' directory."
-            )
 
     @property
     def mimetype(self) -> str:
@@ -220,7 +208,7 @@ class HwpxPackage:
     @property
     def main_content(self) -> RootFile:
         for rootfile in self._rootfiles:
-            if rootfile.media_type == "application/hwpml-package+xml":
+            if rootfile.media_type == MAIN_ROOTFILE_MEDIA_TYPE:
                 return rootfile
         selected = self._rootfiles[0]
         logger.warning(
@@ -254,7 +242,6 @@ class HwpxPackage:
         elif norm_path == self.VERSION_PATH:
             pending_version = self._parse_version(data)
         self._files[norm_path] = data
-        self._invalidate_caches(norm_path)
         if norm_path == self.MIMETYPE_PATH:
             self._mimetype = mimetype
         elif norm_path == self.CONTAINER_PATH:
@@ -263,6 +250,7 @@ class HwpxPackage:
         elif norm_path == self.VERSION_PATH:
             assert pending_version is not None
             self._version = pending_version
+        self._invalidate_caches(norm_path)
         self._validate_structure()
 
     def delete(self, path: str) -> None:
@@ -274,11 +262,12 @@ class HwpxPackage:
                 "Cannot remove mandatory files ('mimetype', 'container.xml', 'version.xml')."
             )
         del self._files[norm_path]
+        self._invalidate_caches(norm_path)
         self._validate_structure()
 
     @staticmethod
     def _normalize_path(path: str) -> str:
-        return path.replace("\\", "/")
+        return normalize_part_name(path)
 
     def files(self) -> list[str]:
         return sorted(self._files)
@@ -314,13 +303,12 @@ class HwpxPackage:
 
     def manifest_tree(self) -> etree._Element:
         if self._manifest_tree is None:
-            self._manifest_tree = self.get_xml(self.MANIFEST_PATH)
+            self._manifest_tree = self.get_xml(self.main_content.full_path)
         return self._manifest_tree
 
     def _manifest_items(self) -> list[etree._Element]:
         manifest = self.manifest_tree()
-        ns = {"opf": _OPF_NS}
-        return list(manifest.findall("./opf:manifest/opf:item", ns))
+        return list(manifest.findall("./opf:manifest/opf:item", OPF_NS))
 
     @staticmethod
     def _normalized_manifest_value(element: etree._Element) -> str:
@@ -339,52 +327,37 @@ class HwpxPackage:
 
     def _resolve_spine_paths(self) -> list[str]:
         if self._spine_cache is None:
-            manifest = self.manifest_tree()
-            ns = {"opf": _OPF_NS}
-            manifest_items: dict[str, str] = {}
-            for item in manifest.findall("./opf:manifest/opf:item", ns):
-                item_id = item.attrib.get("id")
-                href = item.attrib.get("href", "")
-                if item_id and href:
-                    manifest_items[item_id] = href
-            spine_paths: list[str] = []
-            for itemref in manifest.findall("./opf:spine/opf:itemref", ns):
-                idref = itemref.attrib.get("idref")
-                if not idref:
-                    continue
-                href = manifest_items.get(idref)
-                if href:
-                    spine_paths.append(href)
-            self._spine_cache = spine_paths
+            relationships = parse_manifest_relationships(
+                self.manifest_tree(),
+                self.main_content.full_path,
+                known_parts=self._files.keys(),
+            )
+            self._spine_cache = list(relationships.spine_paths)
         return self._spine_cache
 
     def section_paths(self) -> list[str]:
         if self._section_paths_cache is None:
-            from pathlib import PurePosixPath
-
             paths = [
                 path
                 for path in self._resolve_spine_paths()
-                if path and PurePosixPath(path).name.startswith("section")
+                if path and is_section_part_name(path)
             ]
             if not paths:
                 logger.warning("manifest spine에서 section 경로를 찾지 못해 파일명 기반 fallback을 사용합니다.")
                 paths = [
                     name
                     for name in self._files.keys()
-                    if PurePosixPath(name).name.startswith("section")
+                    if is_section_part_name(name)
                 ]
             self._section_paths_cache = paths
         return list(self._section_paths_cache)
 
     def header_paths(self) -> list[str]:
         if self._header_paths_cache is None:
-            from pathlib import PurePosixPath
-
             paths = [
                 path
                 for path in self._resolve_spine_paths()
-                if path and PurePosixPath(path).name.startswith("header")
+                if path and is_header_part_name(path)
             ]
             if not paths and self.has_part(self.HEADER_PATH):
                 logger.warning(
@@ -397,14 +370,13 @@ class HwpxPackage:
 
     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 self._manifest_matches(item, "masterpage", "master-page")
-                and item.attrib.get("href")
-            ]
+            paths = list(
+                parse_manifest_relationships(
+                    self.manifest_tree(),
+                    self.main_content.full_path,
+                    known_parts=self._files.keys(),
+                ).master_page_paths
+            )
             if not paths:
                 logger.warning("manifest에서 masterPage를 찾지 못해 파일명 탐색 fallback을 사용합니다.")
                 paths = [
@@ -418,13 +390,13 @@ class HwpxPackage:
 
     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 self._manifest_matches(item, "history") and item.attrib.get("href")
-            ]
+            paths = list(
+                parse_manifest_relationships(
+                    self.manifest_tree(),
+                    self.main_content.full_path,
+                    known_parts=self._files.keys(),
+                ).history_paths
+            )
             if not paths:
                 logger.warning("manifest에서 history를 찾지 못해 파일명 탐색 fallback을 사용합니다.")
                 paths = [
@@ -437,13 +409,11 @@ class HwpxPackage:
 
     def version_path(self) -> str | None:
         if not self._version_path_cache_resolved:
-            path: str | None = None
-            for item in self._manifest_items():
-                if self._manifest_matches(item, "version"):
-                    href = item.attrib.get("href", "").strip()
-                    if href:
-                        path = href
-                        break
+            path = parse_manifest_relationships(
+                self.manifest_tree(),
+                self.main_content.full_path,
+                known_parts=self._files.keys(),
+            ).version_path
             if path is None and self.has_part(self.VERSION_PATH):
                 logger.warning(
                     "manifest에서 version 파트를 찾지 못해 기본 경로 fallback을 사용합니다: %s",
@@ -461,8 +431,7 @@ class HwpxPackage:
     def _manifest_element(self) -> etree._Element | None:
         """Return the ``<opf:manifest>`` element."""
         manifest = self.manifest_tree()
-        ns = {"opf": _OPF_NS}
-        return manifest.find("opf:manifest", ns)
+        return manifest.find("opf:manifest", OPF_NS)
 
     def add_manifest_item(
         self,
@@ -475,13 +444,12 @@ class HwpxPackage:
         if manifest_el is None:
             raise HwpxStructureError("Manifest does not contain an <opf:manifest> element.")
 
-        ns = {"opf": _OPF_NS}
-        for existing in manifest_el.findall("opf:item", ns):
+        for existing in manifest_el.findall("opf:item", OPF_NS):
             if existing.get("id") == item_id:
                 return  # already present
 
         new_item = manifest_el.makeelement(
-            f"{{{_OPF_NS}}}item",
+            f"{{{OPF_NS['opf']}}}item",
             {"id": item_id, "href": href, "media-type": media_type},
         )
         manifest_el.append(new_item)
@@ -493,8 +461,7 @@ class HwpxPackage:
         if manifest_el is None:
             return False
 
-        ns = {"opf": _OPF_NS}
-        for existing in manifest_el.findall("opf:item", ns):
+        for existing in manifest_el.findall("opf:item", OPF_NS):
             if existing.get("id") == item_id:
                 manifest_el.remove(existing)
                 self._persist_manifest()
@@ -505,20 +472,18 @@ class HwpxPackage:
         """Write the in-memory manifest tree back to the package."""
         tree = self._manifest_tree
         if tree is not None:
-            self.set_part(self.MANIFEST_PATH, tree)
+            self.set_part(self.main_content.full_path, tree)
 
     def _invalidate_caches(self, changed_path: str) -> None:
-        if changed_path == self.MANIFEST_PATH:
+        if changed_path in {self.CONTAINER_PATH, self.main_content.full_path}:
             self._manifest_tree = None
-            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 changed_path == self.VERSION_PATH:
-            self._version_path_cache_resolved = False
+        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
 
     def save(
         self,