python-hwpx 6.7.0__py3-none-any.whl → 6.9.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/fields.py

@@ -663,7 +663,7 @@ def add_form_field(
     """Create a click-here (누름틀) form field and return it as a :class:`FormField`.
 
     The emitted XML follows the real-Hancom CLICKHERE contract
-    (reverse-engineered from Hancom Office 12.0.0.3288 gold documents). The
+    (inferred from Hancom Office 12.0.0.3288 gold documents). The
     prompt (안내문) is materialized as a screen-only red-italic run, exactly as
     Hancom authors it. The created field is immediately re-read through the
     standard ``list_form_fields`` matcher — creation fails loudly if the

hwpx/_document/layout.py

@@ -19,7 +19,9 @@ from ..oxml._document_primitives import NEW_NUM_KINDS
 from ..oxml.namespaces import HH, HP
 from ..oxml.numbering_kinds import ensure_numbering_levels
 from ..oxml.objects import HwpxOxmlInlineObject
-from ..oxml.section_format import _PAGE_LANDSCAPE, _PAGE_PORTRAIT, _page_orientation_value
+from ..oxml.section_format import (
+    _PAGE_LANDSCAPE, _PAGE_PORTRAIT, _checked, _page_orientation_value, column_shares, validate_column_gap,
+)
 from ..oxml.table_sizes import cell_margins_of
 from ._units import _mm_to_hwp_units, _pt_to_hwp_units
 
@@ -512,12 +514,12 @@ def set_list_format(
             suggestion="A continued list numbers on in the format of the list before it: "
             "leave out number_format and start, or continue_list to start a new list.",
         )
-    if level < 1:
+    if isinstance(level, bool) or not isinstance(level, int) or not 1 <= level <= 10:
         raise HwpxValueError(
-            "level must be 1 or greater",
+            f"level must be an int from 1 to 10; got {level!r}",
             code="style-list-level-invalid",
-            context={"requested": level},
-            suggestion="Levels start at 1.",
+            context={"requested": repr(level)},
+            suggestion="Hancom lists have ten levels, 1 to 10; it cannot save a document using a deeper one.",
         )
     if not doc._root.headers:
         raise HwpxValueError(
@@ -525,6 +527,13 @@ def set_list_format(
             code="document-header-missing",
             suggestion="Check that this is an intact HWPX package.",
         )
+    if start is not None and (isinstance(start, bool) or not isinstance(start, int) or not 0 <= start <= 0xFFFF):
+        raise HwpxValueError(  # Hancom keeps a list's start as 16 bits unsigned (0 drawn as 1)
+            f"start must be an int from 0 to 65535; got {start!r}",
+            code="style-list-start-value",
+            context={"requested": repr(start)},
+            suggestion="Pass the number the list starts at, from 0 to 65535.",
+        )
 
     level_specs: list[dict[str, str]] = [{} for _ in range(level)]
     if bullet_char:
@@ -532,7 +541,7 @@ def set_list_format(
     if number_format:
         level_specs[level - 1]["format"] = str(number_format).upper()
     if start is not None:
-        level_specs[level - 1]["start"] = str(max(1, int(start)))
+        level_specs[level - 1]["start"] = str(start)
 
     targets = _resolve_paragraph_targets(doc,
         paragraph_index=paragraph_index,
@@ -609,6 +618,8 @@ def set_page_setup(
     """
 
     normalized_orientation = _normalize_page_orientation(orientation)
+    if columns is not None:  # the gap checked before the page or its margins change
+        validate_column_gap(_mm_to_hwp_units(float(column_gap_mm or 0)))
     target_width_mm = width_mm
     target_height_mm = height_mm
     if paper_size:
@@ -633,6 +644,24 @@ def set_page_setup(
 
     width = _mm_to_hwp_units(float(target_width_mm)) if target_width_mm is not None else None
     height = _mm_to_hwp_units(float(target_height_mm)) if target_height_mm is not None else None
+    margin_source = dict(margins_mm or {})
+    margin_values = {
+        "left": margin_left_mm if margin_left_mm is not None else margin_source.get("left"),
+        "right": margin_right_mm if margin_right_mm is not None else margin_source.get("right"),
+        "top": margin_top_mm if margin_top_mm is not None else margin_source.get("top"),
+        "bottom": margin_bottom_mm if margin_bottom_mm is not None else margin_source.get("bottom"),
+        "header": header_margin_mm if header_margin_mm is not None else margin_source.get("header"),
+        "footer": footer_margin_mm if footer_margin_mm is not None else margin_source.get("footer"),
+        "gutter": gutter_mm if gutter_mm is not None else margin_source.get("gutter"),
+    }
+    hwp_margins = {
+        name: _mm_to_hwp_units(float(value))
+        for name, value in margin_values.items()
+        if value is not None
+    }
+    for name, value in (("width", width), ("height", height), *hwp_margins.items()):
+        if value is not None:  # checked before the page or its margins change
+            _checked(name, value, 2**31 - 1, "page-size-value")
     if width is not None or height is not None or normalized_orientation is not None:
         # Call the local primitives directly rather than `doc.set_page_size`/
         # `doc.set_page_margins`/`doc.set_columns` below — all three names
@@ -649,21 +678,6 @@ def set_page_setup(
             section_index=section_index,
         )
 
-    margin_source = dict(margins_mm or {})
-    margin_values = {
-        "left": margin_left_mm if margin_left_mm is not None else margin_source.get("left"),
-        "right": margin_right_mm if margin_right_mm is not None else margin_source.get("right"),
-        "top": margin_top_mm if margin_top_mm is not None else margin_source.get("top"),
-        "bottom": margin_bottom_mm if margin_bottom_mm is not None else margin_source.get("bottom"),
-        "header": header_margin_mm if header_margin_mm is not None else margin_source.get("header"),
-        "footer": footer_margin_mm if footer_margin_mm is not None else margin_source.get("footer"),
-        "gutter": gutter_mm if gutter_mm is not None else margin_source.get("gutter"),
-    }
-    hwp_margins = {
-        name: _mm_to_hwp_units(float(value))
-        for name, value in margin_values.items()
-        if value is not None
-    }
     if hwp_margins:
         set_page_margins(
             doc,
@@ -723,15 +737,18 @@ def set_columns(
 ) -> HwpxOxmlInlineObject:
     """Set the columns of a section, or start new columns at a paragraph.
 
-    Without ``paragraph`` this rewrites the section's own column layout (the
-    ``hp:colPr`` next to ``hp:secPr``) in place, so the whole section is laid
-    out in ``col_count`` columns. With ``paragraph`` it adds a column
-    definition control there, and the text from that paragraph on uses it.
+    Without ``paragraph``, or with a section's first one, this rewrites the
+    section's own column layout (the ``hp:colPr`` next to ``hp:secPr``) in
+    place, so the whole section is laid out in ``col_count`` columns. With a
+    later ``paragraph`` it adds a column definition there, used from it on.
 
     Args:
         col_count: Number of columns (1–255).
         col_type: ``NEWSPAPER``, ``BALANCED_NEWSPAPER``, or ``PARALLEL``.
         same_gap: Gap in HWPUNIT (7200 = 1 inch).
+        column_widths: With ``same_size=False``, a ``(width, gap)`` pair per
+            column, in HWPUNIT adding up to the text width or in plain
+            proportions; Hancom keeps them as shares of 32768 of the text width.
         separator_type: Optional column separator line type (e.g. ``SOLID``).
     """
     if not 1 <= col_count <= 255:
@@ -741,6 +758,10 @@ def set_columns(
             context={"requested": col_count},
             suggestion="Use columns=1 to remove columns.",
         )
+    if same_size:
+        validate_column_gap(same_gap)  # before a paragraph is added
+    elif column_widths:
+        column_shares(column_widths)  # checked before a paragraph is added too
     if paragraph is None:
         target_section = _resolve_section(doc, section=section, section_index=section_index)
         ctrl = target_section.properties.set_columns(

hwpx/_document/media.py

@@ -19,6 +19,11 @@ from ..opc.relationships import (
 )
 from ..oxml import HwpxOxmlInlineObject, HwpxOxmlParagraph
 from ..oxml.namespaces import HC, HP
+from ..oxml.color import normalize_color
+from ..oxml.shape_position import PictureGlow, PictureReflection, PictureShadow, validate_picture_effects
+from ..oxml.shape_position import (
+    validate_picture_align, validate_picture_border, validate_picture_crop, validate_picture_image, validate_shape_size,
+)
 from ._units import _mm_to_hwp_units
 
 if TYPE_CHECKING:
@@ -106,23 +111,35 @@ def add_picture(
     width_mm: float | None = None,
     height_mm: float | None = None,
     align: str | None = None,
+    brightness: int = 0,
+    contrast: int = 0,
+    effect: str = "REAL_PIC",
+    alpha: int = 0,
+    line_color: str | None = None,
+    line_width: int = 33,
+    crop: tuple[int, int, int, int] | None = None,
+    shadow: PictureShadow | None = None,
+    glow: PictureGlow | None = None,
+    soft_edge: int | None = None,
+    reflection: PictureReflection | None = None,
     para_pr_id_ref: str | int | None = None,
     style_id_ref: str | int | None = None,
     char_pr_id_ref: str | int | None = None,
     run_attributes: dict[str, str] | None = None,
     **extra_attrs: str,
 ) -> HwpxOxmlInlineObject:
-    """Embed image data and place a picture object in a new paragraph."""
-
-    # Call the local primitive directly rather than `doc.add_image` — that
-    # facade name moved in 6.0 (design table row 33), and going through it
-    # would fire a DeprecationWarning on every `add_picture` call even though
-    # `add_picture` itself is a kept (unmoved) root method.
-    binary_item_id_ref = str(add_image(doc, image_data, image_format))
-
+    """Embed image data and place a picture object in a new paragraph, the image adjusted and bordered as
+    :meth:`HwpxOxmlParagraph.add_picture` takes it."""
+
+    validate_picture_align(align)  # before anything is stored: Hancom reads an unknown one as LEFT
+    validate_picture_image(brightness, contrast, effect, alpha)  # ... and draws no other adjustment
+    validate_picture_border(line_width)
+    if line_color is not None:
+        normalize_color(line_color)
     resolved_width = width
     if resolved_width is None:
         resolved_width = _mm_to_hwp_units(width_mm) if width_mm is not None else 14400
+    validate_shape_size(resolved_width, 0)  # validate before aspect-ratio arithmetic too
 
     resolved_height = height
     if resolved_height is None:
@@ -135,6 +152,15 @@ def add_picture(
                 resolved_height = round(resolved_width * source_height / source_width)
             else:
                 resolved_height = resolved_width
+    validate_shape_size(resolved_width, resolved_height)  # before anything is stored too
+    validate_picture_crop(crop, resolved_width, resolved_height)
+    validate_picture_effects(shadow, glow, soft_edge, reflection)
+
+    # Call the local primitive directly rather than `doc.add_image` — that
+    # facade name moved in 6.0 (design table row 33), and going through it
+    # would fire a DeprecationWarning on every `add_picture` call even though
+    # `add_picture` itself is a kept (unmoved) root method.
+    binary_item_id_ref = str(add_image(doc, image_data, image_format))
 
     paragraph = doc.add_paragraph(
         "",
@@ -158,6 +184,17 @@ def add_picture(
         width=resolved_width,
         height=resolved_height,
         align=align,
+        brightness=brightness,
+        contrast=contrast,
+        effect=effect,
+        alpha=alpha,
+        line_color=line_color,
+        line_width=line_width,
+        crop=crop,
+        shadow=shadow,
+        glow=glow,
+        soft_edge=soft_edge,
+        reflection=reflection,
         run_attributes=run_attributes,
         char_pr_id_ref=char_pr_id_ref,
     )

hwpx/_document/memos.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, Any
 
 from ..errors import HwpxValueError
 
-from ..oxml._document_primitives import _object_id
+from ..oxml._document_primitives import _clear_paragraph_layout_cache, _object_id
 from ..oxml.namespaces import HP
 
 if TYPE_CHECKING:
@@ -189,6 +189,7 @@ def attach_memo_field(
             "dirty": "0",
             "zorder": order,
             "fieldid": MEMO_FIELD_ID,
+            "metaTag": "",
         },
     )
 
@@ -247,6 +248,7 @@ def attach_memo_field(
 
     paragraph.element.insert(0, run_begin)
     paragraph.element.append(run_end)
+    _clear_paragraph_layout_cache(paragraph.element)  # the field's controls move its text: laid out again
     paragraph.section.mark_dirty()
 
     return memo

hwpx/_document/ns/shapes.py

@@ -345,8 +345,8 @@ class ShapesNamespace(_Namespace):
         section: "int | Section | None" = None,
         section_index: int | None = None,
     ) -> "Shape":
-        """도형을 그룹으로 묶는다(`ContainerMember.rect`/`.ellipse`/`.polygon`으로
-        각 부재를 그룹 로컬 좌표로 만들어 넘긴다)."""
+        """도형을 그룹으로 묶는다(`ContainerMember.rect`/`.ellipse`/`.polygon`/`.line`/
+        `.text_box`/`.picture`/`.group`으로 각 부재를 그룹 로컬 좌표로 만들어 넘긴다)."""
 
         from .. import shapes as _shapes
 

hwpx/_document/ns/tables.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""`doc.tables` — 표 탐색·매핑·병합·경로 채움.
+"""`doc.tables` — 표 탐색·매핑·병합·구조 편집·경로 채움.
 
 표를 **만드는** 것은 루트에 남았다(`doc.add_table` — python-docx 대응이자
 automation 최다 사용 저작 동사 중 하나). 만든 다음에 하는 일들이 여기 모인다.
@@ -11,7 +11,7 @@ automation 최다 사용 저작 동사 중 하나). 만든 다음에 하는 일
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Mapping
+from typing import TYPE_CHECKING, Iterable, Mapping, overload
 
 from ._base import _Namespace
 
@@ -28,7 +28,7 @@ __all__ = ["TablesNamespace"]
 
 
 class TablesNamespace(_Namespace):
-    """표 탐색·매핑·병합·경로 채움."""
+    """표 탐색·매핑·병합·구조 편집·경로 채움."""
 
     __slots__ = ()
     _path = "doc.tables"
@@ -48,6 +48,20 @@ class TablesNamespace(_Namespace):
     def __iter__(self):
         return iter(self.all)
 
+    @overload
+    def __getitem__(self, index: int) -> "Table": ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list["Table"]: ...
+
+    def __getitem__(self, index: int | slice) -> "Table | list[Table]":
+        """문서 순서의 ``index`` 번째 표(``doc.tables[0]``, ``doc.tables[-1]``, ``doc.tables[1:3]``).
+
+        ``doc.tables.all[index]``와 같다. 범위 밖이면 ``IndexError``.
+        """
+
+        return self.all[index]
+
     def map(self) -> "TableMapResult":
         """모든 표의 위치·모양·헤더 미리보기를 담은 간결 지도."""
 
@@ -78,3 +92,35 @@ class TablesNamespace(_Namespace):
         """
 
         return table.merge_cells(cell_range)
+
+    def insert_rows(
+        self, table: "Table", ref_row: int, count: int = 1, *, side: str = "below", blank: bool = False
+    ) -> None:
+        """``ref_row`` 행을 복제해 그 아래(``side="above"``면 위)에 ``count`` 행을 넣는다.
+
+        새 칸은 같은 열 기준 칸의 서식과 글을 받고, ``blank=True``면 한/글처럼 빈 문단 하나만 둔다.
+        """
+
+        table.insert_rows(ref_row, count, side=side, blank=blank)
+
+    def insert_columns(
+        self, table: "Table", ref_col: int, count: int = 1, *, side: str = "right", blank: bool = False
+    ) -> None:
+        """``ref_col`` 열을 복제해 그 오른쪽(``side="left"``면 왼쪽)에 ``count`` 열을 넣는다(표가 넓어진다)."""
+
+        table.insert_columns(ref_col, count, side=side, blank=blank)
+
+    def delete_rows(self, table: "Table", rows: int | Iterable[int]) -> None:
+        """행을 지운다. 모든 행은 지울 수 없다(표 삭제를 쓴다)."""
+
+        table.delete_rows(rows)
+
+    def delete_columns(self, table: "Table", cols: int | Iterable[int]) -> None:
+        """열을 지우고 그 폭을 남은 열에 나눈다. 모든 열은 지울 수 없다."""
+
+        table.delete_columns(cols)
+
+    def split_cell(self, table: "Table", row: int, col: int, *, rows: int = 1, cols: int = 1) -> None:
+        """(``row``, ``col``) 칸을 ``rows`` 줄 × ``cols`` 칸으로 나눈다(한/글의 셀 나누기)."""
+
+        table.split_cell(row, col, rows=rows, cols=cols)

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/shapes.py

@@ -8,7 +8,9 @@ from typing import TYPE_CHECKING, Any, Sequence, cast
 from ._units import _mm_to_hwp_units
 from ..errors import HwpxStateError, HwpxValueError
 from ..oxml.objects import _closed_points
-from ..oxml.shape_position import validate_original_size
+from ..oxml.shape_position import (
+    validate_equation_base_unit, validate_original_size, validate_rect_ratio, validate_shape_size,
+)
 
 if TYPE_CHECKING:
     from hwpx.document import HwpxDocument
@@ -265,6 +267,8 @@ def add_rectangle(
     Dimensions are in HWPUNIT.  *ratio* controls corner roundness
     (0 = sharp, 50 = semicircle).
     """
+    validate_shape_size(width, height)
+    validate_rect_ratio(ratio)
     validate_original_size(original_size)
     if paragraph is None:
         paragraph = doc.add_paragraph(
@@ -297,6 +301,7 @@ def add_ellipse(
 
     Dimensions are in HWPUNIT.
     """
+    validate_shape_size(width, height)
     validate_original_size(original_size)
     if paragraph is None:
         paragraph = doc.add_paragraph(
@@ -334,6 +339,7 @@ def add_arc(
     mechanism every other shape here already uses. *arc_type* is the
     schema's own ``NORMAL``/``PIE``/``CHORD`` passthrough.
     """
+    validate_shape_size(width, height)
     if paragraph is None:
         paragraph = doc.add_paragraph(
             "", section=section, section_index=section_index,
@@ -461,7 +467,8 @@ def add_container(
     """Insert a group (``<hp:container>``) wrapping *members*.
 
     Each member is built with :class:`hwpx.oxml.ContainerMember`'s
-    ``rect``/``ellipse``/``polygon`` classmethods, which take the member's
+    ``rect``/``ellipse``/``polygon``/``line``/``text_box``/``picture``/``group``
+    classmethods, which take the member's
     position in the group's own local coordinate space (HWPUNIT, top-left
     anchored) alongside its usual shape parameters::
 
@@ -522,15 +529,16 @@ def add_equation(
             context={"length": len(text), "limit": MAX_SOURCE_LENGTH},
             suggestion="Split the equation.",
         )
+    validate_equation_base_unit(base_unit)
+    width, height = size if size is not None else estimate_equation_size(text, base_unit=base_unit)
+    validate_shape_size(width, height)  # one measured at a huge base_unit too
     if paragraph is None:
         paragraph = doc.add_paragraph(
             "", section=section, section_index=section_index,
             include_run=False,
         )
-    if size is None:
-        size = estimate_equation_size(text, base_unit=base_unit)
     inline_object = paragraph.add_equation(
-        text, base_unit=base_unit, size=size, char_pr_id_ref=char_pr_id_ref,
+        text, base_unit=base_unit, size=(width, height), char_pr_id_ref=char_pr_id_ref,
     )
 
     created_id = inline_object.element.get("id", "")
@@ -756,10 +764,10 @@ def add_drop_cap(
     char_pr_id_ref: str | int | None = None,
     para_pr_id_ref: str | int | None = None,
 ) -> HwpxOxmlInlineObject:
-    """Insert a drop cap (문단 첫 글자 장식), reverse-engineered from the one
+    """Insert a drop cap (문단 첫 글자 장식), inferred from the one
     real-corpus example that carries a non-default ``dropcapstyle``
     (``error__20230809__test.hwpx`` -- see ``oxml.drop_cap``'s own
-    docstring for the full structural reverse engineering and why it
+    docstring for the full structural format inference and why it
     supports ``style="TripleLine"`` and ``"DoubleLine"`` only).
 
     Element construction (element-building validation included) happens in