python-hwpx 6.0.3__tar.gz → 6.2.1__tar.gz

{python_hwpx-6.0.3/src/python_hwpx.egg-info → python_hwpx-6.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 6.0.3
+Version: 6.2.1
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0

{python_hwpx-6.0.3 → python_hwpx-6.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "6.0.3"
+version = "6.2.1"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -153,6 +153,15 @@ files = [
     "src/hwpx/errors.py",
     "src/hwpx/mutation_report.py",
     "src/hwpx/capabilities.py",
+    # 6.14 트레인㊾-1 — pre-existing 49 errors 정리 후 편입(6.12 이전부터의
+    # 기존 부채, f7e4e67 리뷰가 지목). 대부분 _si()가 돌려주는 int|None을
+    # 산술/비교에 바로 쓰던 자리(스키마상 필수 hp:tc 속성이라 실제로는
+    # None일 수 없음 -- assert로 좁힘) + 한 함수 안에서 변수 이름을
+    # re.Match와 int 양쪽으로 재사용하던 자리(이름만 갈라 해소, 동작
+    # 불변) + 람다 기본인자가 오버로드 추론을 깨던 자리(named 중첩
+    # 함수로 치환). 동작 변경 없음(assert 실패는 이전에도 TypeError로
+    # 이미 죽던 자리를 더 명확한 메시지로 바꾼 것뿐).
+    "src/hwpx/table_patch.py",
     "src/hwpx/plan/__init__.py",
     "src/hwpx/plan/_model.py",
     "src/hwpx/plan/_validate.py",
@@ -187,8 +196,10 @@ files = [
     "src/hwpx/objects/form_field.py",
     "src/hwpx/objects/results.py",
     "src/hwpx/objects/tracked.py",
+    "src/hwpx/objects/highlight.py",
     "src/hwpx/_document/_resolve.py",
     "src/hwpx/_document/headings.py",
+    "src/hwpx/_document/highlight.py",
     "src/hwpx/_document/ns",
     "src/hwpx/_document/fields.py",
     "src/hwpx/_document/layout.py",
@@ -225,7 +236,79 @@ files = [
     "src/hwpx/tools/text_extractor.py",
     "tests/template_automation/helpers.py",
     "tests/template_automation/generate_fixtures.py",
+    # 6.4: part-hierarchy read models (gap #15) — born in the gate, per the
+    # WP-A rule above.
+    "src/hwpx/oxml/version_part.py",
+    "src/hwpx/oxml/master_page.py",
+    "src/hwpx/oxml/history_part.py",
+    # 6.6 (train 23): document options/compatibility authoring — born in the
+    # gate, per the WP-A rule above.
+    "src/hwpx/oxml/header_compat.py",
+    # 6.9 (train 33): document insertion/merge — born in the gate, per the
+    # WP-A rule above.
+    "src/hwpx/tools/document_merge.py",
+    # 6.9 (train 34): dutmal/compose authoring — born in the gate, per the
+    # WP-A rule above.
+    "src/hwpx/oxml/dutmal_compose.py",
+    # 6.11 (train 44): add_section() layout-carrier lookup, extracted from
+    # document_parts.py (1600-line cap) — born in the gate, per the WP-A
+    # rule above.
+    "src/hwpx/oxml/section_layout.py",
+    # 6.12 (train 48): opf:metadata (content.hpf document properties) read
+    # model — born in the gate, per the WP-A rule above.
+    "src/hwpx/oxml/document_metadata.py",
+    # 6.12 (train 48): drop cap (hp:rect dropcapstyle) shape-authoring
+    # overflow module, extracted from paragraph.py (1600-line cap) — born
+    # in the gate, per the WP-A rule above.
+    "src/hwpx/oxml/drop_cap.py",
+    # 6.13 (train 48): ensure_numbering's full body (bullet/number/outline
+    # kinds), moved out of header_part.py (1600-line cap, no headroom left
+    # once the new "outline" kind was added) — born in the gate, per the
+    # WP-A rule above.
+    "src/hwpx/oxml/numbering_kinds.py",
+    # 6.13 (train 48): master page (바탕쪽) part creation + manifest
+    # registration — new module from the start (document_parts.py had
+    # modest headroom but this needed more than fit safely), per the WP-A
+    # rule above.
+    "src/hwpx/oxml/master_page_authoring.py",
+    # 6.13 (train 48): date field (hp:fieldBegin type=DATE) + proofreading
+    # mark field (type=PROOFREADING_MARKS_SIGN) authoring — new module
+    # from the start; paragraph.py hit exactly 1600 lines with just the
+    # two delegator methods (zero headroom left, resolved by the
+    # extraction below), per the WP-A rule above.
+    "src/hwpx/oxml/field_marks.py",
+    # 6.14 (train 48/debt3): footnote/endnote (각주/미주) authoring moved
+    # out of paragraph.py verbatim (no behavior change) to restore real
+    # headroom -- same escape valve as dutmal_compose.py/objects.py/
+    # field_marks.py above, per the WP-A rule.
+    "src/hwpx/oxml/note_authoring.py",
 ]
+# 칩 후보 1 ✅ 6.14 트레인㊾-1에서 해소: `src/hwpx/table_patch.py`(2073줄,
+# 6.12 트레인㊸ 갭⑤ 정리 시 team-lead가 지목, f7e4e67 리뷰) — 위 files
+# 리스트에 이미 편입돼 있다(pre-existing 49 errors 정리, 이 섹션 첫
+# 항목 주석 참조). 이 블록 자체는 이력으로 남긴다.
+#
+# 다음 사이클 칩 후보 2(6.13 트레인㊼, titleMark 재프로브 부산물로
+# team-lead가 지목): `HwpxDocument.add_heading`(document.py) →
+# `_headings.bind_outline_level` → `_document/layout.py`의
+# `set_paragraph_format(outline_level=)`이 호출될 때마다 **동일한
+# paraPr이 이미 있어도 새 id로 다시 만든다**(기존 요소 재사용/dedup
+# 조회 없음) — 실한컴은 저장 시점에 중복 paraPr을 자기가 병합한다
+# (titleMark 재프로브에서 paraPrIDRef가 21→20으로 "되돌아간" 현상의
+# 원인, 버그 아님·관측된 실동작으로 문서화됨). 우리 쪽에서 paraPr
+# 재사용 lookup을 추가하면 왕복 시 이 되돌아감이 사라지고 저장 파일도
+# 더 작아진다 — fix 안 함, 스코프 밖.
+#
+# 다음 사이클 칩 후보 3(6.13 트레인㊼): `src/hwpx/oxml/paragraph.py`가
+# `add_date_field`/`add_proofreading_mark` 두 delegator를 추가하며
+# 정확히 1600줄(WP-A owner-file 캡)을 채웠다 — 헤드룸 0. 다음에 이
+# 파일에 뭔가 더 추가해야 하면(신규 필드류 저작 등) 곧바로 게이트가
+# 막는다 — 실제 추출/재구조화 패스가 필요하다(어디를 오버플로 모듈로
+# 뺄지는 이번 트레인에서 정하지 않음, 다음 트레인의 몫).
+#
+# 위 세 칩(table_patch 게이트 미편입·add_heading paraPr 비-dedup·
+# paragraph.py 헤드룸 0)은 다음 사이클 초입 부채상환 트레인 후보로
+# 함께 묶어 처리할 것 — team-lead 지시(6.13 트레인㊼ 정리 커밋).
 ignore_missing_imports = true
 
 [tool.pyright]
@@ -236,6 +319,15 @@ include = [
     "src/hwpx/errors.py",
     "src/hwpx/mutation_report.py",
     "src/hwpx/capabilities.py",
+    # 6.14 트레인㊾-1 — pre-existing 49 errors 정리 후 편입(6.12 이전부터의
+    # 기존 부채, f7e4e67 리뷰가 지목). 대부분 _si()가 돌려주는 int|None을
+    # 산술/비교에 바로 쓰던 자리(스키마상 필수 hp:tc 속성이라 실제로는
+    # None일 수 없음 -- assert로 좁힘) + 한 함수 안에서 변수 이름을
+    # re.Match와 int 양쪽으로 재사용하던 자리(이름만 갈라 해소, 동작
+    # 불변) + 람다 기본인자가 오버로드 추론을 깨던 자리(named 중첩
+    # 함수로 치환). 동작 변경 없음(assert 실패는 이전에도 TypeError로
+    # 이미 죽던 자리를 더 명확한 메시지로 바꾼 것뿐).
+    "src/hwpx/table_patch.py",
     "src/hwpx/plan/__init__.py",
     "src/hwpx/plan/_model.py",
     "src/hwpx/plan/_validate.py",
@@ -270,8 +362,10 @@ include = [
     "src/hwpx/objects/form_field.py",
     "src/hwpx/objects/results.py",
     "src/hwpx/objects/tracked.py",
+    "src/hwpx/objects/highlight.py",
     "src/hwpx/_document/_resolve.py",
     "src/hwpx/_document/headings.py",
+    "src/hwpx/_document/highlight.py",
     "src/hwpx/_document/ns",
     "src/hwpx/_document/fields.py",
     "src/hwpx/_document/layout.py",
@@ -308,6 +402,52 @@ include = [
     "src/hwpx/tools/text_extractor.py",
     "tests/template_automation/helpers.py",
     "tests/template_automation/generate_fixtures.py",
+    # 6.4: part-hierarchy read models (gap #15) — born in the gate, per the
+    # WP-A rule above.
+    "src/hwpx/oxml/version_part.py",
+    "src/hwpx/oxml/master_page.py",
+    "src/hwpx/oxml/history_part.py",
+    # 6.6 (train 23): document options/compatibility authoring — born in the
+    # gate, per the WP-A rule above.
+    "src/hwpx/oxml/header_compat.py",
+    # 6.9 (train 33): document insertion/merge — born in the gate, per the
+    # WP-A rule above.
+    "src/hwpx/tools/document_merge.py",
+    # 6.9 (train 34): dutmal/compose authoring — born in the gate, per the
+    # WP-A rule above.
+    "src/hwpx/oxml/dutmal_compose.py",
+    # 6.11 (train 44): add_section() layout-carrier lookup, extracted from
+    # document_parts.py (1600-line cap) — born in the gate, per the WP-A
+    # rule above.
+    "src/hwpx/oxml/section_layout.py",
+    # 6.12 (train 48): opf:metadata (content.hpf document properties) read
+    # model — born in the gate, per the WP-A rule above.
+    "src/hwpx/oxml/document_metadata.py",
+    # 6.12 (train 48): drop cap (hp:rect dropcapstyle) shape-authoring
+    # overflow module, extracted from paragraph.py (1600-line cap) — born
+    # in the gate, per the WP-A rule above.
+    "src/hwpx/oxml/drop_cap.py",
+    # 6.13 (train 48): ensure_numbering's full body (bullet/number/outline
+    # kinds), moved out of header_part.py (1600-line cap, no headroom left
+    # once the new "outline" kind was added) — born in the gate, per the
+    # WP-A rule above.
+    "src/hwpx/oxml/numbering_kinds.py",
+    # 6.13 (train 48): master page (바탕쪽) part creation + manifest
+    # registration — new module from the start (document_parts.py had
+    # modest headroom but this needed more than fit safely), per the WP-A
+    # rule above.
+    "src/hwpx/oxml/master_page_authoring.py",
+    # 6.13 (train 48): date field (hp:fieldBegin type=DATE) + proofreading
+    # mark field (type=PROOFREADING_MARKS_SIGN) authoring — new module
+    # from the start; paragraph.py hit exactly 1600 lines with just the
+    # two delegator methods (zero headroom left, resolved by the
+    # extraction below), per the WP-A rule above.
+    "src/hwpx/oxml/field_marks.py",
+    # 6.14 (train 48/debt3): footnote/endnote (각주/미주) authoring moved
+    # out of paragraph.py verbatim (no behavior change) to restore real
+    # headroom -- same escape valve as dutmal_compose.py/objects.py/
+    # field_marks.py above, per the WP-A rule.
+    "src/hwpx/oxml/note_authoring.py",
 ]
 pythonVersion = "3.10"
 typeCheckingMode = "basic"

{python_hwpx-6.0.3 → python_hwpx-6.2.1}/src/hwpx/_document/_legacy.py

@@ -69,6 +69,7 @@ from . import tracked as _tracked
 
 if TYPE_CHECKING:
     from ..form_fit.policy import FitPolicy
+    from ..objects.binary_item import BinaryItem
     from ..oxml import (
         HwpxOxmlDocument,
         HwpxOxmlHeader,
@@ -862,6 +863,8 @@ class _LegacyFacade:
         border_color: str = "#BFBFBF",
         border_width: str = "0.12 mm",
         fill_color: str | None = None,
+        fill_image: "str | BinaryItem | Mapping[str, object] | None" = None,
+        fill_gradient: Mapping[str, object] | None = None,
         active_borders: Sequence[str] | None = None,
         border_type: str = "SOLID",
     ) -> str:
@@ -869,13 +872,25 @@ class _LegacyFacade:
 
         ``border_type`` selects the OWPML line style (``SOLID``, ``DASH``,
         ``DOT``, ``DOUBLE_SLIM``, ``WAVE``, …); values outside the OWPML
-        vocabulary are rejected.
+        vocabulary are rejected. ``fill_color``/``fill_image``/``fill_gradient``
+        are mutually exclusive (OWPML ``hc:fillBrush`` choice).
         """
 
+        from .ns.styles import _resolve_fill_gradient, _resolve_fill_image
+
+        given = sum(1 for v in (fill_color, fill_image, fill_gradient) if v is not None)
+        if given > 1:
+            raise HwpxValueError(
+                "fill_color/fill_image/fill_gradient are mutually exclusive",
+                code="style-border-fill-conflict",
+                suggestion="Pass exactly one of fill_color, fill_image, fill_gradient.",
+            )
         return self._root.ensure_border_fill(
             border_color=border_color,
             border_width=border_width,
             fill_color=fill_color,
+            fill_image=_resolve_fill_image(fill_image),
+            fill_gradient=_resolve_fill_gradient(fill_gradient),
             active_borders=active_borders,
             border_type=border_type,
         )

python_hwpx-6.2.1/src/hwpx/_document/highlight.py

@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Highlight (``hp:markpenBegin``/``markpenEnd``) authoring and reading owner
+behind the :class:`HwpxDocument` facade.
+
+Real-corpus reversal (``hwpxlib_corpus/error__20251107__test*.hwpx``, the only
+fixtures carrying this pair) plus the OWPML schema (``ParaList XML
+schema.xml``) agree on the shape: both marks live inside a single ``hp:t``,
+``markpenBegin`` carries an optional ``color``, ``markpenEnd`` carries no
+attributes at all — pairing is positional (innermost open begin closes first),
+not by id. :mod:`hwpx.tools.text_extractor` already reads this shape with a
+per-``hp:t`` stack; :func:`list_highlights` exposes the same reading as a
+public model instead of inline text markers.
+
+Authoring is scoped to one run's text the same way ``doc.tracking.delete``
+scopes tracked deletes: a match that only exists once inline markup pieces
+are concatenated crosses a boundary this module refuses to split.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from ..errors import HwpxValueError
+from ..objects.highlight import Highlight
+
+if TYPE_CHECKING:
+    from hwpx.document import HwpxDocument
+    from ..oxml import HwpxOxmlParagraph
+    from ..oxml.body import TextSpan
+
+#: OWPML ``hc:RGBColorType`` — ``#`` followed by exactly six hex digits.
+_COLOR_RE = re.compile(r"#[0-9A-Fa-f]{6}")
+
+#: Matches the real-corpus fixtures' brightest observed value; any
+#: schema-valid hex is otherwise accepted.
+DEFAULT_COLOR = "#FFFF00"
+
+
+def _validate_color(color: str) -> str:
+    if not isinstance(color, str) or not _COLOR_RE.fullmatch(color):
+        raise HwpxValueError(
+            f"highlight color must be a 6-digit hex value like '#FFFF00', got {color!r}",
+            code="text-highlight-color-invalid",
+            context={"color": color},
+            suggestion="Pass a colour matching #RRGGBB (hex digits, either case).",
+        )
+    return color
+
+
+def _paragraph_has_highlightable_text(paragraph: "HwpxOxmlParagraph", match: str) -> bool:
+    """Return whether *match* lives inside one contiguous inline text piece.
+
+    Mirrors ``hwpx._document.tracked._paragraph_has_replaceable_text``: a
+    match that is only present after concatenating text across inline
+    markup (an existing highlight, a tracked-change mark, …) is real but
+    cannot be wrapped safely, so that case raises here instead of falling
+    through to a generic "not found".
+    """
+
+    crosses_inline_markup = False
+    for run in paragraph.runs:
+        model = run.to_model()
+        for span in model.text_spans:
+            if match not in span.text:
+                continue
+            if match in span.leading_text or any(
+                match in markup.trailing_text for markup in span.marks
+            ):
+                return True
+            crosses_inline_markup = True
+
+    if crosses_inline_markup:
+        raise HwpxValueError(
+            "match text crosses inline markup and cannot be wrapped safely",
+            code="text-highlight-match-crosses-markup",
+            context={"match": match},
+            suggestion="Target a substring that lives inside a single run.",
+        )
+    return False
+
+
+def add_highlight(
+    doc: "HwpxDocument",
+    paragraph: "HwpxOxmlParagraph",
+    match: str,
+    *,
+    color: str = DEFAULT_COLOR,
+) -> Highlight:
+    """Wrap the first occurrence of *match* in *paragraph* in markpen marks."""
+
+    if not match:
+        raise HwpxValueError(
+            "match text must be a non-empty string",
+            code="text-highlight-match-empty",
+            suggestion="Pass the substring to highlight.",
+        )
+    validated_color = _validate_color(color)
+
+    if not _paragraph_has_highlightable_text(paragraph, match):
+        raise HwpxValueError(
+            "match text was not found in the paragraph",
+            code="text-highlight-match-not-found",
+            context={"match": match, "paragraphText": paragraph.text},
+            suggestion="Inspect paragraph.text for the actual string.",
+        )
+
+    paragraph.add_highlight(color=validated_color, match=match)
+    return Highlight(text=match, color=validated_color, paragraph=paragraph)
+
+
+def _span_highlights(span: "TextSpan") -> list[tuple[str, "str | None"]]:
+    """Yield (text, color) for every markpen pair closed within *span*.
+
+    A LIFO stack, same as ``text_extractor._render_text_element``'s
+    ``highlight_stack`` — nested ``markpenBegin`` opens a new frame, the next
+    ``markpenEnd`` closes the innermost one. A begin left open at the end of
+    the span (no matching end inside this ``hp:t``) is still reported, same
+    as that reader closing it defensively at ``hp:t`` end; an end with
+    nothing open is silently dropped rather than fabricated.
+    """
+
+    results: list[tuple[str, "str | None"]] = []
+    stack: list[tuple["str | None", list[str]]] = []
+
+    for markup in span.marks:
+        element = markup.element
+        name = getattr(element, "name", None)
+        if name == "markpenBegin":
+            attributes = getattr(element, "attributes", None) or {}
+            stack.append((attributes.get("color"), []))
+            if markup.trailing_text:
+                stack[-1][1].append(markup.trailing_text)
+            continue
+        if name == "markpenEnd":
+            if stack:
+                mark_color, buffer = stack.pop()
+                results.append(("".join(buffer), mark_color))
+                if stack and markup.trailing_text:
+                    stack[-1][1].append(markup.trailing_text)
+            continue
+        if stack and markup.trailing_text:
+            stack[-1][1].append(markup.trailing_text)
+
+    while stack:
+        mark_color, buffer = stack.pop()
+        results.append(("".join(buffer), mark_color))
+    return results
+
+
+def list_highlights(doc: "HwpxDocument") -> tuple[Highlight, ...]:
+    """Return every markpen highlight in the document, in document order."""
+
+    results: list[Highlight] = []
+    for paragraph in doc.paragraphs:
+        for run in paragraph.runs:
+            model = run.to_model()
+            for span in model.text_spans:
+                for text, color in _span_highlights(span):
+                    results.append(Highlight(text=text, color=color, paragraph=paragraph))
+    return tuple(results)
+
+
+__all__ = ["DEFAULT_COLOR", "add_highlight", "list_highlights"]

{python_hwpx-6.0.3 → python_hwpx-6.2.1}/src/hwpx/_document/layout.py

@@ -15,6 +15,7 @@ from ..objects.results import (
     ParagraphFormatResult,
     Units,
 )
+from ..oxml._document_primitives import NEW_NUM_KINDS
 from ..oxml.namespaces import HH
 from ._units import _mm_to_hwp_units, _pt_to_hwp_units
 
@@ -119,16 +120,31 @@ def set_paragraph_format(
     keep_with_next: bool | None = None,
     keep_lines: bool | None = None,
     page_break_before: bool | None = None,
+    column_break: bool | None = None,
     bottom_border: bool = False,
     border_color: str = "#BFBFBF",
     border_width: str = "0.12 mm",
+    tab_stops: Sequence[Mapping[str, Any]] | None = None,
+    auto_tab_left: bool | None = None,
+    auto_tab_right: bool | None = None,
 ) -> ParagraphFormatResult:
     """Apply paragraph-level formatting using human units.
 
     Millimetre inputs are converted to HWP units; paragraph spacing uses
     points; line spacing is stored as a percent value. ``keep_with_next`` /
     ``keep_lines`` / ``page_break_before`` set the paragraph's keep-together
-    (``<hh:breakSetting>``) flags via a freshly minted paraPr.
+    (``<hh:breakSetting>``) flags via a freshly minted paraPr. ``column_break``
+    is a different mechanism -- ``hp:p``'s own ``columnBreak`` attribute, a
+    per-paragraph-instance forced break (not a shared paraPr style property
+    like ``page_break_before``) -- applied directly to each target paragraph.
+
+    ``tab_stops`` is a sequence of ``{"pos_mm": ..., "type": "LEFT"|"RIGHT"|
+    "CENTER"|"DECIMAL", "leader": "NONE"|...}`` mappings (``type``/``leader``
+    default to the real-corpus-majority ``"LEFT"``/``"NONE"``) — order is
+    meaningful, matching how real multi-stop documents list them
+    position-ascending. Passing ``tab_stops``/``auto_tab_left``/
+    ``auto_tab_right`` mints (or reuses — dedupe) a ``hh:tabPr`` and wires
+    the paragraph's ``tabPrIDRef`` to it.
     """
 
     if not doc._root.headers:
@@ -181,6 +197,10 @@ def set_paragraph_format(
     if page_break_before is not None:
         break_setting["page_break_before"] = bool(page_break_before)
 
+    wants_tab_definition = (
+        tab_stops is not None or auto_tab_left is not None or auto_tab_right is not None
+    )
+
     if (
         alignment is None
         and line_spacing_percent is None
@@ -188,6 +208,8 @@ def set_paragraph_format(
         and heading is None
         and not bottom_border
         and not break_setting
+        and not wants_tab_definition
+        and column_break is None
     ):
         raise HwpxValueError(
             "at least one paragraph formatting option is required",
@@ -195,6 +217,28 @@ def set_paragraph_format(
             suggestion="Pass alignment, line_spacing_percent, or another option to change.",
         )
 
+    tab_pr_id: str | None = None
+    if wants_tab_definition:
+        converted_stops: list[dict[str, object]] = []
+        for index, stop in enumerate(tab_stops or ()):
+            if "pos_mm" not in stop or stop["pos_mm"] is None:
+                raise HwpxValueError(
+                    f"tab_stops[{index}] is missing 'pos_mm'",
+                    code="paragraph-tab-pos-invalid",
+                    context={"index": index},
+                    suggestion="각 tab stop은 'pos_mm'(mm, 0 이상)가 필요합니다.",
+                )
+            converted_stops.append({
+                "pos": _mm_to_hwp_units(float(stop["pos_mm"])),
+                "type": stop.get("type"),
+                "leader": stop.get("leader"),
+            })
+        tab_pr_id = header.ensure_tab_definition(
+            tab_stops=converted_stops,
+            auto_tab_left=bool(auto_tab_left),
+            auto_tab_right=bool(auto_tab_right),
+        )
+
     border: dict[str, str] | None = None
     if bottom_border:
         border_fill_id = header.ensure_border_fill(
@@ -212,22 +256,40 @@ def set_paragraph_format(
             "ignoreMargin": "0",
         }
 
+    # column_break bypasses paraPr entirely (it's hp:p's own attribute, not
+    # a shared style) -- only mint a new paraPr when one of the *other*
+    # options actually needs it, so a column_break-only call doesn't churn
+    # a needless duplicate paraPr id.
+    wants_para_pr_change = (
+        alignment is not None
+        or line_spacing_percent is not None
+        or bool(margins)
+        or heading is not None
+        or bottom_border
+        or bool(break_setting)
+        or wants_tab_definition
+    )
+
     targets = _resolve_paragraph_targets(doc,
         paragraph_index=paragraph_index,
         paragraph_indexes=paragraph_indexes,
     )
     formatted: list[int] = []
     for index, paragraph in targets:
-        para_pr_id = header.ensure_paragraph_format(
-            base_para_pr_id=paragraph.para_pr_id_ref,
-            alignment=alignment,
-            line_spacing_percent=line_spacing_percent,
-            margins=margins,
-            heading=heading,
-            border=border,
-            break_setting=break_setting or None,
-        )
-        paragraph.para_pr_id_ref = para_pr_id
+        if wants_para_pr_change:
+            para_pr_id = header.ensure_paragraph_format(
+                base_para_pr_id=paragraph.para_pr_id_ref,
+                alignment=alignment,
+                line_spacing_percent=line_spacing_percent,
+                margins=margins,
+                heading=heading,
+                border=border,
+                break_setting=break_setting or None,
+                tab_pr_id_ref=tab_pr_id,
+            )
+            paragraph.para_pr_id_ref = para_pr_id
+        if column_break is not None:
+            paragraph.column_break = column_break
         formatted.append(index)
 
     return ParagraphFormatResult(
@@ -767,6 +829,61 @@ def set_page_number(
     )
 
 
+def restart_page_number(
+    doc: "HwpxDocument",
+    paragraph: "HwpxOxmlParagraph",
+    *,
+    number: int = 1,
+    kind: str = "PAGE",
+) -> "HwpxOxmlInlineObject":
+    """Restart *kind*'s running count at *number* from *paragraph* onward.
+
+    Inserts ``<hp:ctrl><hp:newNum num="{number}" numType="{kind}"/></hp:ctrl>``
+    — a section-mid restart point, distinct from ``set_page_number`` (which
+    places the *display* field in a header/footer). ``kind`` defaults to
+    ``"PAGE"``, the only value real corpus (hwpxlib_corpus) observes; the
+    other six (``FOOTNOTE``/``ENDNOTE``/``PICTURE``/``TABLE``/``EQUATION``/
+    ``TOTAL_PAGE``) are schema-legal but unattested.
+    """
+
+    normalized_kind = str(kind or "PAGE").upper()
+    if normalized_kind not in NEW_NUM_KINDS:
+        raise HwpxValueError(
+            f"unsupported kind {kind!r}",
+            code="page-new-num-kind-invalid",
+            context={"kind": normalized_kind, "allowed": sorted(NEW_NUM_KINDS)},
+            suggestion="Use one of: " + ", ".join(sorted(NEW_NUM_KINDS)),
+        )
+    return paragraph.add_new_num(number=number, kind=normalized_kind)
+
+
+def hide_page_elements(
+    doc: "HwpxDocument",
+    paragraph: "HwpxOxmlParagraph",
+    *,
+    header: bool = False,
+    footer: bool = False,
+    master_page: bool = False,
+    border: bool = False,
+    fill: bool = False,
+    page_num: bool = False,
+) -> "HwpxOxmlInlineObject":
+    """Hide the named page elements from *paragraph*'s page onward.
+
+    Inserts ``<hp:ctrl><hp:pageHiding .../></hp:ctrl>`` (``ParaList XML
+    schema.xml:148-163`` — six independent booleans, all default unhidden).
+    """
+
+    return paragraph.add_page_hiding(
+        header=header,
+        footer=footer,
+        master_page=master_page,
+        border=border,
+        fill=fill,
+        page_num=page_num,
+    )
+
+
 def remove_header(
     doc: "HwpxDocument",
     *,

{python_hwpx-6.0.3 → python_hwpx-6.2.1}/src/hwpx/_document/ns/__init__.py

@@ -9,7 +9,7 @@
 
 | 능력 영역 | 네임스페이스 |
 |---|---|
-| `shape-authoring`·`shape-escape-hatch`·`curve-objects`·`chart`·`equation` | `doc.shapes` |
+| `shape-authoring`·`shape-escape-hatch`·`curve-objects`·`container-authoring`·`chart`·`equation` | `doc.shapes` |
 | `picture`(BinData 절반) | `doc.media` |
 | `redline` | `doc.tracking` |
 | `memo`·`footnote-endnote` | `doc.notes` |