python-hwpx 3.8.0__py3-none-any.whl → 4.1.1__py3-none-any.whl

hwpx/__init__.py

@@ -1,6 +1,18 @@
 # SPDX-License-Identifier: Apache-2.0
-"""High-level utilities for working with HWPX documents."""
+"""High-level utilities for working with HWPX documents.
 
+최상위 ``from hwpx import ...`` 표면은 세 계층으로 나뉩니다(정책·전수 목록:
+``docs/stable-api.md``):
+
+- **stable** — ``__all__``에 있는 이름. 계약이 굳었고 major 경계에서만 깨질 수 있음.
+- **experimental** — 계약이 유동적. ``from hwpx.experimental import ...``로 쓰세요.
+  최상위 재내보내기는 하위 호환을 위해 유지하되 접근 시 ``DeprecationWarning``이 나며
+  다음 major에서 제거될 예정입니다.
+- **deprecated** — 대체 경로로 이전하세요. 접근 시 ``DeprecationWarning``이 납니다.
+"""
+
+import importlib
+import warnings
 from importlib.metadata import PackageNotFoundError, version as _metadata_version
 
 
@@ -11,13 +23,94 @@ def _resolve_version() -> str:
     except PackageNotFoundError:
         return "0+unknown"
 
+
+# --- experimental / deprecated 최상위 표면 (지연 접근, 접근 시 경고) ---------------
+#
+# stable 이름은 아래에서 eager import 되어 모듈 전역에 존재하므로 ``__getattr__``이
+# 호출되지 않습니다(=경고 없음). 여기 등록된 이름만 지연 해석되어 경고를 냅니다.
+# 4.0.0에서 제거되는 이름은 0개 — 모두 계속 import 가능합니다.
+
+_EXPERIMENTAL_EXPORTS = {
+    # 문서 ingestion 프레임워크(임의 포맷 -> HWPX). 계약 유동.
+    "ConversionAttempt": "hwpx.ingest",
+    "DocumentConverter": "hwpx.ingest",
+    "DocumentIngestError": "hwpx.ingest",
+    "DocumentIngestResult": "hwpx.ingest",
+    "DocumentIngestor": "hwpx.ingest",
+    "DocumentSourceInfo": "hwpx.ingest",
+    "UnsupportedDocumentFormat": "hwpx.ingest",
+    # 레이아웃 프리뷰(한컴 없는 정직 근사). 계약 유동.
+    "LayoutPreview": "hwpx.tools.layout_preview",
+    "PreviewPage": "hwpx.tools.layout_preview",
+    "render_layout_preview": "hwpx.tools.layout_preview",
+    # 문서 프리뷰 뷰어(3.8.0 신규). 계약 유동.
+    "DocumentViewer": "hwpx.tools.document_viewer",
+    "render_document_viewer": "hwpx.tools.document_viewer",
+}
+
+_DEPRECATED_EXPORTS = {
+    "analyze_template_formfit": "hwpx.template_formfit",
+    "apply_template_formfit": "hwpx.template_formfit",
+    "TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION": "hwpx.template_formfit",
+    "TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION": "hwpx.template_formfit",
+}
+
+# deprecated formfit 표면의 공통 대체 경로 안내.
+_FORMFIT_REPLACEMENT = (
+    "구조적 form-fill 경로를 사용하세요: 라이브러리는 "
+    "hwpx.table_patch.fill_cells 계열, MCP는 analyze_form_fill/apply_form_fill/"
+    "verify_form_fill."
+)
+
+
+def _experimental_message(name: str) -> str:
+    return (
+        f"'hwpx.{name}'는 실험적(experimental) 표면입니다. 계약이 유동적이므로 "
+        f"'from hwpx.experimental import {name}'로 import하세요. 최상위 재내보내기는 "
+        f"다음 major에서 제거될 예정입니다."
+    )
+
+
+def _deprecated_message(name: str) -> str:
+    return (
+        f"'hwpx.{name}'는 deprecated입니다. {_FORMFIT_REPLACEMENT} 이 이름은 "
+        f"다음 major에서 제거될 예정입니다."
+    )
+
+
 def __getattr__(name: str) -> object:
-    """Resolve dynamic module attributes."""
+    """Resolve dynamic module attributes.
+
+    ``__version__``은 경고 없이 지연 해석하고, experimental/deprecated 이름은
+    해석 시 ``DeprecationWarning``을 냅니다.
+    """
 
     if name == "__version__":
         return _resolve_version()
+
+    module_name = _EXPERIMENTAL_EXPORTS.get(name)
+    if module_name is not None:
+        warnings.warn(_experimental_message(name), DeprecationWarning, stacklevel=2)
+        return getattr(importlib.import_module(module_name), name)
+
+    module_name = _DEPRECATED_EXPORTS.get(name)
+    if module_name is not None:
+        warnings.warn(_deprecated_message(name), DeprecationWarning, stacklevel=2)
+        return getattr(importlib.import_module(module_name), name)
+
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
+
+def __dir__() -> list[str]:
+    return sorted(
+        set(globals())
+        | set(__all__)
+        | set(_EXPERIMENTAL_EXPORTS)
+        | set(_DEPRECATED_EXPORTS)
+    )
+
+
+# --- stable 최상위 표면 (eager import) ------------------------------------------
 from .tools.text_extractor import (
     DEFAULT_NAMESPACES,
     ParagraphInfo,
@@ -70,25 +163,8 @@ from .tools.style_profile import (
     placeholder_fill_report,
     register_template,
 )
-from .tools.layout_preview import (
-    LayoutPreview,
-    PreviewPage,
-    render_layout_preview,
-)
-from .tools.document_viewer import (
-    DocumentViewer,
-    render_document_viewer,
-)
-from .ingest import (
-    ConversionAttempt,
-    DocumentConverter,
-    DocumentIngestError,
-    DocumentIngestResult,
-    DocumentIngestor,
-    DocumentSourceInfo,
-    HwpxMarkdownConverter,
-    UnsupportedDocumentFormat,
-)
+from .ingest import HwpxMarkdownConverter
+from .errors import HwpxError
 from .mutation_report import (
     MutationReport,
     PreservationDowngradeError,
@@ -124,12 +200,6 @@ from .quality import (
     SavePipeline,
     VisualCompleteReport,
 )
-from .template_formfit import (
-    TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION,
-    TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION,
-    analyze_template_formfit,
-    apply_template_formfit,
-)
 
 __all__ = [
     "QualityPolicy",
@@ -141,30 +211,21 @@ __all__ = [
     "DEFAULT_STYLE_PRESET",
     "DOCUMENT_PLAN_SCHEMA_VERSION",
     "get_document_plan_schema",
-    "ConversionAttempt",
     "DocumentBlock",
-    "DocumentConverter",
-    "DocumentIngestError",
-    "DocumentIngestResult",
-    "DocumentIngestor",
     "DocumentPlan",
-    "DocumentSourceInfo",
     "DocumentStylePreset",
     "EditorOpenSafetyReport",
     "ParagraphInfo",
     "PackageValidationReport",
     "BytePreservingPatchResult",
+    "HwpxError",
     "MutationReport",
     "PreservationDowngradeError",
     "PlanValidationReport",
     "ParagraphTextPatch",
     "PatchApplied",
     "PatchSkipped",
-    "LayoutPreview",
-    "PreviewPage",
     "SectionInfo",
-    "TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION",
-    "TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION",
     "TextExtractor",
     "FoundElement",
     "HwpxMarkdownConverter",
@@ -177,7 +238,6 @@ __all__ = [
     "STYLE_PROFILE_SCHEMA_VERSION",
     "TEMPLATE_REGISTRY_SCHEMA_VERSION",
     "TABLE_COMPUTE_REPORT_VERSION",
-    "UnsupportedDocumentFormat",
     "apply_style_profile_to_plan",
     "build_comparison_table_plan",
     "build_image_grid",
@@ -190,8 +250,6 @@ __all__ = [
     "HwpxDocument",
     "HwpxPackage",
     "create_document_from_plan",
-    "analyze_template_formfit",
-    "apply_template_formfit",
     "approval_box",
     "describe_template",
     "extract_style_profile",
@@ -209,9 +267,6 @@ __all__ = [
     "validate_editor_open_safety",
     "validate_package",
     "paragraph_patch",
-    "render_layout_preview",
-    "render_document_viewer",
-    "DocumentViewer",
     "register_template",
     "table_compute",
 ]

hwpx/_document/persistence.py

@@ -3,10 +3,10 @@
 
 from __future__ import annotations
 
-import warnings
 from os import PathLike
 from typing import TYPE_CHECKING, Any, BinaryIO, Literal, Sequence
 
+from ..errors import SaveError
 from ..mutation_report import (
     Fallback,
     Mode,
@@ -84,7 +84,15 @@ def _run_pre_save_validation(doc: "HwpxDocument") -> None:
     report = doc.validate()
     if not report.ok:
         msgs = _summarize_validation_issues(report.issues)
-        raise ValueError(f"Document validation failed: {msgs}")
+        raise SaveError(
+            f"Document validation failed: {msgs}",
+            code="document-validation-failed",
+            context={"issueCount": len(report.issues), "issues": msgs},
+            suggestion=(
+                "Fix the reported schema issues, or disable validate_on_save if "
+                "the validation is a false positive for your document."
+            ),
+        )
 
 
 def _run_open_safety_validation(doc: "HwpxDocument", archive_bytes: bytes) -> None:
@@ -94,9 +102,15 @@ def _run_open_safety_validation(doc: "HwpxDocument", archive_bytes: bytes) -> No
 
     report = validate_editor_open_safety(archive_bytes)
     if not report.ok:
-        raise ValueError(
+        raise SaveError(
             "Generated HWPX package failed open-safety validation: "
-            + report.summary
+            + report.summary,
+            code="open-safety-failed",
+            context={"summary": report.summary},
+            suggestion=(
+                "The serialized package would not reopen in an HWPX editor; "
+                "inspect validate_editor_open_safety(...) for the failing checks."
+            ),
         )
 
 
@@ -126,7 +140,15 @@ def _gate_and_write(
     )
     if not report.ok:
         detail = "; ".join(str(error) for error in report.errors)
-        raise ValueError(f"Document save failed the quality gate: {detail}")
+        raise SaveError(
+            f"Document save failed the quality gate: {detail}",
+            code="quality-gate-failed",
+            context={"errors": [str(error) for error in report.errors]},
+            suggestion=(
+                "The SavePipeline quality gate rejected the archive; inspect the "
+                "returned report's errors before retrying."
+            ),
+        )
     return report
 
 
@@ -420,29 +442,3 @@ def _mark_save_clean(doc: "HwpxDocument") -> None:
     package = doc._package
     package._opened_members = dict(package._files)
     package._opened_zip_infos = dict(package._zip_infos)
-
-
-def save(
-    doc: "HwpxDocument",
-    path_or_stream: str | PathLike[str] | BinaryIO | None = None,
-) -> str | PathLike[str] | BinaryIO | bytes:
-    """Deprecated compatibility wrapper around save_to_path/save_to_stream/to_bytes.
-
-    Deprecated:
-        ``save()``는 하위 호환을 위해 유지되며 향후 제거될 수 있습니다.
-        - 경로 저장: ``save_to_path(path)``
-        - 스트림 저장: ``save_to_stream(stream)``
-        - 바이트 반환: ``to_bytes()``
-    """
-
-    warnings.warn(
-        "HwpxDocument.save()는 deprecated 예정입니다. "
-        "save_to_path()/save_to_stream()/to_bytes() 사용을 권장합니다.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-    if path_or_stream is None:
-        return doc.to_bytes()
-    if isinstance(path_or_stream, (str, PathLike)):
-        return doc.save_to_path(path_or_stream)
-    return doc.save_to_stream(path_or_stream)

hwpx/document.py

@@ -1844,28 +1844,3 @@ class HwpxDocument:
             self,
             reset_dirty=reset_dirty,
         )
-
-
-    @overload
-    def save(self, path_or_stream: None = None) -> bytes: ...
-
-    @overload
-    def save(self, path_or_stream: str | PathLike[str]) -> str | PathLike[str]: ...
-
-    @overload
-    def save(self, path_or_stream: BinaryIO) -> BinaryIO: ...
-
-    def save(
-        self,
-        path_or_stream: str | PathLike[str] | BinaryIO | None = None,
-    ) -> str | PathLike[str] | BinaryIO | bytes:
-        """Deprecated compatibility wrapper around save_to_path/save_to_stream/to_bytes.
-
-        Deprecated:
-            ``save()``는 하위 호환을 위해 유지되며 향후 제거될 수 있습니다.
-            - 경로 저장: ``save_to_path(path)``
-            - 스트림 저장: ``save_to_stream(stream)``
-            - 바이트 반환: ``to_bytes()``
-        """
-
-        return _persistence.save(self, path_or_stream=path_or_stream)

hwpx/errors.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Structured exception base for python-hwpx (S-091 P2).
+
+Every fail-closed public contract raises a :class:`HwpxError` (or a subclass).
+The base carries three machine-readable fields on top of the human-readable
+message, so a caller can branch on a stable ``code``, read the measured
+``context``, and surface an actionable ``suggestion`` without parsing prose:
+
+- ``code`` — a stable, kebab-case identifier for the failure class. Callers may
+  switch on it; it is part of the contract and changes only on a major boundary.
+- ``context`` — a JSON-serialisable dict of the measured values that triggered
+  the failure (offending parts, indices, counts…). Empty when there is nothing
+  to measure.
+- ``suggestion`` — one actionable next step, or ``None`` when there is nothing
+  specific to advise.
+
+``str(exc)`` stays the human sentence (the ``message``), so existing ``except``
+handlers and log lines are unchanged. Subclasses set :attr:`default_code`, which
+lets a historical ``raise Subclass("message")`` site keep working while gaining
+the structured fields with no raise-site churn (§11 — no bulk raise rewrites).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+class HwpxError(Exception):
+    """Base for structured, fail-closed python-hwpx errors."""
+
+    #: Stable ``code`` used when a raise site does not pass an explicit ``code``.
+    default_code: str = "hwpx-error"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        context: Mapping[str, Any] | None = None,
+        suggestion: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code if code is not None else self.default_code
+        self.context: dict[str, Any] = dict(context) if context else {}
+        self.suggestion = suggestion
+
+    def to_dict(self) -> dict[str, Any]:
+        """The structured envelope: ``code`` / ``message`` / ``context`` / ``suggestion``."""
+
+        return {
+            "code": self.code,
+            "message": self.message,
+            "context": dict(self.context),
+            "suggestion": self.suggestion,
+        }
+
+
+class SaveError(HwpxError, ValueError):
+    """A representative save path (``save_to_path`` / ``save_to_stream`` /
+    ``to_bytes``) failed closed before writing any output.
+
+    Subclasses :class:`ValueError` for backward compatibility: pre-4.0 callers
+    caught ``ValueError`` from these paths and must keep working.
+    """
+
+    default_code = "save-failed"
+
+
+__all__ = ["HwpxError", "SaveError"]

hwpx/experimental.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+"""실험적(experimental) 공개 표면.
+
+여기 노출되는 이름들은 **계약이 유동적**입니다 — minor 릴리스에서 시그니처,
+동작, 반환 스키마가 예고 없이 바뀔 수 있습니다. 안정 계약이 필요하면 stable 표면
+(:mod:`hwpx` 최상위 ``__all__`` / ``docs/stable-api.md``)만 사용하세요.
+
+이 모듈은 실제 구현 모듈에서 이름을 **재내보내기(re-export)** 만 합니다(모듈을
+옮기지 않음). 최상위 ``from hwpx import ...`` 경로도 하위 호환을 위해 당분간
+동작하지만 ``DeprecationWarning``을 내며 다음 major에서 제거될 예정입니다 —
+새 코드는 ``from hwpx.experimental import ...``를 쓰세요.
+"""
+
+from __future__ import annotations
+
+from .ingest import (
+    ConversionAttempt,
+    DocumentConverter,
+    DocumentIngestError,
+    DocumentIngestResult,
+    DocumentIngestor,
+    DocumentSourceInfo,
+    UnsupportedDocumentFormat,
+)
+from .tools.document_viewer import (
+    DocumentViewer,
+    render_document_viewer,
+)
+from .tools.layout_preview import (
+    LayoutPreview,
+    PreviewPage,
+    render_layout_preview,
+)
+
+__all__ = [
+    "ConversionAttempt",
+    "DocumentConverter",
+    "DocumentIngestError",
+    "DocumentIngestResult",
+    "DocumentIngestor",
+    "DocumentSourceInfo",
+    "UnsupportedDocumentFormat",
+    "LayoutPreview",
+    "PreviewPage",
+    "render_layout_preview",
+    "DocumentViewer",
+    "render_document_viewer",
+]

hwpx/form_fit/wordbox.py

@@ -681,6 +681,14 @@ def extract_cell_clips(pdf_path: str, *, page: int | None = None) -> list[Rect]:
     These are the overflow clips — same coordinate space as the glyph boxes — so
     no HWPX→PDF transform is needed. ``find_tables`` can raise on odd pages; such
     a page contributes no clips rather than crashing.
+
+    Borders-only (``strategy="lines_strict"``): a cell rectangle is defined by its
+    *drawn borders*, not by the text inside it. The ``find_tables`` default snaps
+    edges to glyph positions, so a filled value can appear to *escape* a clip that
+    was mis-sized around the very text it holds — a false overflow. S-094 P3
+    measured this: the only 3 corpus pairs that flagged ``newOverflow`` (the nts
+    forms) all had the fill value escaping a text-snapped clip under the default,
+    and 0 escapes under ``lines_strict``; there were no real escapes to mask.
     """
 
     if not fitz_available():
@@ -695,7 +703,7 @@ def extract_cell_clips(pdf_path: str, *, page: int | None = None) -> list[Rect]:
     with doc:
         for pno in _page_indices(doc, page):
             try:
-                tables = doc[pno].find_tables().tables
+                tables = doc[pno].find_tables(strategy="lines_strict").tables
             except Exception:
                 continue  # layout analysis failed on this page -> no clips, no crash
             for ti, table in enumerate(tables):
@@ -839,8 +847,21 @@ class LayoutSignature:
     lesson that absolute glyph-overlap is unusable on real forms). Page count is
     the dominant, high-confidence signal — a fill that spills onto a new page is
     the canonical layout collapse. Per-table ``(rows, cols)`` is the finer
-    row/column signal; ``find_tables`` is content-sensitive, so it is judged as a
-    multiset *delta* (blank vs filled), not an absolute count.
+    row/column signal, extracted from *drawn table borders only*
+    (``find_tables(strategy="lines_strict")``): a structural fingerprint must be
+    text-independent, so it is judged as a multiset *delta* (blank vs filled),
+    not an absolute count.
+
+    Why ``lines_strict`` and not the ``find_tables`` default (``"lines"``): the
+    default snaps table edges to *text* positions, so injecting a value into a
+    previously-empty cell makes it hallucinate a phantom ``(2,2)``/``(1,2)`` table
+    or wobble a real one by ±1 row/col even when the drawn grid and page count are
+    unchanged. S-094 P3 measured this on the frozen corpus (all 6 "table-shape"
+    differential failures were page-stable phantoms; under ``lines_strict`` blank
+    and filled agree, 0 regressions across 31 pairs; ``sen-24`` has byte-identical
+    drawn rectangles yet the default strategy still invented a ``(1,2)`` table from
+    the 3 added glyphs). Borders-only detection measures the grid the fill did not
+    touch.
     """
 
     page_count: int
@@ -879,7 +900,12 @@ def extract_layout_signature(pdf_path: str) -> LayoutSignature:
         for page in doc:
             sizes.append((float(page.rect.width), float(page.rect.height)))
             try:
-                tables = page.find_tables().tables
+                # Borders-only ("lines_strict"): a *structural* fingerprint must
+                # not react to cell text. The default strategy snaps to glyph
+                # positions and invents phantom tables from a fill's added text
+                # (S-094 P3). Bordered form grids are detected identically either
+                # way; the text-sensitivity is the only difference we drop.
+                tables = page.find_tables(strategy="lines_strict").tables
             except Exception:
                 continue  # layout analysis failed on this page -> no tables, no crash
             for table in tables:

hwpx/mutation_report.py

@@ -22,6 +22,8 @@ from io import BytesIO
 from typing import Any, Literal, Mapping, Sequence
 from zipfile import ZipInfo
 
+from .errors import HwpxError
+
 MUTATION_REPORT_SCHEMA = "hwpx.mutation-report/v1"
 COORDINATE_SPACE = "uncompressed-part-bytes"
 
@@ -229,9 +231,19 @@ class MutationReport:
         }
 
 
-class PreservationDowngradeError(Exception):
+class PreservationDowngradeError(HwpxError):
     """Raised when a requested preservation grade is not achieved and
-    ``fallback="error"`` — before any output is written (specs/032 §1)."""
+    ``fallback="error"`` — before any output is written (specs/032 §1).
+
+    Structured on the :class:`~hwpx.errors.HwpxError` base: ``code`` is the stable
+    ``"preservation-downgrade"`` identifier, ``context`` carries the measured
+    modes and offending parts, and ``suggestion`` is the actionable next step.
+    The historical positional attributes (``requested_mode``/``achieved_grade``/
+    ``offending_parts``/``suggestion``) are preserved so existing handlers still
+    read them.
+    """
+
+    default_code = "preservation-downgrade"
 
     def __init__(
         self,
@@ -244,12 +256,18 @@ class PreservationDowngradeError(Exception):
         self.requested_mode = requested_mode
         self.achieved_grade = achieved_grade
         self.offending_parts = offending_parts
-        self.suggestion = suggestion
         parts = ", ".join(offending_parts) if offending_parts else "(none)"
         super().__init__(
             f"requested mode {requested_mode!r} needs patch-grade preservation but "
             f"the save achieved {achieved_grade!r}; offending parts: {parts}. "
-            f"{suggestion}"
+            f"{suggestion}",
+            code=self.default_code,
+            context={
+                "requestedMode": requested_mode,
+                "achievedGrade": achieved_grade,
+                "offendingParts": list(offending_parts),
+            },
+            suggestion=suggestion,
         )
 
 

hwpx/table_patch.py

@@ -28,6 +28,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Iterable, Mapping, Sequence
 
+from .errors import HwpxError
 from .mutation_report import MutationReport, project_byte_splice
 from .patch import (
     _apply_edits,
@@ -803,8 +804,16 @@ _S_TR = re.compile(r"<hp:tr\b.*?</hp:tr>", re.DOTALL)
 _S_TC = re.compile(r"<hp:tc\b.*?</hp:tc>", re.DOTALL)
 
 
-class TableStructureError(ValueError):
-    """A structure edit was refused (fail-closed) or is unsupported."""
+class TableStructureError(HwpxError, ValueError):
+    """A structure edit was refused (fail-closed) or is unsupported.
+
+    Structured on :class:`~hwpx.errors.HwpxError` (``code="table-structure"``)
+    while still subclassing :class:`ValueError` for backward compatibility. The
+    many string-only raise sites keep working and gain the ``code``/``context``/
+    ``suggestion`` fields via the base default.
+    """
+
+    default_code = "table-structure"
 
 
 def _si(chunk: str, tag: str, attr: str) -> int | None:
@@ -1645,8 +1654,14 @@ def apply_table_ops(
 
 # --- P3: real-Hancom oracle gate for form-fill (FR-005) -----------------------
 
-class RenderCheckRequired(RuntimeError):
-    """``verify_fill(require=True)`` but no real Hancom oracle rendered."""
+class RenderCheckRequired(HwpxError, RuntimeError):
+    """``verify_fill(require=True)`` but no real Hancom oracle rendered.
+
+    Structured on :class:`~hwpx.errors.HwpxError` (``code="render-check-required"``)
+    while still subclassing :class:`RuntimeError` for backward compatibility.
+    """
+
+    default_code = "render-check-required"
 
 
 def verify_fill(

python_hwpx-4.1.1.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: python-hwpx
+Version: 4.1.1
+Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
+Author: python-hwpx Maintainers
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/airmang/python-hwpx
+Project-URL: Documentation, https://airmang.github.io/python-hwpx/
+Project-URL: Issues, https://github.com/airmang/python-hwpx/issues
+Keywords: hwp,hwpx,hancom,opc,xml,document-automation,validation,template
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Markup :: XML
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: lxml<7,>=4.9
+Provides-Extra: visual
+Requires-Dist: pymupdf>=1.24; extra == "visual"
+Requires-Dist: pillow>=10.0; extra == "visual"
+Requires-Dist: numpy>=1.26; extra == "visual"
+Provides-Extra: xlsx
+Requires-Dist: openpyxl>=3.1; extra == "xlsx"
+Provides-Extra: preview
+Requires-Dist: latex2mathml>=3.77; extra == "preview"
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: latex2mathml>=3.77; extra == "dev"
+Provides-Extra: test
+Requires-Dist: build>=1.0; extra == "test"
+Requires-Dist: numpy>=1.26; extra == "test"
+Requires-Dist: pillow>=10.0; extra == "test"
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: ruff>=0.12; extra == "test"
+Requires-Dist: latex2mathml>=3.77; extra == "test"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.10; extra == "typecheck"
+Requires-Dist: pyright>=1.1.390; extra == "typecheck"
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">python-hwpx</h1>
+  <p align="center">
+    <strong>한컴 없이 HWPX를 읽고, 고치고, 만드는 순수 파이썬 라이브러리</strong>
+  </p>
+  <p align="center">
+    <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/v/python-hwpx?color=blue&label=PyPI" alt="PyPI"></a>
+    <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx" alt="Python"></a>
+    <a href="https://github.com/airmang/python-hwpx/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx/tests.yml?branch=main&label=tests" alt="Tests"></a>
+    <a href="https://airmang.github.io/python-hwpx/corpus-metrics.html"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fairmang.github.io%2Fpython-hwpx%2F_static%2Fbadge-hancom-open.json" alt="Hancom open"></a>
+    <a href="https://github.com/airmang/python-hwpx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
+  </p>
+</p>
+
+<p align="center">한국어 | <a href="README_EN.md">English</a></p>
+
+기존 문서는 손댄 곳만 고치고(미수정 영역은 바이트 그대로), 새 문서는 실제
+한컴오피스가 받아들이는 형태로 만듭니다. HWPX는 ZIP+XML(OWPML/OPC) 구조라
+Windows·macOS·Linux·CI 어디서든 순수 파이썬으로 동작합니다.
+
+| | 레포 | 역할 |
+|---|---|---|
+| 📦 | **`python-hwpx`** | 순수 파이썬 HWPX 코어 (이 레포) |
+| 🔌 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop 등)에서 HWPX 조작 |
+| 🎯 | [`hwpx-plugin`](https://github.com/airmang/hwpx-plugins) | 에이전트용 플러그인·스킬 번들 |
+
+## 시작하기
+
+```bash
+pip install python-hwpx      # Python 3.10+
+```
+
+```python
+from hwpx import HwpxDocument
+
+doc = HwpxDocument.open("보고서.hwpx")
+doc.add_paragraph("자동화로 추가한 문단입니다.")
+doc.save_to_path("보고서-수정.hwpx")
+```
+
+## 무엇을 하나
+
+- **읽기·추출** — 텍스트/HTML/rich Markdown 내보내기(서식·중첩 표·각주 보존), XPath 객체 탐색
+- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 등 서식
+- **양식 채우기** — 라벨·경로 기반 셀 채움, 바이트 보존 구조 편집(행·열·오토핏·shrink-to-fit)
+- **생성** — 조립형 builder, 공문 lint·결재란, 사진대지·명패·조직도, mail merge, 신구대조표
+- **변경추적·목차** — redline 저작, 네이티브 목차·상호참조
+- **검증·안전** — XSD·패키지 검증 CLI, 열림 안전 게이트, 모든 쓰기에 영수증(`MutationReport`)
+
+자세한 내용: [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [안정 API 표면](docs/stable-api.md) · [예제](docs/examples.md)
+
+### 양식 채우기 — 서식은 그대로, 값만
+
+```python
+doc = HwpxDocument.open("신청서.hwpx")
+result = doc.fill_by_path({
+    "성명 > right": "홍길동",
+    "소속 > right": "플랫폼팀",
+})
+doc.save_to_path("신청서-작성완료.hwpx")
+```
+
+라벨 기준으로 셀을 찾아 채우고, 손대지 않은 영역은 원본 바이트가 그대로 유지됩니다.
+
+### 저장에는 영수증이 따라옵니다
+
+```python
+report = doc.save_to_path("결과.hwpx", return_report=True)
+print(report.actual_mode)        # "patch" — 문서 재조립 없이 저장됨
+print(report.preservation.untouched_part_payloads.to_dict())
+                                 # {"verified": 17, "changed": 0}
+```
+
+요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
+전체 규칙은 [안전한 쓰기 계약](docs/safe-write-contract.md)에 있습니다.
+
+## 실측으로 말합니다
+
+산출물 전수를 실제 한컴오피스로 측정해 그대로 공개합니다(동결 코퍼스 N=497):
+
+- **한컴 오픈 476/476 all-pass** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **미수정 영역 바이트 보존 497/497** · 개인정보 0-leak
+- **렌더 검증 416/476** + 정직 버킷 43 — 한컴 자체가 PDF export를 거부한 케이스도 숨기지 않고 집계
+- 낮은 숫자도 그대로 발행합니다 — 전체 수치·주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)
+
+기능별로 되는 것과 안 되는 것은 [지원 매트릭스](docs/support-matrix.md)에 등급으로
+명시되어 있습니다. 현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
+
+> 위 수치는 *생성물 수용률* 축입니다(만든 파일을 실한컴이 받는가). 문서 *파싱 recall*과는
+> 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
+
+## 비교
+
+| | python-hwpx | pyhwpx | pyhwp |
+|---|---|---|---|
+| **대상 포맷** | `.hwpx` (OWPML/OPC) | `.hwpx` | `.hwp` (v5 바이너리) |
+| **한/글 설치** | 불필요 | 필요 (Windows COM) | 불필요 |
+| **크로스 플랫폼** | ✅ Linux / macOS / Windows / CI | ❌ Windows 전용 | ✅ |
+| **편집/생성 API** | ✅ | ✅ (COM) | ❌ 대부분 읽기 |
+| **AI 에이전트 연동 (MCP)** | ✅ | ❌ | ❌ |
+
+> HWP(v5 바이너리)는 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.
+
+## 알려진 제약
+
+- `add_shape()` / `add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않습니다.
+- `<hp:pic>` 그림 개체의 완전 자동 생성은 제공하지 않습니다.
+- 암호화된 HWPX는 지원하지 않습니다.
+
+## 기여하기
+
+[help wanted](https://github.com/airmang/python-hwpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) ·
+[로드맵](https://github.com/airmang/python-hwpx/milestones) ·
+[Discussions](https://github.com/airmang/python-hwpx/discussions) ·
+[내부 실전 가이드](docs/internals/) ·
+[CONTRIBUTING](CONTRIBUTING.md)
+
+HWPX 내부 구조가 처음이라면 [내부 실전 가이드](docs/internals/)부터 — 실제 한/글
+동작에서 확인된 조판 캐시·목차 필드·OPC 재패킹 같은 실전 지식을 정리해 두었습니다.
+
+## 감사의 말
+
+아래 공개 표준·프로젝트에 빚지고 있습니다.
+
+- **[OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101)](https://www.kssn.net/search/stddetail.do?itemNo=K001010119985)** — HWPX가 기반하는 한국 산업 표준
+- **[hancom-io/hwpx-owpml-model](https://github.com/hancom-io/hwpx-owpml-model)** — OWPML 요소 구조 참조 모델 · **[neolord0/hwpxlib](https://github.com/neolord0/hwpxlib)** — 오라클 샘플 코퍼스
+- **[edwardkim/rhwp](https://github.com/edwardkim/rhwp)** — 멱등성·검증 게이트 설계 영감
+- **범정부오피스** — 공무 문서 편집 워크플로 아이디어
+
+## License · Maintainer
+
+Apache-2.0 ([LICENSE](LICENSE) · [NOTICE](NOTICE)) — **Kohkyuhyun** [@airmang](https://github.com/airmang) · [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)

{python_hwpx-3.8.0.dist-info → python_hwpx-4.1.1.dist-info}/RECORD

@@ -1,17 +1,19 @@
-hwpx/__init__.py,sha256=HisWQIT_6hib7mZizJnOixVZ04CtEb0Jb7ldWpEOy5U,5774
+hwpx/__init__.py,sha256=7o5kxSumBqqFnhLrYojfCrvRbq3I0cE5DxxIp3cFeB8,8600
 hwpx/authoring.py,sha256=BoWGNc50ALMSuyjFUGl1iMCLYb1rFllCKVcuugvsaOw,129001
 hwpx/body_patch.py,sha256=yB3X0L3Jns38CpRFOvjvPMnovJ5a2SoVefh6FIy3uYQ,25736
-hwpx/document.py,sha256=grSkZFmRAIIy6arVrP9DVbKrjKzsKopvSE8TFFmBVD8,60037
+hwpx/document.py,sha256=_a0snPKzdsdIL9AmzvQzvOloqXB0CVq89vx6GjnKeHw,59186
+hwpx/errors.py,sha256=BgWhEFHiiiz9DoCNRwovHt95dz8HVzQx1C29PGfXMwQ,2619
 hwpx/evalplan_fill.py,sha256=UmXj6uo63Bo1iBI9lB3_e2G-z8dT_8nQBywwvfrepfM,83578
+hwpx/experimental.py,sha256=H8fBrmGf0BzoDS6dqwBpUChUestUgOpO7XjMEBXsssg,1499
 hwpx/fill_residue.py,sha256=Uq4DbwFNlbHrO3FQA7Yyk1I0gAsvPw6O8mPD82rmBws,8286
 hwpx/form_fill.py,sha256=VUIU53Qa9Ho2aP72biDvJwnDW7ngdAzu3PSd5A7d1JM,9908
 hwpx/formfill_quality.py,sha256=pRxZYb1cg95F2O78va5glMJ3UqPh1rewJB1Qz-LOlsc,38521
 hwpx/guidance_scan.py,sha256=62ltZsuaebWaDxDaMbbq870J5PQVZoz0ZCSZ39otBkE,25193
-hwpx/mutation_report.py,sha256=a5l9TtkfwOluXhTof88pVesjNr-7pD1vQ3G0wh0iuhI,18683
+hwpx/mutation_report.py,sha256=6hurhDdgGiONeLIeWZJT8lwLtWJZ1VHp1l6G0zy0mQo,19409
 hwpx/package.py,sha256=0rKjGCJbPQvrVBIy07Jpjsu3fI7HhbqFCGWTiTDsJpo,1141
 hwpx/patch.py,sha256=6MEVGAjpaWKK7Oyxydfvk52-VzSJfHi6I-eUCGJHZQM,24846
 hwpx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-hwpx/table_patch.py,sha256=_i220iggNfrIXmQxq4eKO0OZWqZeUFRwAlev9FL1xKw,78208
+hwpx/table_patch.py,sha256=R5DBCgImIU8e53nq9X3wqGPJlZ7pbZoiretgU2E__a8,78805
 hwpx/template_formfit.py,sha256=dlxf98FatT5Nl4hN15TuMXqj5NlDTGSnLaqXVo_PoBo,23424
 hwpx/templates.py,sha256=28bYqeJVeDb1Cq8G9NZG9Mhnu4K2GamAKC4QhxvUZyA,1187
 hwpx/_document/__init__.py,sha256=gJ7N5W4EANv_341NJCtbxSh0QrNIBtArRAnjJUe_PE4,98
@@ -20,7 +22,7 @@ hwpx/_document/fields.py,sha256=YvrbWyjcDtZDrWSMQkR31maCpYvhwYEWkNtxTFVxXGY,1969
 hwpx/_document/layout.py,sha256=2Y3JUnN5-_zZHg0CxfXq4nl8MjqFoqQbSlgszCCzJ6g,23097
 hwpx/_document/media.py,sha256=F3iquwS7V-luiBVg7H8Aq1DpNXNClPDmO1ug99dLyhw,11600
 hwpx/_document/memos.py,sha256=LBr5OPKLQMm4cHFIg9HohcMyKbf8DPpdmR3jeiyRNMg,7489
-hwpx/_document/persistence.py,sha256=dZDXRLdKjjN6JAjVnJAZngXhMvwJp4WgYcZGgd0vvX8,15978
+hwpx/_document/persistence.py,sha256=gPxo7alBywBPBu3iACeQs_gK3w3ruFd2K7J90cr4Keo,16011
 hwpx/_document/shapes.py,sha256=RoDtvlGvLshIKMsqDbiKfGz0pin63qkLHVtWGbdzb-0,6165
 hwpx/_document/tracked.py,sha256=ni4tglO1LuukTnRz6I__9kW0P8uYCSy9BEuxZMrinqc,3423
 hwpx/agent/__init__.py,sha256=jMMxl9cvGrRtdX669yNmLzrk_CK3UlhXGjXQHy4ERpo,3400
@@ -106,7 +108,7 @@ hwpx/form_fit/measure.py,sha256=gnSfqccm7_3oTKv3HH6Zs77r2bToxzmfvUWN2zshDE8,2232
 hwpx/form_fit/policy.py,sha256=iXAatjS7ZycOdKgMCL4Q_kYg0qnogFPdRNlr_ecOvjc,3106
 hwpx/form_fit/report.py,sha256=h1NzQfbj1JYvZtKUi0DckJNWGnUHMZtQ3iCzbUxUjHA,3305
 hwpx/form_fit/seal.py,sha256=QsPzFagaEi7UKAXS-iFwiZs8rLG-_Fo9RixLc2OaqbU,17640
-hwpx/form_fit/wordbox.py,sha256=bStyzpcK4PF3pihRUSKiStwW_XwYHDeU0D3Or_Eh0nM,48301
+hwpx/form_fit/wordbox.py,sha256=n86BegyBZMybf6Qxol6hWCG1r0EWiaJRyZEno_YkpIE,50170
 hwpx/ingest/__init__.py,sha256=cjDQwMdaqbq2xiD32zmaFAyzZbENga_6MLbgo0sLGZE,636
 hwpx/ingest/base.py,sha256=95jXJ70Hkay70BgyryGOzI3UVTixUpR-6f71iF3eqn4,8134
 hwpx/ingest/hwpx_converter.py,sha256=HOUCFYO-HK4WRpWiN5sA_kZIvdv439mkZ6PMCFU3hLg,4269
@@ -207,10 +209,10 @@ hwpx/visual/page_qa.py,sha256=AuJCySfLIdXjPeekhAc3YnrIWOsN0sI35Pnz8BZ6Pro,7278
 hwpx/visual/qa_contracts.py,sha256=1cjoiRTAWgi7NgE8SPc6bKxdoUfKx9nyou1mgC47TxY,10506
 hwpx/visual/qa_metrics.py,sha256=I7RdybN-f1Fvcv2j-ceDPoek51nOkMui1Zrd7TEX_C8,9838
 hwpx/visual/report.py,sha256=2RhXN1KBYOZTim9FNpeUhaaDHR7oFxI6Z2DLUkDIiwE,1717
-python_hwpx-3.8.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-3.8.0.dist-info/licenses/NOTICE,sha256=KJgtwIIzrXoA0j3PUhwp78ZtnucocEoB7jiuwoL4i7o,3060
-python_hwpx-3.8.0.dist-info/METADATA,sha256=O2fepIIHxJZFjeuuJZzzAVtvg6WvxiWxLdT03-vYCg0,20512
-python_hwpx-3.8.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_hwpx-3.8.0.dist-info/entry_points.txt,sha256=PVUBTBQtBHiflQ9XBjfd004w-LrDibgZjwzxgu8Tx7w,480
-python_hwpx-3.8.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-3.8.0.dist-info/RECORD,,
+python_hwpx-4.1.1.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
+python_hwpx-4.1.1.dist-info/licenses/NOTICE,sha256=KJgtwIIzrXoA0j3PUhwp78ZtnucocEoB7jiuwoL4i7o,3060
+python_hwpx-4.1.1.dist-info/METADATA,sha256=5R5nvsB-mwhZxnwU0KQG3wXscXzEBa6TjdvA4iknZhg,9164
+python_hwpx-4.1.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_hwpx-4.1.1.dist-info/entry_points.txt,sha256=PVUBTBQtBHiflQ9XBjfd004w-LrDibgZjwzxgu8Tx7w,480
+python_hwpx-4.1.1.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-4.1.1.dist-info/RECORD,,

python_hwpx-3.8.0.dist-info/METADATA

@@ -1,344 +0,0 @@
-Metadata-Version: 2.4
-Name: python-hwpx
-Version: 3.8.0
-Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
-Author: python-hwpx Maintainers
-License-Expression: Apache-2.0
-Project-URL: Homepage, https://github.com/airmang/python-hwpx
-Project-URL: Documentation, https://airmang.github.io/python-hwpx/
-Project-URL: Issues, https://github.com/airmang/python-hwpx/issues
-Keywords: hwp,hwpx,hancom,opc,xml,document-automation,validation,template
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: Text Processing :: Markup :: XML
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE
-Requires-Dist: lxml<7,>=4.9
-Provides-Extra: visual
-Requires-Dist: pymupdf>=1.24; extra == "visual"
-Requires-Dist: pillow>=10.0; extra == "visual"
-Requires-Dist: numpy>=1.26; extra == "visual"
-Provides-Extra: xlsx
-Requires-Dist: openpyxl>=3.1; extra == "xlsx"
-Provides-Extra: preview
-Requires-Dist: latex2mathml>=3.77; extra == "preview"
-Provides-Extra: dev
-Requires-Dist: build>=1.0; extra == "dev"
-Requires-Dist: twine>=4.0; extra == "dev"
-Requires-Dist: pytest>=7.4; extra == "dev"
-Requires-Dist: latex2mathml>=3.77; extra == "dev"
-Provides-Extra: test
-Requires-Dist: build>=1.0; extra == "test"
-Requires-Dist: numpy>=1.26; extra == "test"
-Requires-Dist: pillow>=10.0; extra == "test"
-Requires-Dist: pytest>=7.4; extra == "test"
-Requires-Dist: pytest-cov>=5.0; extra == "test"
-Requires-Dist: ruff>=0.12; extra == "test"
-Requires-Dist: latex2mathml>=3.77; extra == "test"
-Provides-Extra: typecheck
-Requires-Dist: mypy>=1.10; extra == "typecheck"
-Requires-Dist: pyright>=1.1.390; extra == "typecheck"
-Dynamic: license-file
-
-<p align="center">
-  <h1 align="center">python-hwpx</h1>
-  <p align="center">
-    <strong>한컴 없이 HWPX를 안전하게 자동화하는 Python 계층 — 최소 범위 편집, 검증된 저작, 모든 쓰기에 영수증.</strong>
-  </p>
-  <p align="center">
-    <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/v/python-hwpx?color=blue&label=PyPI" alt="PyPI"></a>
-    <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx" alt="Python"></a>
-    <a href="https://github.com/airmang/python-hwpx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
-    <a href="https://airmang.github.io/python-hwpx/"><img src="https://img.shields.io/badge/docs-Sphinx-8CA1AF" alt="Docs"></a>
-    <a href="https://github.com/airmang/python-hwpx/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx/tests.yml?branch=main&label=tests" alt="Tests"></a>
-    <a href="https://airmang.github.io/python-hwpx/corpus-metrics.html"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fairmang.github.io%2Fpython-hwpx%2F_static%2Fbadge-hancom-open.json" alt="Hancom open"></a>
-  </p>
-</p>
-
-<p align="center">한국어 | <a href="README_EN.md">English</a></p>
-
----
-
-> **python-hwpx는 한컴 없이 HWPX를 안전하게 자동화하는 Python 계층입니다.** 기존
-> 문서는 최소 범위만 수정하고, 새 문서는 실제 한컴 수용이 검증된 형태로 생성하며,
-> 모든 쓰기에 변경·보존·검증 영수증을 남기고, 완전한 해석과 렌더링은 전문 백엔드에
-> 위임할 수 있습니다.
-
-- **최소 범위 편집** — 미수정 part는 저장 시 바이트 그대로 유지됩니다(patch 경로
-  바이트 보존 497/497, 동결 코퍼스 v2 · 2026-07-19).
-- **검증된 저작** — 밑바닥 생성도 실제 한컴이 받아들이는 형태로 냅니다(산출물 한컴
-  오픈 476/476 all-pass, 실저작 품질 게이트 58/58).
-- **모든 쓰기에 영수증** — 대표 저장 경로는 [Safe Write Contract](docs/safe-write-contract.md)의
-  `MutationReport`(`hwpx.mutation-report/v1`)로 실제 쓰기 모드·보존 등급·검증 결과를
-  **측정해** 반환합니다.
-
----
-
-## 🧩 HWPX Stack (3종)
-
-| 계층 | 레포 | 역할 |
-|---|---|---|
-| 📦 라이브러리 | **[`python-hwpx`](https://github.com/airmang/python-hwpx)** | 순수 파이썬 HWPX 파싱·편집·생성 코어 |
-| 🔌 MCP 서버 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작 |
-| 🎯 에이전트 스킬 | [`hwpx-plugin`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 first-party 플러그인·스킬 번들 |
-
-`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동
-구성요소입니다(유지보수 관계를 뜻하며, 한컴 등 외부 기관의 인증을 뜻하지 않습니다).
-
-현재 PyPI 공개 릴리스는 `python-hwpx 3.8.0`입니다. 일반
-`pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
-현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
-성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
-
----
-
-## 실측으로 말합니다 — Published Corpus
-
-이 스택의 산출물은 주장 대신 **실제 한컴오피스 전수 측정**으로 검증됩니다
-(동결 코퍼스 v2, N=497 산출물, 2026-07-19, 실한컴 12.0.0.3288 COM/GUI 오라클;
-상세·주의사항은
-[실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)):
-
-- **한컴 오픈 수용률 476/476 all-pass** (동결 코퍼스 v2 · 2026-07-19 · 실한컴 COM
-  `Open()` 판정 · rule-of-three 하한 99.37%) · 파싱 96.2%(458/476)
-- **미수정 영역 바이트 보존 497/497** (patch 경로 한정, zip-part diff · 오라클 불요)
-  · **개인정보 0-leak** (35문서/합성 140값)
-- 렌더 검증 416/476 (실한컴 `SaveAs("PDF")`) + 정직 버킷 43건(변경추적 문서의 PDF
-  export는 한컴 자체가 거부 — 실측 한계로 발행) + 미검증 17건
-- wild 공개 양식 채움은 구조결함 픽스 후 **무음 서식파괴 16.7%**(판정 66조합, 못 담는 타깃은 typed 거부 35건·산출분 pass 17/28) — **낮은 숫자도 그대로 발행**하고 잔여(페이지 리플·표 shape)를 명명합니다
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/images/redline-hancom.png" alt="python-hwpx가 남긴 변경추적과 AI 에이전트 메모가 실제 한/글에서 열린 화면" width="720">
-</p>
-<p align="center"><sub>python-hwpx로 작성한 변경추적(취소선·삽입)과 AI 에이전트 메모 — 실제 한/글에서 연 화면입니다.</sub></p>
-
-> 이 숫자들은 *생성물 수용률* 축입니다(우리가 만든 파일을 실제 한컴이 받아들이는가).
-> 문서 *파싱 recall*과는 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
-
----
-
-## 왜 python-hwpx인가
-
-- **코어 편집에 한컴오피스 설치 불필요** — HWPX는 ZIP+XML(OWPML/OPC) 구조라, 순수 파이썬으로 Windows·macOS·Linux·CI 어디서나 읽고 씁니다.
-- **읽기부터 생성까지 한 코어** — 텍스트/서식 추출, 문단·표·양식 편집, 새 문서 생성, XSD 스키마 검증을 하나의 API로 처리합니다.
-- **에이전트·자동화 친화** — 같은 프로젝트가 유지보수하는 `hwpx-mcp-server`와 `hwpx-plugin`이 코어에 연결됩니다.
-
-문서 파싱·편집·생성은 순수 Python으로 수행할 수 있습니다. 다만 페이지 나눔, 표 넘침,
-글꼴 대체 등 최종 시각 품질을 확언하려면 필요에 따라 실제 한컴 렌더 오라클을 별도로 사용합니다.
-
-## 빠른 시작
-
-```bash
-pip install python-hwpx      # Python 3.10+ · lxml ≥ 4.9
-```
-
-```python
-from hwpx import HwpxDocument
-
-# 기존 문서 열기 → 편집 → 저장
-doc = HwpxDocument.open("보고서.hwpx")
-doc.add_paragraph("자동화로 추가한 문단입니다.")
-doc.save_to_path("보고서-수정.hwpx")
-
-# 새 문서 만들기
-new = HwpxDocument.new()
-new.add_paragraph("python-hwpx로 만든 새 문서")
-new.save_to_path("새문서.hwpx")
-```
-
-> 💡 컨텍스트 매니저도 지원합니다 — `with` 블록을 벗어나면 리소스가 자동 정리됩니다:
-> ```python
-> with HwpxDocument.open("보고서.hwpx") as doc:
->     doc.add_paragraph("자동으로 리소스가 정리됩니다.")
->     doc.save_to_path("결과물.hwpx")
-> ```
-
-`open`/`new` → `edit`/`extract` → `save_to_path` 흐름만 잡으면 나머지는 필요할 때 확장하면 됩니다.
-
-## 무엇을 하나
-
-### 🔍 읽기 · 추출
-- 텍스트/HTML/Markdown 내보내기 — `export_text()` · `export_html()` · `export_markdown()`
-- **풍부한 Markdown** — `export_rich_markdown()`은 인라인 서식(`**굵게**`·`*기울임*`·`~~취소선~~`), 중첩 표(colspan/rowspan 안전), 도형 텍스트, 이미지, 각주/미주, 하이퍼링크, 제목(`#`/`##`) 자동 감지까지 보존
-- **문서 ingest 게이트웨이** — `hwpx.ingest.DocumentIngestor`가 HWPX를 감지해 rich Markdown과 섹션/표 메타데이터로 정규화
-- `TextExtractor` / `ObjectFinder` — 섹션·문단 순회, 태그·속성·XPath로 객체 탐색 (`hp:tab`은 `\t`로 보존, roundtrip 안전)
-
-```python
-doc = HwpxDocument.open("보고서.hwpx")
-md = doc.export_rich_markdown(
-    image_dir="out/images",       # BinData 이미지를 디스크에 추출
-    image_ref_prefix="images/",   # 마크다운 내 ![](images/...) 경로 접두
-    detect_headings=True,         # Ⅰ./1. 패턴 기반 #/## 자동
-)
-```
-
-### ✏️ 편집
-- 문단 추가/삭제/서식, Run 단위 볼드·이탤릭·밑줄·색상
-- 섹션 추가/삭제(`add_section(after=)`·`remove_section()`, manifest 자동 관리)
-- 표 생성·셀 텍스트·병합/분할·중첩 테이블, 이미지 임베드, 머리글/바닥글, 메모(앵커 기반), 각주/미주, 북마크/하이퍼링크, 다단 편집
-- **기존 문서 서식 편집** — 정렬·줄간격·들여쓰기·문단 간격, 용지·여백·방향, 쪽번호, 불릿/번호
-- **스타일 기반 치환** — 색상·밑줄·`charPrIDRef`로 Run을 필터링해 선택 교체(`replace_text_in_runs`·`find_runs_by_style`)
-
-```python
-# 빨간색 텍스트만 찾아서 치환
-doc.replace_text_in_runs("임시", "확정", text_color="#FF0000")
-```
-
-### 🖊️ 양식 채우기 (byte-preserving)
-- 누름틀(클릭히어) 필드 조회·서식 보존 채움, 라벨 기반 셀 탐색(`find_cell_by_label`)·경로 채우기(`fill_by_path`)
-- **바이트 보존 구조 편집** — 셀 채우기 / 행·열·표 삭제·삽입 / 열 너비 오토핏 / 폰트 shrink-to-fit 을 문서 재조립 없이 수행해 양식 서식을 그대로 보존. 미수정 영역은 `hwpx.patch`가 section XML 바이트를 splice해 손대지 않음
-
-```python
-doc = HwpxDocument.open("신청서.hwpx")
-result = doc.fill_by_path({
-    "성명 > right": "홍길동",
-    "소속 > right": "플랫폼팀",
-})
-doc.save_to_path("신청서-작성완료.hwpx")
-print(result["applied_count"], result["failed_count"])
-```
-
-### 🏗️ 생성 · 공문서 도구
-- `hwpx.builder` — Section/Heading/Table/Image/Header 조립형 생성 + 하드게이트 저장 리포트
-- 공문서 도구 — `official_lint`(항목기호 위계·"끝." 표시·붙임·날짜 lint), 결재란 프리셋
-- `advanced_generators` — 사진대지(image_grid)·회의 명패·표 기반 조직도
-- `mail_merge` — 템플릿+데이터 N부 대량 생성, 표 합계·평균 계산
-- `doc_diff` — 문단 LCS diff·신구대조표·참조 정합 lint
-- `style_profile` — 참조 문서 프로파일 추출·적용, 템플릿 레지스트리
-
-### ✅ 검증 · 안전 · 저수준
-- XSD 스키마 + 패키지 구조 검증 — CLI `hwpx-validate` · `hwpx-validate-package`, `hwpx-analyze-template`
-- `validate_editor_open_safety` — 저장/팩/리페어/빌더 출력 게이트, `openSafety` 증거 반환
-- `hwpx.tools.fuzz`(시드 결정적 시나리오·3중 오라클) · `hwpx.tools.layout_preview`(페이지 박스 근사 HTML/PNG 자기검증) · `opc.security`(XML entity·ZIP 압축 폭탄 가드)
-- `hwpx.oxml` 데이터클래스로 OWPML 스키마 ↔ Python 객체 직접 조작, HWPML 2016→2011 네임스페이스 자동 정규화
-
-```bash
-hwpx-validate-package 보고서.hwpx
-hwpx-analyze-template 보고서.hwpx
-```
-
-> 전체 기능·클래스·메서드 목록은 [사용 가이드](docs/usage.md)와 [API 레퍼런스](https://airmang.github.io/python-hwpx/api_reference.html)를 참고하세요.
-
-## 안전한 쓰기 계약 (Safe Write Contract)
-
-대표 저장 경로(`save_to_path` · `save_to_stream` · `to_bytes`)는 **요청한 보존 등급을
-쓰기 전에 판정하고, 실제로 무엇을 바꿨는지 측정한 영수증**을 돌려줍니다.
-
-```python
-from hwpx.mutation_report import PreservationDowngradeError
-
-# 영수증과 함께 저장 — 달성 가능한 가장 강한 보존 등급 자동 선택(mode="auto" 기본)
-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}
-
-# patch 등급 강제 — 미달이면 아무것도 쓰지 않고 예외(fail-closed)
-try:
-    doc.save_to_path("결과.hwpx", mode="patch", fallback="error")
-except PreservationDowngradeError as exc:
-    print(exc.offending_parts, exc.suggestion)
-```
-
-- `mode="patch" | "rebuild" | "auto"`(기본 `auto`) · `fallback="error" | "rebuild"`(기본 `error`)
-- `mode="patch"` + `fallback="error"`에서 미수정 part의 바이트 동일성을 지킬 수 없으면
-  **아무것도 쓰지 않고** `PreservationDowngradeError`를 던집니다(무음 rebuild 없음).
-- `MutationReport`는 `requestedMode`/`actualMode`/`fallbackUsed`, 변경 part와 좌표 명시
-  범위, 보존 3층(part 페이로드·ZIP 레코드·전체 패키지), 검증 3항목(`passed`/`failed`/`not_performed`)을
-  **측정해** 반환합니다.
-
-> 파라미터 전체와 `MutationReport` 스키마는 [안전한 쓰기 계약 문서](docs/safe-write-contract.md)를 참고하세요.
-
-## 지원 매트릭스
-
-능력 영역별 실제 등급입니다(동결 코퍼스 v2 · 2026-07-19 · 실한컴 12.0.0.3288 오라클).
-등급 어휘: **Parse / Preserve / Edit / Create / Render-verified /
-Unsupported-but-preserved / Unsupported-and-rejected**.
-
-| 능력 영역 | 상태 | 증거 |
-|---|---|---|
-| 문단·표 저작/편집 | Parse·Preserve·Edit·Create·Render-verified | 오픈 476/476 · 실저작 게이트 58/58 · 렌더 416 |
-| 표 구조 변경(행·열·표, 오토핏) | Preserve·Edit | `hwpx.table_patch` · 바이트 보존 497/497 |
-| 양식 채움(byte-splice) | Preserve·Edit | `hwpx.patch`·`table_patch`·`body_patch` · 보존 497/497 (wild 무음 서식파괴 16.7%·typed 거부 35/66, 잔여 명명) |
-| 그림 삽입/치환 | Edit·Create | `add_picture`·`replace_picture` (복잡 개체는 한컴 확인 권장) |
-| 차트 | Unsupported-but-preserved | 생성 API 없음 · 기존 차트 part는 patch 보존 |
-| 수식 | Parse·Unsupported-but-preserved | 저작 API 없음 · 기존 수식 파싱·patch 보존 |
-| 변경추적(redline) | Edit·Create | `add_tracked_*` · 실한컴 `IsTrackChange=1` (한컴이 PDF export 거부 → `render_unavailable` 정직 집계) |
-| 메모(코멘트) | Edit·Create·Render-verified | `add_memo*` · 실 Windows 한컴 검증 |
-| 각주/미주 | Edit·Create | `add_footnote`·`add_endnote` (렌더 독립 게이트 미측정) |
-| 네이티브 목차/상호참조 | Create·Render-verified | `add_native_toc`·`toc_verify` · 구조 15/15 · 페이지 정합 5/5 |
-| 암호화 HWPX | Unsupported-and-rejected | 복호화 없음 · 암호화 part는 파싱 단계 예외로 거부 |
-| HWP 5.x 바이너리 | Unsupported-and-rejected | ZIP 아님 → 열기 시 `BadZipFile` (HWPX로 변환 후 사용) |
-| 누름틀(form field) 생성 | Parse·Edit | 기존 필드 조회·서식보존 채움 · **신규 누름틀 생성 도구는 미제공** |
-
-> 각 등급의 판정 근거와 상세 증거 포인터는 [지원 매트릭스 문서](docs/support-matrix.md)를 참고하세요.
-
-## 대항 라이브러리 비교
-
-| | python-hwpx | pyhwpx | pyhwp |
-|---|---|---|---|
-| **대상 포맷** | `.hwpx` (OWPML/OPC) | `.hwpx` | `.hwp` (v5 바이너리) |
-| **한/글 설치** | 불필요 | 필요 (Windows COM) | 불필요 |
-| **크로스 플랫폼** | ✅ Linux / macOS / Windows / CI | ❌ Windows 전용 | ✅ |
-| **편집/생성 API** | ✅ | ✅ (COM) | ❌ 대부분 읽기 |
-| **스키마 검증** | ✅ | ❌ | ❌ |
-| **AI 에이전트 연동 (MCP)** | ✅ `hwpx-mcp-server` | ❌ | ❌ |
-
-> HWP(v5 바이너리) 파일은 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.
-
-## 알려진 제약
-
-- `add_shape()` / `add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않습니다. 복잡한 개체 추가 시 한/글에서 열어 검증하세요.
-- 이미지 바이너리 임베드는 지원하지만 `<hp:pic>` 요소의 완전 자동 생성은 제공하지 않습니다.
-- 암호화된 HWPX 파일의 암복호화는 지원하지 않습니다.
-
-## 더 보기
-
-- **[🚀 빠른 시작](docs/quickstart.md)** · **[📚 사용 가이드](docs/usage.md)** — 첫 파일 열기부터 문단·표·메모·섹션 편집, 텍스트 추출·검증까지
-- **[💡 예제 모음](docs/examples.md)** · [`examples/`](examples/) — `build_release_checklist.py`(메모·스타일 편집 HWPX 생성), `extract_text.py`(CLI 텍스트 추출), `find_objects.py`(OWPML 노드 추적) 등
-- **[📐 스키마 개요](docs/schema-overview.md)** · **[🔧 설치 검증](docs/installation.md)**
-- **[🔬 HWPX 내부 실전 가이드](docs/internals/)** — 실제 한/글 동작에서 확인된 HWPUNIT·조판 캐시·목차 필드·OPC 재패킹·메모·오라클 한계
-- **[📖 전체 문서 (Sphinx)](https://airmang.github.io/python-hwpx/)** — API 레퍼런스·50+ 실전 패턴·FAQ
-- **[📝 CHANGELOG](CHANGELOG.md)** · **[🤝 CONTRIBUTING](CONTRIBUTING.md)** · **[👥 CONTRIBUTORS](CONTRIBUTORS.md)**
-
-## 기여하기
-
-버그 리포트, 기능 제안, PR 모두 환영합니다.
-
-- **[help wanted 이슈](https://github.com/airmang/python-hwpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)** — 지금 들어오기 좋은 입구입니다. 시작 전에 이슈에 코멘트로 방향을 남겨주세요.
-- **[마일스톤](https://github.com/airmang/python-hwpx/milestones)** — 공개 로드맵입니다. 프로젝트가 어디로 가는지 여기서 보입니다.
-- **[Discussions](https://github.com/airmang/python-hwpx/discussions)** — 질문·아이디어는 이슈 대신 여기로.
-- **[내부 실전 가이드](docs/internals/)** — HWPX 내부 구조가 처음이라면 여기부터. 개발 흐름은 [CONTRIBUTING.md](CONTRIBUTING.md)에 있습니다.
-
-```bash
-git clone https://github.com/airmang/python-hwpx.git
-cd python-hwpx
-pip install -e ".[dev]"
-pytest
-```
-
-## 감사의 말
-
-아래 공개 표준·프로젝트에 빚지고 있습니다.
-
-- **[OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101)](https://www.kssn.net/search/stddetail.do?itemNo=K001010119985)** — HWPX가 기반하는 한국 산업 표준
-- **[hancom-io/hwpx-owpml-model](https://github.com/hancom-io/hwpx-owpml-model)** — OWPML 요소 구조 참조 모델 · **[neolord0/hwpxlib](https://github.com/neolord0/hwpxlib)** — 오라클 샘플 코퍼스
-- **[edwardkim/rhwp](https://github.com/edwardkim/rhwp)** — 멱등성·검증 게이트 설계 영감
-- **범정부오피스** — 공무 문서 편집 워크플로 아이디어
-
-## License
-
-Apache License 2.0. See LICENSE and NOTICE.
-
-## Maintainer
-
-Primary maintainer/contact: **Kohkyuhyun** ([@airmang](https://github.com/airmang))
-
-- ✉️ [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)
-- 🐙 [@airmang](https://github.com/airmang)