python-hwpx 6.7.0__py3-none-any.whl → 6.8.0__py3-none-any.whl

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). 계약 유동.
@@ -293,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__":
@@ -318,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)
@@ -346,11 +357,76 @@ def __dir__() -> list[str]:
     return sorted(
         set(globals())
         | set(__all__)
+        | {"tools"}
         | set(_EXPERIMENTAL_EXPORTS)
         | set(_DEPRECATED_EXPORTS)
     )
 
 
+# --- 지연 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
@@ -359,35 +435,9 @@ _moved_modules.install(_MOVED_TO_COMPANION)
 
 
 # --- 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,
-)
+# ``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,

hwpx/_document/persistence.py

@@ -408,7 +408,8 @@ def save_report(
     oracle-verified ``visual_complete`` tier (plan §0.0).
 
     Like the legacy savers it raises only if the serialize step's open-safety
-    check fails; all other gate outcomes are returned in the report.
+    check fails; all other gate outcomes are returned in the report. An ``.hwp``
+    path is written as HWP 5.0, as :func:`save_to_path` writes it.
     """
 
     _run_pre_save_validation(doc)
@@ -420,10 +421,15 @@ def save_report(
         output_path = path_or_stream
     elif path_or_stream is not None:
         output_stream = path_or_stream
+    # An .hwp target gets HWP 5.0 made from the HWPX parts the gate checks; it raises before anything is
+    # written when the HWP 5.0 writer cannot express the document.
+    hwp5 = None
+    if output_path is not None and str(output_path).lower().endswith(".hwp"):
+        hwp5 = _hwp5_bytes(archive_bytes)
 
     report = doc._save_pipeline.run(
         archive_bytes,
-        output_path=output_path,
+        output_path=None if hwp5 is not None else output_path,
         output_stream=output_stream,
         quality=quality or QualityPolicy.transparent(),
         before=before,
@@ -432,6 +438,12 @@ def save_report(
         reference_document=doc,
         source_label="document.save_report",
     )
+    if hwp5 is not None and report.ok:  # the gate passed: publish the HWP 5.0 file in its place
+        from ..quality.save_pipeline import write_bytes_atomically
+
+        assert output_path is not None
+        write_bytes_atomically(output_path, hwp5)
+        report.output_path = str(output_path)
     if report.ok:
         _mark_save_clean(doc)
     return report

hwpx/document.py

@@ -37,7 +37,6 @@ from ._document import fields as _fields
 from ._document import media as _media
 from ._document import persistence as _persistence
 from ._document.persistence import SaveFormat
-from .hwp5.errors import Hwp5ConversionReport
 from ._document import _resolve
 from ._document import headings as _headings
 from ._document import layout as _layout
@@ -64,6 +63,7 @@ register_owpml_namespaces(ET.register_namespace)
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
+    from .hwp5.errors import Hwp5ConversionReport
     from .tools.validator import ValidationReport
 
 
@@ -836,7 +836,9 @@ class HwpxDocument(_LegacyFacade):
         oracle-verified ``visual_complete`` tier (plan §0.0).
 
         Like the legacy savers it raises only if the serialize step's open-safety
-        check fails; all other gate outcomes are returned in the report.
+        check fails; all other gate outcomes are returned in the report. An ``.hwp``
+        path is written as HWP 5.0, as :meth:`save_to_path` writes it, and raises
+        :class:`~hwpx.Hwp5Error` before writing when the document cannot be.
         """
 
         return _persistence.save_report(

hwpx/equation/authoring.py

@@ -270,6 +270,8 @@ class _LatexParser:
                 radicand = self._group_or_atom(depth)
                 return f"root {{{' '.join(index_parts)}}} of {{{radicand}}}"
             return f"sqrt {{{self._group_or_atom(depth)}}}"
+        if token in ("\\lbrace", "\\rbrace"):  # the command spellings of \{ and \}
+            return "LBRACE" if token == "\\lbrace" else "RBRACE"
         if token in _TEXT_COMMANDS:
             return self._text_literal()
         if token == "\\mathbf":
@@ -407,8 +409,8 @@ class _LatexParser:
             raise UnsupportedLatexError("missing \\left/\\right delimiter")
         if token in _LATEX_DELIMITERS:
             return _LATEX_DELIMITERS[token]
-        if token in ("\\{", "\\}"):
-            return "LBRACE" if token == "\\{" else "RBRACE"
+        if token in ("\\{", "\\}", "\\lbrace", "\\rbrace"):
+            return "LBRACE" if token in ("\\{", "\\lbrace") else "RBRACE"
         if token in DELIMITERS and len(token) == 1:
             return token
         raise UnsupportedLatexError(f"unsupported \\left/\\right delimiter: {token}")
@@ -450,7 +452,8 @@ def estimate_equation_size(script: str, *, base_unit: int = 1100) -> tuple[int,
 
     A reader that lays the page out from the file uses the stored box, so the
     box has to fit the script; Hancom itself was observed (on macOS) to lay the
-    equation out again and rewrite the box when it saves the document (see
+    equation out again and rewrite the box when it saves the document, while on
+    Windows it keeps the stored box and lays the page out with it (see
     :func:`hwpx.equation.measure.measure_equation`).
     """
 

hwpx/equation/eqedit.py

@@ -42,8 +42,10 @@ from .tokens import (
 MAX_SOURCE_LENGTH = 10_000
 MAX_GROUP_DEPTH = 64
 
-# Words EqEdit reads as symbols or structure. The writer quotes a bare identifier that collides with one
-# (``T_{int}`` → ``T _{"int"}``); the reader turns such a quoted word back into plain letters.
+# Words EqEdit reads as symbols, structure or font switches. The writer quotes a bare identifier that collides
+# with one (``T_{int}`` → ``T _{"int"}``, ``e^{it}`` → ``e ^{"it"}``: a lone ``it`` in a superscript switches to
+# italic and draws nothing); the reader turns such a quoted word back into plain letters.
+_FONT_SWITCHES = frozenset({"rm", "it", "bold", "RM", "IT", "BOLD"})
 _RESERVED_WORDS = (
     frozenset(GREEK)
     | frozenset(OPERATORS)
@@ -52,6 +54,7 @@ _RESERVED_WORDS = (
     | frozenset(ACCENTS)
     | frozenset(MATRIX_ENVIRONMENTS)
     | STRUCTURAL
+    | _FONT_SWITCHES
 )
 
 # Characters that always terminate a token even when not whitespace separated.
@@ -338,6 +341,8 @@ class _Parser:
             return OPERATORS[token]
         if token in FUNCTIONS:
             return FUNCTIONS[token]
+        if token in ("LBRACE", "RBRACE"):  # a literal brace outside LEFT/RIGHT
+            return r"\{" if token == "LBRACE" else r"\}"
         if token.startswith('"') and token.endswith('"') and len(token) >= 2:
             literal = token[1:-1]
             if literal.isalpha() and literal in _RESERVED_WORDS: