python-hwpx 6.0.3__py3-none-any.whl → 6.2.1__py3-none-any.whl

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

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

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

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` |

hwpx/_document/ns/page.py

@@ -27,7 +27,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Mapping, Sequence
 
 from ...errors import HwpxValueError
-from .._resolve import resolve_section
+from .._resolve import resolve_paragraph, resolve_section
 from ._base import _Namespace
 
 if TYPE_CHECKING:
@@ -37,6 +37,7 @@ if TYPE_CHECKING:
         PageMargins,
         PageSize,
         SectionGrid,
+        SectionTextDirection,
         SectionVisibility,
     )
     from ...objects import PageSetup
@@ -44,6 +45,10 @@ if TYPE_CHECKING:
 
 __all__ = ["PageNamespace"]
 
+#: 6.12 트레인㊸ 갭③ — 스키마 선언 열거값(다른 어떤 값도 실코퍼스에 없음,
+#: 실측 근거는 SectionTextDirection 독스트링 참조).
+_TEXT_DIRECTIONS = frozenset({"HORIZONTAL", "VERTICAL", "VERTICALALL"})
+
 
 class PageNamespace(_Namespace):
     """쪽 기하 — 용지·여백·단·머리말/꼬리말·쪽번호·격자·줄번호."""
@@ -339,6 +344,54 @@ class PageNamespace(_Namespace):
             section=self._section(section, section_index, "set_page_number"),
         )
 
+    def restart_page_number(
+        self,
+        paragraph: "HwpxOxmlParagraph | int",
+        *,
+        number: int = 1,
+        kind: str = "PAGE",
+    ) -> "HwpxOxmlInlineObject":
+        """*paragraph* 부터 *kind* 의 진행 번호를 *number* 로 재시작한다.
+
+        `set_page_number` 가 머리말/꼬리말의 *표시* 필드를 다루는 것과 달리,
+        이건 구역 중간의 재시작 지점(`hp:newNum`)을 문단에 심는다.
+        """
+
+        from .. import layout as _layout
+
+        return _layout.restart_page_number(
+            self._doc,
+            resolve_paragraph(self._doc, paragraph, caller="doc.page.restart_page_number"),
+            number=number,
+            kind=kind,
+        )
+
+    def hide_page_elements(
+        self,
+        paragraph: "HwpxOxmlParagraph | int",
+        *,
+        header: bool = False,
+        footer: bool = False,
+        master_page: bool = False,
+        border: bool = False,
+        fill: bool = False,
+        page_num: bool = False,
+    ) -> "HwpxOxmlInlineObject":
+        """*paragraph* 가 속한 쪽부터 지정한 요소를 숨긴다(`hp:pageHiding`)."""
+
+        from .. import layout as _layout
+
+        return _layout.hide_page_elements(
+            self._doc,
+            resolve_paragraph(self._doc, paragraph, caller="doc.page.hide_page_elements"),
+            header=header,
+            footer=footer,
+            master_page=master_page,
+            border=border,
+            fill=fill,
+            page_num=page_num,
+        )
+
     # -- 읽기: 현재 지면 상태 ----------------------------------------------
 
     def size(
@@ -368,6 +421,33 @@ class PageNamespace(_Namespace):
     # 저수준 API 는 ``HwpxOxmlSectionProperties`` 가 소유하고(Q3b), 여기서는 쪽
     # 기하 축의 나머지와 같은 자리에 노출하기만 한다.
 
+    def master_page_refs(
+        self,
+        *,
+        section: "int | HwpxOxmlSection | None" = None,
+        section_index: int | None = None,
+    ) -> tuple[str, ...]:
+        """이 절이 참조하는 바탕쪽 id(``hp:masterPage/@idRef``) 목록."""
+
+        return self._section(
+            section, section_index, "master_page_refs"
+        ).properties.master_page_refs
+
+    def set_master_page(
+        self,
+        master_page_id: str,
+        *,
+        section: "int | HwpxOxmlSection | None" = None,
+        section_index: int | None = None,
+    ) -> None:
+        """이 절이 바탕쪽(``doc.parts.add_master_page``가 만든 id)을
+        참조하도록 등록한다(6.13 트레인㊻). 이미 참조 중이면 아무 일도
+        안 한다(멱등)."""
+
+        self._section(
+            section, section_index, "set_master_page"
+        ).properties.add_master_page_reference(master_page_id)
+
     def grid(
         self,
         *,
@@ -395,6 +475,50 @@ class PageNamespace(_Namespace):
             wonggoji_format=wonggoji_format,
         )
 
+    def text_direction(
+        self,
+        *,
+        section: "int | HwpxOxmlSection | None" = None,
+        section_index: int | None = None,
+    ) -> "SectionTextDirection":
+        """글자 방향(가로쓰기/세로쓰기)과 머리말/꼬리말 세로쓰기 여부."""
+
+        return self._section(
+            section, section_index, "text_direction"
+        ).properties.text_direction
+
+    def set_text_direction(
+        self,
+        direction: str | None = None,
+        *,
+        vertical_header_footer: bool | None = None,
+        section: "int | HwpxOxmlSection | None" = None,
+        section_index: int | None = None,
+    ) -> None:
+        """글자 방향(세로쓰기 포함)을 설정한다.
+
+        실코퍼스 67파일 전수에 `VERTICAL`/`VERTICALALL` 실사용 예가 없다
+        (74/74 `HORIZONTAL`) — 스키마 열거값 자체는 명확해 저작을 막지
+        않지만, 실한컴 렌더 검증 전까지는 "Create(experimental)"로만
+        표기한다(``docs/support-matrix.md`` 참조).
+        """
+
+        if direction is not None and direction not in _TEXT_DIRECTIONS:
+            raise HwpxValueError(
+                f"unsupported text direction: {direction}",
+                code="page-text-direction-unsupported",
+                context={
+                    "requested": direction,
+                    "supported": sorted(_TEXT_DIRECTIONS),
+                },
+                suggestion=f"Supported: {', '.join(sorted(_TEXT_DIRECTIONS))}",
+            )
+        self._section(
+            section, section_index, "set_text_direction"
+        ).properties.set_text_direction(
+            direction, vertical_header_footer=vertical_header_footer
+        )
+
     def visibility(
         self,
         *,