python-hwpx 2.10.1__py3-none-any.whl → 2.10.3__py3-none-any.whl

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",
 ]

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

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),

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: ...