python-hwpx 6.6.0__tar.gz → 6.8.0__tar.gz

{python_hwpx-6.6.0/src/python_hwpx.egg-info → python_hwpx-6.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 6.6.0
+Version: 6.8.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -68,7 +68,7 @@ Dynamic: license-file
 
 한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
 읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
-**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서의 저장은 요청한 보존 등급과 실제 검증 결과를 영수증으로 남깁니다.
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다.
 새 문서의 한컴 호환성은 아래에 날짜·버전을 명시한 코퍼스로 측정합니다.
 
 <p align="center">
@@ -109,7 +109,7 @@ from hwpx import HwpxDocument
 
 doc = HwpxDocument.new()
 doc.add_heading("2026 운영계획", level=1)
-doc.add_paragraph("가. 추진 배경", style="개요 2")
+doc.add_paragraph("추진 배경", style="개요 2")  # 한/글이 "가." 번호를 붙인다
 doc.save_to_path("계획.hwpx")
 ```
 
@@ -130,7 +130,7 @@ doc.save_to_path("계획.hwpx")
 - **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
 - **양식 채우기** — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
 - **생성·일괄 처리** — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
-- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(`MutationReport`)
+- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 저장 결과 보고(`return_report=True`)
 
 자세한 내용: [5분 퀵스타트](docs/quickstart.md) · [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [예제](docs/examples.md)
 
@@ -152,20 +152,6 @@ report = doc.save_to_path("신청서-작성완료.hwpx", mode="patch", fallback=
 바이트 보존을 요구합니다. 수정 파트 내부의 보존과 시각적 배치는 별도 확인이
 필요합니다. 출력 재개봉과 내용 확인까지 포함한 경로는 [안전한 쓰기 계약](docs/safe-write-contract.md)을 따르세요.
 
-### 저장에는 영수증이 따라옵니다
-
-```python
-report = doc.save_to_path("결과.hwpx", return_report=True)
-print(report.actual_mode)        # "patch" 또는 "rebuild" — 실제 저장 등급
-print(report.preservation.untouched_part_payloads.to_dict())
-                                 # {"verified": 17, "changed": 0}
-```
-
-`mode="patch", fallback="error"`는 보존 등급 미달 시 출력하지 않습니다.
-기본 `auto`는 달성 가능한 등급을 선택합니다. `report.ok`는 요청 반영이나 시각
-검증 완료를 뜻하지 않습니다.
-전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
-
 *예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
 쓰는 조각입니다. 예제별 Python 블록 판정은
 [실행 ledger](docs/python-example-ledger.json)에 동결돼 있습니다.*
@@ -175,10 +161,9 @@ print(report.preservation.untouched_part_payloads.to_dict())
 만든 파일이 실제 한컴오피스에서 열리는지 재서 그대로 공개합니다. 측정마다
 스택과 날짜를 병기합니다:
 
-- **한컴 열림 120/120 · 렌더 검증 120/120** — 현행 스택(5.7.0 · 실한컴
-  12.0.0.3288 · 2026-08-03)의 축소 측정: 기준 스트라텀 + 신규 저작 표면
-  6종(각주·누름틀·수식·차트·체크박스·편집 계획). 영수증은 행마다 bucket이
-  있어 `jq` 한 줄로 재현됩니다
+- **한컴 열림 120/120 · 렌더 검증 120/120** — 기준 문서군 + 저작 기능
+  6종(각주·누름틀·수식·차트·체크박스·편집 계획) 축소 측정
+  (5.7.0 · 실한컴 12.0.0.3288 · 2026-08-03)
 - **한컴 열림 476/476** — 전수 동결 코퍼스(N=497) 측정
   (3.4.1 · 실한컴 12.0.0.3288 · 2026-07-19)
 - **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0

{python_hwpx-6.6.0 → python_hwpx-6.8.0}/README.md

@@ -17,7 +17,7 @@
 
 한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
 읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
-**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서의 저장은 요청한 보존 등급과 실제 검증 결과를 영수증으로 남깁니다.
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다.
 새 문서의 한컴 호환성은 아래에 날짜·버전을 명시한 코퍼스로 측정합니다.
 
 <p align="center">
@@ -58,7 +58,7 @@ from hwpx import HwpxDocument
 
 doc = HwpxDocument.new()
 doc.add_heading("2026 운영계획", level=1)
-doc.add_paragraph("가. 추진 배경", style="개요 2")
+doc.add_paragraph("추진 배경", style="개요 2")  # 한/글이 "가." 번호를 붙인다
 doc.save_to_path("계획.hwpx")
 ```
 
@@ -79,7 +79,7 @@ doc.save_to_path("계획.hwpx")
 - **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
 - **양식 채우기** — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
 - **생성·일괄 처리** — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
-- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(`MutationReport`)
+- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 저장 결과 보고(`return_report=True`)
 
 자세한 내용: [5분 퀵스타트](docs/quickstart.md) · [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [예제](docs/examples.md)
 
@@ -101,20 +101,6 @@ report = doc.save_to_path("신청서-작성완료.hwpx", mode="patch", fallback=
 바이트 보존을 요구합니다. 수정 파트 내부의 보존과 시각적 배치는 별도 확인이
 필요합니다. 출력 재개봉과 내용 확인까지 포함한 경로는 [안전한 쓰기 계약](docs/safe-write-contract.md)을 따르세요.
 
-### 저장에는 영수증이 따라옵니다
-
-```python
-report = doc.save_to_path("결과.hwpx", return_report=True)
-print(report.actual_mode)        # "patch" 또는 "rebuild" — 실제 저장 등급
-print(report.preservation.untouched_part_payloads.to_dict())
-                                 # {"verified": 17, "changed": 0}
-```
-
-`mode="patch", fallback="error"`는 보존 등급 미달 시 출력하지 않습니다.
-기본 `auto`는 달성 가능한 등급을 선택합니다. `report.ok`는 요청 반영이나 시각
-검증 완료를 뜻하지 않습니다.
-전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
-
 *예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
 쓰는 조각입니다. 예제별 Python 블록 판정은
 [실행 ledger](docs/python-example-ledger.json)에 동결돼 있습니다.*
@@ -124,10 +110,9 @@ print(report.preservation.untouched_part_payloads.to_dict())
 만든 파일이 실제 한컴오피스에서 열리는지 재서 그대로 공개합니다. 측정마다
 스택과 날짜를 병기합니다:
 
-- **한컴 열림 120/120 · 렌더 검증 120/120** — 현행 스택(5.7.0 · 실한컴
-  12.0.0.3288 · 2026-08-03)의 축소 측정: 기준 스트라텀 + 신규 저작 표면
-  6종(각주·누름틀·수식·차트·체크박스·편집 계획). 영수증은 행마다 bucket이
-  있어 `jq` 한 줄로 재현됩니다
+- **한컴 열림 120/120 · 렌더 검증 120/120** — 기준 문서군 + 저작 기능
+  6종(각주·누름틀·수식·차트·체크박스·편집 계획) 축소 측정
+  (5.7.0 · 실한컴 12.0.0.3288 · 2026-08-03)
 - **한컴 열림 476/476** — 전수 동결 코퍼스(N=497) 측정
   (3.4.1 · 실한컴 12.0.0.3288 · 2026-07-19)
 - **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0

{python_hwpx-6.6.0 → python_hwpx-6.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "6.6.0"
+version = "6.8.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -295,6 +295,9 @@ files = [
     # Table width/height distribution (distribute cell width row by row) moved out
     # of table.py -- born in the gate, per the WP-A rule.
     "src/hwpx/oxml/table_sizes.py",
+    # A paragraph shape's heading (outline levels 8 to 10 in Hancom's hp:switch form),
+    # written and read in one place -- born in the gate, per the WP-A rule.
+    "src/hwpx/oxml/paragraph_heading.py",
     # Floating-shape reference frames (set_position) and shape-text
     # vertical alignment -- objects.py's overflow module (1600-line cap),
     # born in the gate, per the WP-A rule.
@@ -501,6 +504,9 @@ include = [
     # Table width/height distribution (distribute cell width row by row) moved out
     # of table.py -- born in the gate, per the WP-A rule.
     "src/hwpx/oxml/table_sizes.py",
+    # A paragraph shape's heading (outline levels 8 to 10 in Hancom's hp:switch form),
+    # written and read in one place -- born in the gate, per the WP-A rule.
+    "src/hwpx/oxml/paragraph_heading.py",
     # Floating-shape reference frames (set_position) and shape-text
     # vertical alignment -- objects.py's overflow module (1600-line cap),
     # born in the gate, per the WP-A rule.

{python_hwpx-6.6.0 → python_hwpx-6.8.0}/src/hwpx/__init__.py

@@ -14,7 +14,7 @@
 import importlib
 import warnings
 from dataclasses import dataclass
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 
 def _resolve_version() -> str:
@@ -28,9 +28,9 @@ def _resolve_version() -> str:
 
 # --- experimental / deprecated 최상위 표면 (지연 접근, 접근 시 경고) ---------------
 #
-# stable 이름은 아래에서 eager import 되어 모듈 전역에 존재하므로 ``__getattr__``이
-# 호출되지 않습니다(=경고 없음). 여기 등록된 이름만 지연 해석되어 경고를 냅니다.
-# 4.0.0에서 제거되는 이름은 0개 — 모두 계속 import 가능합니다.
+# stable 이름은 경고 없이 해석됩니다. 대부분 아래에서 eager import 되고, ``hwpx.tools``의
+# 이름은 ``_TOOLS_STABLE_EXPORTS``가 지연 해석합니다. 여기 등록된 이름만 지연 해석되어
+# 경고를 냅니다. 4.0.0에서 제거되는 이름은 0개 — 모두 계속 import 가능합니다.
 
 _EXPERIMENTAL_EXPORTS = {
     # 문서 ingestion 프레임워크(임의 포맷 -> HWPX). 계약 유동.
@@ -45,6 +45,10 @@ _EXPERIMENTAL_EXPORTS = {
     "LayoutPreview": "hwpx.tools.layout_preview",
     "PreviewPage": "hwpx.tools.layout_preview",
     "render_layout_preview": "hwpx.tools.layout_preview",
+    # 쪽 수 추정(한/글 없이, 줄마다 쪽·단·세로 위치). 계약 유동.
+    "EstimatedLine": "hwpx.layout.pages",
+    "PageEstimate": "hwpx.layout.pages",
+    "estimate_pages": "hwpx.layout.pages",
     # 문서 프리뷰 뷰어(3.8.0 신규). 계약 유동.
     "DocumentViewer": "hwpx.tools.document_viewer",
     "render_document_viewer": "hwpx.tools.document_viewer",
@@ -289,8 +293,8 @@ class RetiredSurface(ImportError):
 def __getattr__(name: str) -> object:
     """Resolve dynamic module attributes.
 
-    ``__version__``은 경고 없이 지연 해석하고, experimental/deprecated 이름은
-    해석 시 ``DeprecationWarning``을 냅니다.
+    ``__version__``과 ``hwpx.tools``의 stable 이름은 경고 없이 지연 해석하고,
+    experimental/deprecated 이름은 해석 시 ``DeprecationWarning``을 냅니다.
     """
 
     if name == "__version__":
@@ -314,6 +318,17 @@ def __getattr__(name: str) -> object:
         warnings.warn(_deprecated_message(name), DeprecationWarning, stacklevel=2)
         return getattr(importlib.import_module(module_name), name)
 
+    if name in _TOOLS_STABLE_EXPORTS or name == "tools":
+        # Not ``from . import tools``: that asks this module for ``tools`` first and
+        # re-enters this function.
+        import hwpx.tools as tools
+
+        if name == "tools":
+            return tools
+        value = getattr(tools, name)
+        globals()[name] = value
+        return value
+
     moved = _MOVED_TO_COMPANION.get(name)
     if moved is not None:
         statement = moved.import_statement(name)
@@ -342,41 +357,87 @@ def __dir__() -> list[str]:
     return sorted(
         set(globals())
         | set(__all__)
+        | {"tools"}
         | set(_EXPERIMENTAL_EXPORTS)
         | set(_DEPRECATED_EXPORTS)
     )
 
 
-# --- stable 최상위 표면 (eager import) ------------------------------------------
-from .tools.text_extractor import (
-    DEFAULT_NAMESPACES,
-    ParagraphInfo,
-    SectionInfo,
-    TextExtractor,
-)
-from .tools.object_finder import FoundElement, ObjectFinder
-from .tools.doc_diff import (
-    DOC_DIFF_REPORT_VERSION,
-    REFERENCE_CONSISTENCY_REPORT_VERSION,
-    diff_paragraphs,
-    doc_diff,
-    inspect_reference_consistency,
-)
-from .tools.mail_merge import (
-    MAIL_MERGE_REPORT_VERSION,
-    inspect_mail_merge_placeholders,
-    load_mail_merge_rows,
-    merge_template_rows,
-)
-from .tools.package_validator import (
-    EditorOpenSafetyReport,
-    PackageValidationReport,
-    validate_editor_open_safety,
-    validate_package,
+# --- 지연 stable 최상위 표면 (첫 접근 때 해석, 경고 없음) ---------------------------
+#
+# ``hwpx.tools``에 사는 stable 이름은 첫 접근 때 ``__getattr__``이 그 모듈을 읽어
+# 같은 객체를 돌려주고 모듈 전역에 둡니다(경고 없음). ``import hwpx``가 도구 모듈
+# 전부(내보내기·비교·검증 등)를 읽지 않게 하려는 것입니다. ``__all__``·``dir()``·
+# ``from hwpx import *``에는 그대로 있습니다.
+
+#: ``hwpx.tools``의 하위 모듈이 정의하고 ``hwpx.tools``가 다시 내보내는 stable 이름(텍스트 추출·개체
+#: 찾기·문서 비교·메일 머지·패키지 검증). 정적 import로 해석하므로 동적 import 지점은
+#: 늘지 않는다.
+_TOOLS_STABLE_EXPORTS = frozenset(
+    {
+        "DEFAULT_NAMESPACES",
+        "ParagraphInfo",
+        "SectionInfo",
+        "TextExtractor",
+        "FoundElement",
+        "ObjectFinder",
+        "DOC_DIFF_REPORT_VERSION",
+        "REFERENCE_CONSISTENCY_REPORT_VERSION",
+        "diff_paragraphs",
+        "doc_diff",
+        "inspect_reference_consistency",
+        "MAIL_MERGE_REPORT_VERSION",
+        "inspect_mail_merge_placeholders",
+        "load_mail_merge_rows",
+        "merge_template_rows",
+        "EditorOpenSafetyReport",
+        "PackageValidationReport",
+        "validate_editor_open_safety",
+        "validate_package",
+    }
 )
+
+
+if TYPE_CHECKING:  # type checkers see the real objects; at runtime they load lazily
+    from .tools.doc_diff import (
+        DOC_DIFF_REPORT_VERSION,
+        REFERENCE_CONSISTENCY_REPORT_VERSION,
+        diff_paragraphs,
+        doc_diff,
+        inspect_reference_consistency,
+    )
+    from .tools.mail_merge import (
+        MAIL_MERGE_REPORT_VERSION,
+        inspect_mail_merge_placeholders,
+        load_mail_merge_rows,
+        merge_template_rows,
+    )
+    from .tools.object_finder import FoundElement, ObjectFinder
+    from .tools.package_validator import (
+        EditorOpenSafetyReport,
+        PackageValidationReport,
+        validate_editor_open_safety,
+        validate_package,
+    )
+    from .tools.text_extractor import (
+        DEFAULT_NAMESPACES,
+        ParagraphInfo,
+        SectionInfo,
+        TextExtractor,
+    )
+
+
+# ``import hwpx.builder`` goes through the import system, not ``__getattr__``,
+# so the moved module names get their destination from a finder instead.
+from . import _moved_modules
+
+_moved_modules.install(_MOVED_TO_COMPANION)
+
+
+# --- stable 최상위 표면 (eager import) ------------------------------------------
+# ``hwpx.tools``의 stable 이름은 위 ``_TOOLS_STABLE_EXPORTS``가 지연 해석한다.
 from .ingest import HwpxMarkdownConverter
-from .errors import HwpxError
-from .hwp5.errors import Hwp5ConversionWarning, Hwp5Error
+from .errors import Hwp5ConversionWarning, Hwp5Error, HwpxError
 from .mutation_report import (
     MutationReport,
     PreservationDowngradeError,

{python_hwpx-6.6.0 → python_hwpx-6.8.0}/src/hwpx/_document/_legacy.py

@@ -615,7 +615,7 @@ class _LegacyFacade:
         field_id: str | None = None,
         author: str | None = None,
         created: datetime | str | None = None,
-        number: int = 1,
+        number: int | None = None,
         anchor_char_pr_id_ref: str | int | None = None,
     ) -> tuple[HwpxOxmlMemo, HwpxOxmlParagraph, str]:
         """Create a memo and ensure it is visible by anchoring a MEMO field."""
@@ -801,7 +801,7 @@ class _LegacyFacade:
         field_id: str | None = None,
         author: str | None = None,
         created: datetime | str | None = None,
-        number: int = 1,
+        number: int | None = None,
         char_pr_id_ref: str | int | None = None,
     ) -> str:
         """Attach a MEMO field control to *paragraph* so Hangul shows *memo*."""