python-hwpx 5.0.2__tar.gz → 5.2.0__tar.gz

{python_hwpx-5.0.2 → python_hwpx-5.2.0}/NOTICE

@@ -30,9 +30,15 @@ reimplemented from public references, without copying source code:
   structure and roundtrip fixtures.
 
 - OpenBapul/hml-equation-parser (Apache-2.0): HULK-style EqEdit <-> LaTeX token
-  mapping, referenced for reader-direction <hp:equation> script rendering. The
-  token maps are a clean-room re-derivation from the public EqEdit grammar; no
-  source code was copied, translated, or vendored.
+  mapping, referenced for reader-direction <hp:equation> script rendering and
+  for the authoring-direction LaTeX -> EqEdit conversion. The token maps are a
+  clean-room re-derivation from the public EqEdit grammar; no source code was
+  copied, translated, or vendored.
+- chrisryugj/kordoc (MIT): the authoring-direction approach for native
+  <hp:equation> generation — the XML shell contract, reserved-word quoting,
+  and untrusted-input guards (source-size and recursion-depth caps) were
+  referenced as behavior evidence. Clean-room Python implementation; no source
+  code was copied, translated, or vendored.
 
 These form-fill and equation references were used as behavior evidence only. The
 implementation is a clean-room Python implementation; no source code was

{python_hwpx-5.0.2/src/python_hwpx.egg-info → python_hwpx-5.2.0}/PKG-INFO

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

{python_hwpx-5.0.2 → python_hwpx-5.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "5.0.2"
+version = "5.2.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -148,6 +148,7 @@ files = [
     "src/hwpx/equation/__init__.py",
     "src/hwpx/equation/tokens.py",
     "src/hwpx/equation/eqedit.py",
+    "src/hwpx/equation/authoring.py",
     "src/hwpx/equation/mathml.py",
     "src/hwpx/equation/render.py",
     "src/hwpx/tools/document_viewer.py",
@@ -202,6 +203,7 @@ include = [
     "src/hwpx/equation/__init__.py",
     "src/hwpx/equation/tokens.py",
     "src/hwpx/equation/eqedit.py",
+    "src/hwpx/equation/authoring.py",
     "src/hwpx/equation/mathml.py",
     "src/hwpx/equation/render.py",
     "src/hwpx/tools/document_viewer.py",

{python_hwpx-5.0.2 → python_hwpx-5.2.0}/src/hwpx/__init__.py

@@ -48,6 +48,10 @@ _EXPERIMENTAL_EXPORTS = {
     # 문서 프리뷰 뷰어(3.8.0 신규). 계약 유동.
     "DocumentViewer": "hwpx.tools.document_viewer",
     "render_document_viewer": "hwpx.tools.document_viewer",
+    # 수식 저작(5.2.0 신규, LaTeX -> EqEdit). 계약 유동.
+    "UnsupportedLatexError": "hwpx.equation.authoring",
+    "estimate_equation_size": "hwpx.equation.authoring",
+    "latex_to_eqedit": "hwpx.equation.authoring",
 }
 
 # Emptied in 5.0. The 4.x notice on these names said they would go in the next

{python_hwpx-5.0.2 → python_hwpx-5.2.0}/src/hwpx/_document/fields.py

@@ -211,10 +211,16 @@ def _form_field_payload(
         name = _field_parameter_value(parameters, "fieldName", "fieldname", "field_name", "name", "title")
     prompt = _first_attr(field_begin, _FORM_FIELD_PROMPT_ATTRS)
     if not prompt:
-        prompt = _field_parameter_value(parameters, *_FORM_FIELD_PARAM_NAMES)
+        # "Direction" is the real-Hancom 안내문 parameter (P0 gold contract).
+        prompt = _field_parameter_value(parameters, "Direction", *_FORM_FIELD_PARAM_NAMES)
     instruction = _field_parameter_value(parameters, "instruction", "guide", "help", "description", "desc")
     if not instruction:
         instruction = prompt
+    memo = _field_parameter_value(parameters, "HelpState", "memo")
+    dirty = (field_begin.get("dirty") or "").strip()
+    # Contract: while dirty != "1" the content between begin/end is the prompt
+    # placeholder (screen-only, not printed), not a user value.
+    is_placeholder = dirty != "1" and bool(prompt) and current_value == prompt
     return {
         "index": index,
         "field_id": _field_identifier(field_begin),
@@ -223,9 +229,13 @@ def _form_field_payload(
         "name": name,
         "prompt": prompt,
         "instruction": instruction,
+        "memo": memo,
+        "dirty": dirty,
+        "is_placeholder": is_placeholder,
         "current_value": current_value,
         "field_type": field_begin.get("type", ""),
         "control_type": ctrl.get("type", ""),
+        "_field_begin": field_begin,
         "section_index": section_index,
         "paragraph_index": paragraph_index,
         "paragraph_index_in_section": paragraph_index_in_section,
@@ -320,6 +330,62 @@ def list_form_fields(doc: "HwpxDocument") -> list[dict[str, Any]]:
     ]
 
 
+_PROMPT_TEXT_COLOR = "#FF0000"
+
+
+def add_form_field(
+    doc: "HwpxDocument",
+    name: str,
+    *,
+    prompt: str = "",
+    memo: str = "",
+    editable: bool = True,
+    paragraph: Any | None = None,
+    section: Any | None = None,
+    section_index: int | None = None,
+) -> dict[str, Any]:
+    """Create a click-here (누름틀) form field and return its field payload.
+
+    The emitted XML follows the real-Hancom CLICKHERE contract
+    (reverse-engineered 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
+    standard consumer would not recognize it (no special-casing by design).
+    """
+
+    if not str(name).strip():
+        raise ValueError("form field name must be a non-empty string")
+    if paragraph is None:
+        paragraph = doc.add_paragraph(
+            "", section=section, section_index=section_index, include_run=False,
+        )
+
+    prompt_char_pr: str | None = None
+    if _sanitize_field_text(prompt):
+        prompt_char_pr = doc.ensure_run_style(italic=True, color=_PROMPT_TEXT_COLOR)
+
+    control = paragraph.add_form_field(
+        name,
+        prompt=prompt,
+        memo=memo,
+        editable=editable,
+        prompt_char_pr_id_ref=prompt_char_pr,
+    )
+    _clear_form_field_layout_cache(paragraph.element)
+
+    field_begin = control.element.find(f"{_HP}fieldBegin")
+    created_id = field_begin.get("id", "") if field_begin is not None else ""
+    for match in _iter_form_field_matches(doc):
+        if match.get("id") == created_id:
+            return {
+                key: value for key, value in match.items() if not key.startswith("_")
+            }
+    raise RuntimeError(
+        "created form field was not recognized by the standard form-field matcher"
+    )
+
+
 def _select_form_field(
     doc: "HwpxDocument",
     matches: Sequence[dict[str, Any]],
@@ -447,9 +513,23 @@ def fill_form_field(
             node.text = ""
             for child in list(node):
                 child.tail = ""
+        if match.get("is_placeholder"):
+            # Contract (P0 gold): Hancom swaps the screen-only prompt style for
+            # the surrounding style when a value replaces the placeholder.
+            begin_run = runs[int(match["_begin_run_index"])]
+            begin_ref = begin_run.get("charPrIDRef")
+            primary_run = primary.getparent()
+            if begin_ref is not None and primary_run is not None:
+                primary_run.set("charPrIDRef", begin_ref)
     else:
         _insert_form_field_text_run(doc, match, sanitized)
 
+    # Contract (P0 gold): a field that went through fill machinery carries
+    # dirty="1"; while dirty != "1" readers treat the content as the prompt.
+    field_begin = match.get("_field_begin")
+    if field_begin is not None:
+        field_begin.set("dirty", "1")
+
     if fit_result is not None:
         _apply_form_field_fit_style(doc, match, fit_result)
 

{python_hwpx-5.0.2 → python_hwpx-5.2.0}/src/hwpx/_document/shapes.py

@@ -227,3 +227,58 @@ def add_ellipse(
         line_color=line_color, line_width=line_width,
         fill_color=fill_color, treat_as_char=treat_as_char,
     )
+
+
+def add_equation(
+    doc: "HwpxDocument",
+    script: str,
+    *,
+    paragraph: HwpxOxmlParagraph | None = None,
+    section: HwpxOxmlSection | None = None,
+    section_index: int | None = None,
+    base_unit: int = 1100,
+    size: tuple[int, int] | None = None,
+    char_pr_id_ref: str | int | None = None,
+) -> HwpxOxmlInlineObject:
+    """Insert an inline equation and prove the standard reader recognizes it.
+
+    The emitted XML follows the real-Hancom ``<hp:equation>`` contract
+    (specs/054-equation-authoring/evidence/p0/equation-contract.md). After
+    insertion the equation is re-read through the standard section scan —
+    creation fails loudly if the script did not land verbatim (no
+    special-casing by design).
+    """
+    from ..equation.authoring import estimate_equation_size
+    from ..equation.eqedit import MAX_SOURCE_LENGTH
+    from ..oxml.namespaces import HP
+
+    text = (script or "").strip()
+    if not text:
+        raise ValueError("equation script must be a non-empty string")
+    if len(text) > MAX_SOURCE_LENGTH:
+        raise ValueError("equation script exceeds size limit")
+    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,
+    )
+
+    created_id = inline_object.element.get("id", "")
+    for owning_section in doc.sections:
+        for candidate in owning_section.element.iter(f"{HP}equation"):
+            if candidate.get("id") != created_id:
+                continue
+            script_element = candidate.find(f"{HP}script")
+            if script_element is None or (script_element.text or "") != text:
+                raise RuntimeError(
+                    "created equation did not store its script verbatim"
+                )
+            return inline_object
+    raise RuntimeError(
+        "created equation was not recognized by the standard section scan"
+    )

{python_hwpx-5.0.2 → python_hwpx-5.2.0}/src/hwpx/document.py

@@ -1388,6 +1388,95 @@ class HwpxDocument:
             section_index=section_index,
         )
 
+    def add_form_field(
+        self,
+        name: str,
+        *,
+        prompt: str = "",
+        memo: str = "",
+        editable: bool = True,
+        paragraph: HwpxOxmlParagraph | None = None,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+    ) -> dict[str, Any]:
+        """Create a click-here (누름틀) form field. **Experimental contract.**
+
+        Emits the real-Hancom CLICKHERE shape (안내문 placeholder run included)
+        so the created field is indistinguishable from a Hancom-authored one:
+        ``list_form_fields``/``fill_form_field`` recognize it with no
+        special-casing, and real Hancom Office enumerates and fills it.
+
+        Args:
+            name: Field name (non-empty).
+            prompt: 안내문 shown while the field is empty. Screen-only —
+                Hancom does not print it.
+            memo: Help text (``HelpState``).
+            paragraph: Target paragraph (e.g. inside a table cell). When
+                omitted a new paragraph is appended to *section*.
+
+        Returns:
+            The created field's payload, same shape as a ``list_form_fields``
+            entry.
+        """
+
+        return _fields.add_form_field(
+            self,
+            name,
+            prompt=prompt,
+            memo=memo,
+            editable=editable,
+            paragraph=paragraph,
+            section=section,
+            section_index=section_index,
+        )
+
+
+    def add_equation(
+        self,
+        script: str,
+        *,
+        paragraph: HwpxOxmlParagraph | None = None,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+        base_unit: int = 1100,
+        size: tuple[int, int] | None = None,
+        char_pr_id_ref: str | int | None = None,
+    ) -> HwpxOxmlInlineObject:
+        """Insert an inline equation from an EqEdit script. **Experimental contract.**
+
+        Emits the real-Hancom ``<hp:equation>`` shape (contract:
+        ``specs/054-equation-authoring/evidence/p0/equation-contract.md``): the
+        EqEdit source is stored verbatim in ``<hp:script>``, no layout cache is
+        written (Hancom re-lays-out on open), and the shape is inline so it
+        renders in the page flow. The created element is immediately re-read
+        through the standard section scan — creation fails loudly if the
+        standard consumer would not see it (no special-casing by design).
+
+        To author from LaTeX, convert first (typed refusal outside the
+        verified token set)::
+
+            from hwpx.equation import latex_to_eqedit
+            doc.add_equation(latex_to_eqedit(r"\\frac{a}{b}"))
+
+        Args:
+            script: EqEdit script stored as-is (e.g. ``{a} over {b}``).
+            paragraph: Target paragraph (e.g. inside a table cell). When
+                omitted a new paragraph is appended to *section*.
+            base_unit: Equation base font size in 1/100 pt.
+            size: Optional explicit ``(width, height)`` HWPUNIT pair;
+                defaults to a proportional estimate (Hancom re-measures).
+        """
+
+        return _shapes.add_equation(
+            self,
+            script,
+            paragraph=paragraph,
+            section=section,
+            section_index=section_index,
+            base_unit=base_unit,
+            size=size,
+            char_pr_id_ref=char_pr_id_ref,
+        )
 
     def set_page_size(
         self,

{python_hwpx-5.0.2 → python_hwpx-5.2.0}/src/hwpx/equation/__init__.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Reader-direction equation support: EqEdit → LaTeX → MathML.
+"""Equation support: EqEdit → LaTeX → MathML (reader) and LaTeX → EqEdit (authoring).
 
 Clean-room re-derivation of the HULK-style EqEdit vocabulary; see NOTICE for the
 referenced projects.  ``latex2mathml`` is an optional dependency
@@ -9,6 +9,11 @@ block rather than dropping the equation.
 
 from __future__ import annotations
 
+from .authoring import (
+    UnsupportedLatexError,
+    estimate_equation_size,
+    latex_to_eqedit,
+)
 from .eqedit import (
     MAX_GROUP_DEPTH,
     MAX_SOURCE_LENGTH,
@@ -39,8 +44,11 @@ __all__ = [
     "EquationConversionError",
     "EquationRender",
     "MathMLUnavailableError",
+    "UnsupportedLatexError",
     "eqedit_to_latex",
+    "estimate_equation_size",
     "latex2mathml_available",
+    "latex_to_eqedit",
     "latex_to_mathml",
     "render_equation",
 ]