python-hwpx 2.10.1__tar.gz → 2.10.3__tar.gz

{python_hwpx-2.10.1/src/python_hwpx.egg-info → python_hwpx-2.10.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 2.10.1
+Version: 2.10.3
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -115,6 +115,47 @@ hwpx-validate-package 보고서.hwpx
 hwpx-analyze-template 보고서.hwpx
 ```
 
+### 4. 풍부한 Markdown 변환 (서식·표·각주·이미지 보존)
+
+`export_markdown()`는 단순 평문 추출이고, `export_rich_markdown()`는 인라인 서식(`**굵게**`, `*기울임*`, `~~취소선~~`),
+표(중첩 포함, colspan/rowspan 안전), 도형 텍스트, 이미지, 각주/미주, 하이퍼링크, 제목(`#`/`##`) 자동 감지까지 보존한다.
+
+```python
+from hwpx import HwpxDocument
+
+doc = HwpxDocument.open("보고서.hwpx")
+
+md = doc.export_rich_markdown(
+    image_dir="out/images",          # BinData 이미지를 디스크에 추출
+    image_ref_prefix="images/",      # 마크다운 내 ![](images/...) 경로 접두
+    detect_headings=True,            # Ⅰ./1. 패턴 기반 #/## 자동
+)
+print(md)
+```
+
+문자열·경로·바이트도 그대로 받는다:
+
+```python
+from hwpx.tools.markdown_export import export_markdown
+
+md = export_markdown("보고서.hwpx")          # 경로
+md = export_markdown(open("a.hwpx", "rb").read())  # bytes
+```
+
+### 5. 각주 본문에 혼합 서식 / 하이퍼링크 추가
+
+`HwpxOxmlNote`에 `body_paragraph`, `add_run`, `add_hyperlink` helper가 있어 각주 본문을
+직접 paragraph로 다루지 않고도 인라인 서식·링크를 손쉽게 채울 수 있다.
+
+```python
+para = section.paragraphs[0]
+note = para.add_footnote("")  # 빈 각주 생성 후 본문 구성
+note.add_run("자세한 내용은 ", )
+note.add_run("정부 공식 사이트", bold=True)
+note.add_run("를 참고하라: ")
+note.add_hyperlink("https://www.kasa.go.kr", "우주항공청")
+```
+
 처음에는 `open/new -> edit/extract -> save_to_path` 흐름만 잡으면 된다. 패키지 구조, XML 파트, 템플릿 회귀 점검은 필요할 때만 확장하면 된다.
 
 ## 어디부터 읽으면 되나
@@ -244,6 +285,7 @@ doc.set_footer_text("1 / 10", page_type="BOTH")
 # 표 셀 병합·분할
 table.merge_cells(0, 0, 1, 1)   # (0,0)~(1,1) 병합
 table.set_cell_text(0, 0, "병합된 셀", logical=True, split_merged=True)
+table.set_cell_text(0, 0, "line 1\nline 2", split_paragraphs=True)
 
 # 양식형 표 자동 채우기
 form = doc.add_table(2, 2)
@@ -257,6 +299,12 @@ doc.fill_by_path({
 })
 ```
 
+`doc.paragraphs`의 인덱스는 본문 직속 문단 0-based 기준입니다. 표 안 문단은
+본문 `paragraph_index`에 섞지 않고 `get_table_map()`의 cell `location`
+(`table_index`, `row`, `col`, `cell_paragraph_index`)으로 다룹니다.
+`get_table_map()`은 `caption_text`와 `preceding_paragraph_text`를 분리해
+반환하고, 셀 미리보기의 여러 문단은 `\n`으로 유지합니다.
+
 ### 🔍 텍스트 추출 & 검색
 
 ```python

{python_hwpx-2.10.1 → python_hwpx-2.10.3}/README.md

@@ -79,6 +79,47 @@ hwpx-validate-package 보고서.hwpx
 hwpx-analyze-template 보고서.hwpx
 ```
 
+### 4. 풍부한 Markdown 변환 (서식·표·각주·이미지 보존)
+
+`export_markdown()`는 단순 평문 추출이고, `export_rich_markdown()`는 인라인 서식(`**굵게**`, `*기울임*`, `~~취소선~~`),
+표(중첩 포함, colspan/rowspan 안전), 도형 텍스트, 이미지, 각주/미주, 하이퍼링크, 제목(`#`/`##`) 자동 감지까지 보존한다.
+
+```python
+from hwpx import HwpxDocument
+
+doc = HwpxDocument.open("보고서.hwpx")
+
+md = doc.export_rich_markdown(
+    image_dir="out/images",          # BinData 이미지를 디스크에 추출
+    image_ref_prefix="images/",      # 마크다운 내 ![](images/...) 경로 접두
+    detect_headings=True,            # Ⅰ./1. 패턴 기반 #/## 자동
+)
+print(md)
+```
+
+문자열·경로·바이트도 그대로 받는다:
+
+```python
+from hwpx.tools.markdown_export import export_markdown
+
+md = export_markdown("보고서.hwpx")          # 경로
+md = export_markdown(open("a.hwpx", "rb").read())  # bytes
+```
+
+### 5. 각주 본문에 혼합 서식 / 하이퍼링크 추가
+
+`HwpxOxmlNote`에 `body_paragraph`, `add_run`, `add_hyperlink` helper가 있어 각주 본문을
+직접 paragraph로 다루지 않고도 인라인 서식·링크를 손쉽게 채울 수 있다.
+
+```python
+para = section.paragraphs[0]
+note = para.add_footnote("")  # 빈 각주 생성 후 본문 구성
+note.add_run("자세한 내용은 ", )
+note.add_run("정부 공식 사이트", bold=True)
+note.add_run("를 참고하라: ")
+note.add_hyperlink("https://www.kasa.go.kr", "우주항공청")
+```
+
 처음에는 `open/new -> edit/extract -> save_to_path` 흐름만 잡으면 된다. 패키지 구조, XML 파트, 템플릿 회귀 점검은 필요할 때만 확장하면 된다.
 
 ## 어디부터 읽으면 되나
@@ -208,6 +249,7 @@ doc.set_footer_text("1 / 10", page_type="BOTH")
 # 표 셀 병합·분할
 table.merge_cells(0, 0, 1, 1)   # (0,0)~(1,1) 병합
 table.set_cell_text(0, 0, "병합된 셀", logical=True, split_merged=True)
+table.set_cell_text(0, 0, "line 1\nline 2", split_paragraphs=True)
 
 # 양식형 표 자동 채우기
 form = doc.add_table(2, 2)
@@ -221,6 +263,12 @@ doc.fill_by_path({
 })
 ```
 
+`doc.paragraphs`의 인덱스는 본문 직속 문단 0-based 기준입니다. 표 안 문단은
+본문 `paragraph_index`에 섞지 않고 `get_table_map()`의 cell `location`
+(`table_index`, `row`, `col`, `cell_paragraph_index`)으로 다룹니다.
+`get_table_map()`은 `caption_text`와 `preceding_paragraph_text`를 분리해
+반환하고, 셀 미리보기의 여러 문단은 `\n`으로 유지합니다.
+
 ### 🔍 텍스트 추출 & 검색
 
 ```python

{python_hwpx-2.10.1 → python_hwpx-2.10.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "2.10.1"
+version = "2.10.3"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"

{python_hwpx-2.10.1 → python_hwpx-2.10.3}/src/hwpx/__init__.py

@@ -25,6 +25,12 @@ from .tools.text_extractor import (
     TextExtractor,
 )
 from .tools.object_finder import FoundElement, ObjectFinder
+from .tools.package_validator import (
+    EditorOpenSafetyReport,
+    PackageValidationReport,
+    validate_editor_open_safety,
+    validate_package,
+)
 from .document import HwpxDocument
 from .package import HwpxPackage
 from .authoring import (
@@ -58,7 +64,9 @@ __all__ = [
     "DocumentBlock",
     "DocumentPlan",
     "DocumentStylePreset",
+    "EditorOpenSafetyReport",
     "ParagraphInfo",
+    "PackageValidationReport",
     "PlanValidationReport",
     "SectionInfo",
     "TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION",
@@ -76,4 +84,6 @@ __all__ = [
     "inspect_operating_plan_quality",
     "normalize_document_plan",
     "validate_document_plan",
+    "validate_editor_open_safety",
+    "validate_package",
 ]

{python_hwpx-2.10.1 → python_hwpx-2.10.3}/src/hwpx/builder/core.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from hwpx.document import HwpxDocument
+from hwpx.tools.package_validator import validate_editor_open_safety
 from hwpx.tools.package_validator import validate_package
 from hwpx.tools.validator import validate_document
 
@@ -576,13 +577,24 @@ def _merge_flags(*flag_sets: dict[str, bool]) -> dict[str, bool]:
     return merged
 
 
-def _hard_gates(package_report: object, document_report: object, reopen_report: ReopenReport) -> dict[str, str]:
+def _hard_gates(
+    package_report: object,
+    document_report: object,
+    reopen_report: ReopenReport,
+    editor_open_safety_report: object | None = None,
+) -> dict[str, str]:
     document_warnings = getattr(document_report, "warnings", ())
+    editor_open_safety_ok = (
+        True
+        if editor_open_safety_report is None
+        else bool(getattr(editor_open_safety_report, "ok", False))
+    )
     return {
         "package_validation": "pass" if getattr(package_report, "ok", False) else "fail",
         "document_errors": "pass" if getattr(document_report, "ok", False) else "fail",
         "schema_lint": "warning" if document_warnings else "pass",
         "reopen": "pass" if reopen_report.ok else "fail",
+        "editor_open_safety": "pass" if editor_open_safety_ok else "fail",
         "id_integrity": "unavailable",
     }
 
@@ -696,6 +708,7 @@ class Document:
         document.save_to_path(path)
         package_report = validate_package(path)
         document_report = validate_document(path)
+        editor_open_safety_report = validate_editor_open_safety(path)
         try:
             reopened_document = HwpxDocument.open(path)
             reopen_report = ReopenReport(ok=True, document=reopened_document)
@@ -713,8 +726,14 @@ class Document:
             validate_document=document_report,
             reopened=reopen_report,
             metadata=self.metadata.as_dict() if self.metadata is not None else {},
-            hard_gates=_hard_gates(package_report, document_report, reopen_report),
+            hard_gates=_hard_gates(
+                package_report,
+                document_report,
+                reopen_report,
+                editor_open_safety_report,
+            ),
             visual_review_required=visual_review_required,
             feature_flags=feature_flags,
+            editor_open_safety=editor_open_safety_report,
         )
         return report

{python_hwpx-2.10.1 → python_hwpx-2.10.3}/src/hwpx/builder/report.py

@@ -6,7 +6,7 @@ from os import PathLike
 from typing import Any
 
 from hwpx.tools.id_integrity import IdIntegrityReport, check_id_integrity
-from hwpx.tools.package_validator import PackageValidationReport
+from hwpx.tools.package_validator import EditorOpenSafetyReport, PackageValidationReport
 from hwpx.tools.validator import ValidationReport
 
 
@@ -32,6 +32,7 @@ class BuilderSaveReport:
     visual_review_required: bool = False
     feature_flags: dict[str, bool] = field(default_factory=dict)
     id_integrity: IdIntegrityReport | None = None
+    editor_open_safety: EditorOpenSafetyReport | None = None
 
     def __post_init__(self) -> None:
         hard_gates = dict(self.hard_gates)
@@ -52,6 +53,11 @@ class BuilderSaveReport:
             "hard_gates": dict(self.hard_gates),
             "visual_review_required": self.visual_review_required,
             "feature_flags": dict(self.feature_flags),
+            "editor_open_safety": (
+                None
+                if self.editor_open_safety is None
+                else self.editor_open_safety.to_dict()
+            ),
             "validate_package": {
                 "ok": self.validate_package.ok,
                 "checked_parts": list(self.validate_package.checked_parts),

{python_hwpx-2.10.1 → python_hwpx-2.10.3}/src/hwpx/document.py

@@ -5,12 +5,15 @@ from __future__ import annotations
 
 import xml.etree.ElementTree as ET
 import io
+import os
+import tempfile
 import warnings
 from datetime import datetime
 import logging
 import uuid
 
 from os import PathLike
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, BinaryIO, Iterator, Mapping, Sequence, overload
 
 from lxml import etree
@@ -39,7 +42,10 @@ from .oxml import (
     TrackChange,
     TrackChangeAuthor,
 )
-from .opc.package import HwpxPackage
+from .opc.package import (
+    HwpxPackage,
+    _UNCHECKED_SAVE_TOKEN,
+)
 from .oxml.namespaces import HH, HH_NS, HP, HP_NS, register_owpml_namespaces
 from .templates import blank_document_bytes
 
@@ -83,6 +89,91 @@ def _png_dimensions(image_data: bytes) -> tuple[int, int] | None:
     return width, height
 
 
+def _write_bytes_atomically(path: str | PathLike[str], data: bytes) -> None:
+    target = Path(path)
+    fd, tmp_path = tempfile.mkstemp(dir=str(target.parent), suffix=".hwpx.tmp")
+    try:
+        with os.fdopen(fd, "wb") as tmp_fh:
+            tmp_fh.write(data)
+        os.replace(tmp_path, str(target))
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def _capture_stream_checkpoint(stream: BinaryIO) -> tuple[int, bytes] | None:
+    try:
+        position = stream.tell()
+    except (AttributeError, OSError):
+        return None
+    try:
+        tail = stream.read()
+    except (AttributeError, OSError):
+        try:
+            end_position = stream.seek(0, os.SEEK_END)
+        except (AttributeError, OSError):
+            return None
+        try:
+            stream.seek(position)
+        except (AttributeError, OSError):
+            return None
+        if end_position == position:
+            return position, b""
+        return None
+    try:
+        stream.seek(position)
+    except (AttributeError, OSError):
+        return None
+    return position, tail
+
+
+def _rollback_stream(stream: BinaryIO, checkpoint: tuple[int, bytes] | None) -> None:
+    if checkpoint is None:
+        return
+    position, tail = checkpoint
+    try:
+        stream.seek(position)
+        if tail:
+            stream.write(tail)
+            stream.truncate(position + len(tail))
+        else:
+            stream.truncate(position)
+        stream.seek(position)
+    except (AttributeError, OSError):
+        return
+
+
+def _write_stream_or_rollback(stream: BinaryIO, data: bytes) -> None:
+    checkpoint = _capture_stream_checkpoint(stream)
+    if checkpoint is None:
+        raise OSError(
+            "HWPX stream save requires a checkpointable stream; "
+            "use save_to_path() for non-seekable outputs"
+        )
+    try:
+        written = stream.write(data)
+        if written is not None and written != len(data):
+            raise OSError(
+                "short write while saving HWPX stream: "
+                f"wrote {written} of {len(data)} bytes"
+            )
+    except BaseException:
+        _rollback_stream(stream, checkpoint)
+        raise
+
+
+def _summarize_validation_issues(issues: Sequence[Any], *, limit: int = 5) -> str:
+    selected = [str(issue) for issue in issues[:limit]]
+    remaining = len(issues) - len(selected)
+    summary = "; ".join(selected)
+    if remaining > 0:
+        summary += f" ... and {remaining} more"
+    return summary
+
+
 class HwpxDocument:
     """Provides a user-friendly API for editing HWPX documents."""
 
@@ -1472,6 +1563,14 @@ class HwpxDocument:
         from .tools.exporter import export_markdown
         return export_markdown(self, **kwargs)  # type: ignore[arg-type]
 
+    def export_rich_markdown(self, **kwargs: object) -> str:
+        """Export rich Markdown preserving inline styles, tables, footnotes, hyperlinks, images, and shape text.
+
+        Keyword args forwarded to :func:`~hwpx.tools.markdown_export.export_markdown`.
+        """
+        from .tools.markdown_export import export_markdown as _rich
+        return _rich(self, **kwargs)  # type: ignore[arg-type]
+
     # ------------------------------------------------------------------
     # Validation
     # ------------------------------------------------------------------
@@ -1485,7 +1584,9 @@ class HwpxDocument:
         """
         from .tools.validator import validate_document
 
-        return validate_document(self._to_bytes_raw(reset_dirty=False))
+        return validate_document(
+            self._to_bytes_for_validation()
+        )
 
     def _run_pre_save_validation(self) -> None:
         """Raise if validate_on_save is enabled and the document is invalid."""
@@ -1493,29 +1594,38 @@ class HwpxDocument:
             return
         report = self.validate()
         if not report.ok:
-            msgs = "; ".join(str(i) for i in report.issues[:5])
-            remaining = len(report.issues) - 5
-            if remaining > 0:
-                msgs += f" … and {remaining} more"
+            msgs = _summarize_validation_issues(report.issues)
             raise ValueError(f"Document validation failed: {msgs}")
 
+    def _run_open_safety_validation(self, archive_bytes: bytes) -> None:
+        """Raise if generated bytes are unsafe to hand to an HWPX editor."""
+
+        from .tools.package_validator import validate_editor_open_safety
+
+        report = validate_editor_open_safety(archive_bytes)
+        if not report.ok:
+            raise ValueError(
+                "Generated HWPX package failed open-safety validation: "
+                + report.summary
+            )
+
     def save_to_path(self, path: str | PathLike[str]) -> str | PathLike[str]:
         """Persist pending changes to *path* and return the same path."""
 
         self._run_pre_save_validation()
-        updates = self._root.serialize()
-        result = self._package.save(path, updates)
-        self._root.reset_dirty()
-        return path if result is None else result
+        archive_bytes = self._to_bytes_raw(reset_dirty=False)
+        _write_bytes_atomically(path, archive_bytes)
+        self._mark_save_clean()
+        return path
 
     def save_to_stream(self, stream: BinaryIO) -> BinaryIO:
         """Persist pending changes to *stream* and return the same stream."""
 
         self._run_pre_save_validation()
-        updates = self._root.serialize()
-        result = self._package.save(stream, updates)
-        self._root.reset_dirty()
-        return stream if result is None else result
+        archive_bytes = self._to_bytes_raw(reset_dirty=False)
+        _write_stream_or_rollback(stream, archive_bytes)
+        self._mark_save_clean()
+        return stream
 
     def to_bytes(self) -> bytes:
         """Serialize pending changes and return the HWPX archive as bytes."""
@@ -1523,20 +1633,44 @@ class HwpxDocument:
         self._run_pre_save_validation()
         return self._to_bytes_raw()
 
-    def _to_bytes_raw(self, *, reset_dirty: bool = True) -> bytes:
-        """Serialize without validation.
+    def _to_bytes_raw(
+        self,
+        *,
+        reset_dirty: bool = True,
+    ) -> bytes:
+        """Serialize and run editor-open safety validation.
 
         When ``reset_dirty`` is ``False``, the document remains marked as
         modified after the archive snapshot is generated.
         """
         updates = self._root.serialize()
-        result = self._package.save(None, updates)
-        if reset_dirty:
-            self._root.reset_dirty()
+        if updates:
+            for part_name, payload in updates.items():
+                self._package.set_part(part_name, payload)
+        result = self._package._save_to_bytes(
+            verify_open_safety=True,
+            mark_clean=False,
+        )
         if isinstance(result, bytes):
+            self._run_open_safety_validation(result)
+            if reset_dirty:
+                self._mark_save_clean()
             return result
         raise TypeError("package.save(None) must return bytes")
 
+    def _to_bytes_for_validation(self) -> bytes:
+        """Serialize current state for document validation without handing bytes to callers."""
+
+        updates = self._root.serialize()
+        return self._package._save_bytes_unchecked(
+            updates,
+            _unchecked_token=_UNCHECKED_SAVE_TOKEN,
+        )
+
+    def _mark_save_clean(self) -> None:
+        self._root.reset_dirty()
+        self._package.version_info.mark_clean()
+
     @overload
     def save(self, path_or_stream: None = None) -> bytes: ...