python-hwpx 3.1.0__tar.gz → 3.3.0__tar.gz

{python_hwpx-3.1.0/src/python_hwpx.egg-info → python_hwpx-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 3.1.0
+Version: 3.3.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -70,7 +70,8 @@ Dynamic: license-file
 `hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
 “first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
 
-현재 공개 릴리스와 최소 호환 코어 버전은 모두 `python-hwpx 3.1.0`입니다.
+현재 PyPI 공개 릴리스는 `python-hwpx 3.3.0`입니다. 일반
+`pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
 

{python_hwpx-3.1.0 → python_hwpx-3.3.0}/README.md

@@ -25,7 +25,8 @@
 `hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
 “first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
 
-현재 공개 릴리스와 최소 호환 코어 버전은 모두 `python-hwpx 3.1.0`입니다.
+현재 PyPI 공개 릴리스는 `python-hwpx 3.3.0`입니다. 일반
+`pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
 

{python_hwpx-3.1.0 → python_hwpx-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "3.1.0"
+version = "3.3.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -109,11 +109,25 @@ python_version = "3.10"
 follow_imports = "skip"
 files = [
     "src/hwpx/document.py",
+    "src/hwpx/agent/commands.py",
+    "src/hwpx/agent/document.py",
+    "src/hwpx/agent/story.py",
+    "src/hwpx/oxml/_document_impl.py",
+    "src/hwpx/oxml/_document_primitives.py",
     "src/hwpx/oxml/document.py",
+    "src/hwpx/oxml/document_parts.py",
+    "src/hwpx/oxml/header_part.py",
+    "src/hwpx/oxml/memo.py",
+    "src/hwpx/oxml/numbering.py",
+    "src/hwpx/oxml/objects.py",
     "src/hwpx/opc/package.py",
     "src/hwpx/opc/relationships.py",
     "src/hwpx/oxml/paragraph.py",
     "src/hwpx/oxml/run.py",
+    "src/hwpx/oxml/section.py",
+    "src/hwpx/oxml/section_format.py",
+    "src/hwpx/oxml/section_story.py",
+    "src/hwpx/oxml/simple_parts.py",
     "src/hwpx/oxml/table.py",
     "src/hwpx/quality/policy.py",
     "src/hwpx/quality/report.py",
@@ -123,23 +137,36 @@ files = [
     "src/hwpx/tools/template_analyzer.py",
     "src/hwpx/tools/text_extract_cli.py",
     "src/hwpx/tools/text_extractor.py",
+    "src/hwpx/visual/oracle.py",
     "tests/template_automation/helpers.py",
     "tests/template_automation/generate_fixtures.py",
 ]
 ignore_missing_imports = true
 
-[[tool.mypy.overrides]]
-module = ["hwpx.document", "hwpx.oxml.document"]
-ignore_errors = true
-
 [tool.pyright]
-# Keep basic pyright focused on OPC/tooling modules that currently pass
-# without suppressing their real diagnostics.
+# Keep basic pyright focused on the explicit gradual scope. Feature 025 adds
+# both central facades and every extracted/touched runtime owner to the gate.
 include = [
+    "src/hwpx/document.py",
+    "src/hwpx/agent/commands.py",
+    "src/hwpx/agent/document.py",
+    "src/hwpx/agent/story.py",
+    "src/hwpx/oxml/_document_impl.py",
+    "src/hwpx/oxml/_document_primitives.py",
+    "src/hwpx/oxml/document.py",
+    "src/hwpx/oxml/document_parts.py",
+    "src/hwpx/oxml/header_part.py",
+    "src/hwpx/oxml/memo.py",
+    "src/hwpx/oxml/numbering.py",
+    "src/hwpx/oxml/objects.py",
     "src/hwpx/opc/package.py",
     "src/hwpx/opc/relationships.py",
     "src/hwpx/oxml/paragraph.py",
     "src/hwpx/oxml/run.py",
+    "src/hwpx/oxml/section.py",
+    "src/hwpx/oxml/section_format.py",
+    "src/hwpx/oxml/section_story.py",
+    "src/hwpx/oxml/simple_parts.py",
     "src/hwpx/oxml/table.py",
     "src/hwpx/quality/policy.py",
     "src/hwpx/quality/report.py",
@@ -149,6 +176,7 @@ include = [
     "src/hwpx/tools/template_analyzer.py",
     "src/hwpx/tools/text_extract_cli.py",
     "src/hwpx/tools/text_extractor.py",
+    "src/hwpx/visual/oracle.py",
     "tests/template_automation/helpers.py",
     "tests/template_automation/generate_fixtures.py",
 ]

{python_hwpx-3.1.0 → python_hwpx-3.3.0}/src/hwpx/agent/commands.py

@@ -21,7 +21,7 @@ from pathlib import Path
 from typing import Any
 from xml.etree import ElementTree as ET
 
-from lxml import etree as LET
+from lxml import etree as LET  # type: ignore[reportAttributeAccessIssue]  # lxml has no complete bundled typing
 
 from hwpx.document import HwpxDocument
 from hwpx.oxml import HwpxOxmlTable
@@ -38,6 +38,12 @@ from .model import (
     validate_agent_batch,
 )
 from .path import parse_path
+from .story import (
+    HEADER_STORY_EDITABLE_PROPERTIES,
+    HEADER_STORY_KIND,
+    HeaderStoryBinding,
+    try_parse_header_story_path,
+)
 
 _EMPTY_REVISION = "sha256:" + hashlib.sha256(b"").hexdigest()
 _HWP_UNITS_PER_MM = 7200 / 25.4
@@ -242,6 +248,21 @@ def _validate_property_values(kind: str, properties: Mapping[str, Any], *, creat
             raise AgentContractError("unknown_property", f"untyped property: {target}", target=target)
 
 
+def _validate_header_story_properties(properties: Mapping[str, Any]) -> None:
+    unknown = sorted(set(properties) - HEADER_STORY_EDITABLE_PROPERTIES)
+    if unknown:
+        raise AgentContractError(
+            "unknown_property",
+            f"header does not support properties: {unknown}",
+            target=f"header.{unknown[0]}",
+        )
+    if "text" not in properties:
+        raise AgentContractError(
+            "invalid_syntax", "existing header set requires text", target="header.text"
+        )
+    _require_string(properties["text"], "header.text")
+
+
 def _preflight(batch: Mapping[str, Any]) -> None:
     """Reject the complete static command matrix before the first mutation."""
 
@@ -254,6 +275,9 @@ def _preflight(batch: Mapping[str, Any]) -> None:
                 return alias_kinds[command_id][field]
             except KeyError as exc:  # validate_agent_batch already checks ordering
                 raise AgentContractError("not_found", f"unknown command alias: {value}") from exc
+        story = try_parse_header_story_path(value)
+        if story is not None:
+            return story.kind
         parsed = parse_path(value)
         return parsed.segments[-1].kind if parsed.segments else "document"
 
@@ -264,6 +288,9 @@ def _preflight(batch: Mapping[str, Any]) -> None:
                 return alias_kinds[command_id]["parentPath" if field == "path" else field]
             except KeyError:
                 return "document"
+        story = try_parse_header_story_path(value)
+        if story is not None:
+            return "section"
         parsed = parse_path(value)
         return parsed.segments[-2].kind if len(parsed.segments) > 1 else "document"
 
@@ -298,6 +325,19 @@ def _preflight(batch: Mapping[str, Any]) -> None:
             }
             continue
         source_kind = reference_kind(command["path"])
+        if source_kind == HEADER_STORY_KIND:
+            if op != "set":
+                raise AgentContractError(
+                    "unsupported_operation",
+                    f"{op} is unsupported for {source_kind}",
+                    target=command["commandId"],
+                )
+            _validate_header_story_properties(command["properties"])
+            alias_kinds[command["commandId"]] = {
+                "path": source_kind,
+                "parentPath": "section",
+            }
+            continue
         if op not in NODE_PROPERTY_CATALOG_V1[source_kind]["operations"]:
             raise AgentContractError(
                 "unsupported_operation",
@@ -309,11 +349,11 @@ def _preflight(batch: Mapping[str, Any]) -> None:
         destination_kind = parent_kind(command["path"])
         if op in {"move", "copy"}:
             destination_kind = reference_kind(command["parent"])
-            expected_parent = _MOVE_COPY_PARENTS.get(source_kind)
-            if destination_kind != expected_parent:
+            move_parent = _MOVE_COPY_PARENTS.get(source_kind)
+            if destination_kind != move_parent:
                 raise AgentContractError(
                     "incompatible_parent",
-                    f"{source_kind} requires a {expected_parent} parent, not {destination_kind}",
+                    f"{source_kind} requires a {move_parent} parent, not {destination_kind}",
                     target=command["commandId"],
                 )
         alias_kinds[command["commandId"]] = {
@@ -570,6 +610,42 @@ def _mark_containing_section(document: HwpxDocument, target: Any) -> None:
     raise AgentContractError("not_found", "mutated element is detached")
 
 
+def _apply_header_story_set(
+    binding: HeaderStoryBinding, properties: Mapping[str, Any]
+) -> dict[str, Any]:
+    """Apply the bounded existing-header mutation through its OXML owner."""
+
+    _validate_header_story_properties(properties)
+    try:
+        binding.native.set_simple_text_preserving(properties["text"])
+    except AgentContractError:
+        raise
+    except ValueError as exc:
+        # The OXML owner uses ValueError for rich/control-bearing or otherwise
+        # structurally unsafe headers.  Do not let it degrade to the generic
+        # invariant envelope or fall back to the destructive whole-story setter.
+        message = str(exc) or "header content cannot be edited losslessly"
+        lowered = message.lower()
+        code = (
+            "ambiguous_target"
+            if "ambiguous" in lowered
+            else "not_found"
+            if "not found" in lowered
+            else "unsupported_content"
+        )
+        raise AgentContractError(
+            code,
+            message,
+            target=binding.path,
+        ) from exc
+    return {
+        "text": {
+            "before": binding.text,
+            "after": properties["text"],
+        }
+    }
+
+
 def _apply_set(document: HwpxDocument, record: NodeRecord, properties: Mapping[str, Any]) -> dict[str, Any]:
     _ensure_operation(record, "set")
     _validate_property_values(record.kind, properties, creating=False)
@@ -711,7 +787,10 @@ def _add(
         if "pageHeightMm" in properties:
             size_kwargs["height"] = round(properties["pageHeightMm"] * _HWP_UNITS_PER_MM)
         if size_kwargs:
-            created.properties.set_page_size(**size_kwargs)
+            created.properties.set_page_size(
+                width=size_kwargs.get("width"),
+                height=size_kwargs.get("height"),
+            )
         return created
     if kind == "paragraph":
         created = parent.native.add_paragraph(str(properties.get("text", "")))
@@ -1081,6 +1160,47 @@ def _member_diff(before: bytes, after: bytes) -> dict[str, Any]:
         return {"ok": False, "error": f"{type(exc).__name__}: {exc}"}
 
 
+def _verify_header_story_candidates(
+    candidate_data: bytes,
+    candidate_revision: str,
+    expectations: Mapping[str, Mapping[str, str]],
+) -> dict[str, Any]:
+    receipts: list[dict[str, Any]] = []
+    if expectations:
+        with HwpxDocument.open(candidate_data) as reopened:
+            view = HwpxAgentDocument.from_document(
+                reopened, revision=candidate_revision
+            )
+            for expectation in expectations.values():
+                path = expectation["path"]
+                binding = view._resolve_header_story(path)
+                if (
+                    binding.stable_id != expectation["stableId"]
+                    or binding.page_type != expectation["pageType"]
+                    or binding.text != expectation["text"]
+                ):
+                    raise AgentContractError(
+                        "verification_failed",
+                        "reopened header story does not match the committed binding",
+                        target=path,
+                    )
+                receipts.append(
+                    {
+                        "commandId": expectation["commandId"],
+                        "path": binding.path,
+                        "stableId": binding.stable_id,
+                        "pageType": binding.page_type,
+                        "textMatched": True,
+                    }
+                )
+    return {
+        "schemaVersion": "hwpx.agent-story-preservation/v1",
+        "ok": True,
+        "storyCount": len(receipts),
+        "stories": receipts,
+    }
+
+
 def _request_hash(batch: Mapping[str, Any]) -> str:
     payload = json.dumps(
         batch,
@@ -1192,6 +1312,7 @@ def apply_document_commands(
         aliases: dict[str, dict[str, str]] = {}
         identity_changes: list[Mapping[str, str]] = []
         semantic_changes: list[Mapping[str, Any]] = []
+        story_expectations: dict[str, Mapping[str, str]] = {}
         _call_fault(fault_injector, "before_open")
         with HwpxDocument.open(input_data) as document:
             view = HwpxAgentDocument.from_document(document, revision=input_revision)
@@ -1203,11 +1324,24 @@ def apply_document_commands(
                 parent_path: str | None = None
                 changed: dict[str, Any] = {}
                 generated: list[dict[str, str]] = []
+                target_native: Any | None = None
+                story_before: HeaderStoryBinding | None = None
                 if op == "set":
                     resolved_path = _resolve_alias(command["path"], aliases)
-                    record = view.resolve_record(resolved_path, expected_revision=input_revision)
-                    changed = _apply_set(document, record, command["properties"])
-                    target_native = record.native
+                    story_path = try_parse_header_story_path(resolved_path)
+                    if story_path is not None:
+                        story_before = view._resolve_header_story(
+                            story_path, expected_revision=input_revision
+                        )
+                        changed = _apply_header_story_set(
+                            story_before, command["properties"]
+                        )
+                    else:
+                        record = view.resolve_record(
+                            resolved_path, expected_revision=input_revision
+                        )
+                        changed = _apply_set(document, record, command["properties"])
+                        target_native = record.native
                 elif op == "add":
                     parent_path = _resolve_alias(command["parent"], aliases)
                     parent = view.resolve_record(parent_path, expected_revision=input_revision)
@@ -1244,7 +1378,26 @@ def apply_document_commands(
 
                 _call_fault(fault_injector, "after_command", index)
                 view = HwpxAgentDocument.from_document(document, revision=input_revision)
-                if op == "set" and resolved_path is not None:
+                result_stable_id: str | None = None
+                if story_before is not None and resolved_path is not None:
+                    target_story = view._resolve_header_story(resolved_path)
+                    if target_story.stable_id != story_before.stable_id:
+                        raise AgentContractError(
+                            "invariant_violation",
+                            "header story identity changed during text edit",
+                            target=resolved_path,
+                        )
+                    result_path = target_story.path
+                    result_parent = target_story.parent_path
+                    result_stable_id = target_story.stable_id
+                    story_expectations[target_story.binding_key] = {
+                        "commandId": command_id,
+                        "path": target_story.path,
+                        "stableId": target_story.stable_id,
+                        "pageType": target_story.page_type,
+                        "text": command["properties"]["text"],
+                    }
+                elif op == "set" and resolved_path is not None:
                     # Some native bindings (notably form fields) are request-local
                     # match dictionaries.  A property edit is non-structural, so
                     # its canonical path is the durable post-edit lookup key.
@@ -1269,6 +1422,11 @@ def apply_document_commands(
                     "generatedIdentities": generated,
                     "warnings": [],
                 }
+                if result_stable_id is not None:
+                    # Command results are already an untyped JSON mapping.  This
+                    # story-only receipt carries the actual stable identity
+                    # without changing AgentBatchResult or the ToolSpec schema.
+                    result["stableId"] = result_stable_id
                 command_results.append(result)
                 semantic_changes.append(
                     {
@@ -1285,6 +1443,12 @@ def apply_document_commands(
             _call_fault(fault_injector, "after_serialize")
 
             candidate_revision = _revision(candidate_data)
+            if story_expectations:
+                verification["storyPreservation"] = _verify_header_story_candidates(
+                    candidate_data,
+                    candidate_revision,
+                    story_expectations,
+                )
             semantic_diff = {
                 "schemaVersion": "hwpx.agent-semantic-diff/v1",
                 "inputRevision": input_revision,

{python_hwpx-3.1.0 → python_hwpx-3.3.0}/src/hwpx/agent/document.py

@@ -8,7 +8,7 @@ from collections import Counter, defaultdict
 from dataclasses import dataclass, field
 from os import PathLike
 from pathlib import Path
-from typing import Any
+from typing import Any, Sequence, cast
 
 from hwpx.document import HwpxDocument
 from hwpx.oxml import HwpxOxmlShape
@@ -22,7 +22,14 @@ from .model import (
     NODE_PROPERTY_CATALOG_V1,
 )
 from .path import SemanticPath, canonicalize_path, identified_segment, indexed_segment
+from .query import QueryRecord as _QueryRecord
 from .query import QueryResult, evaluate_selector, parse_selector
+from .story import (
+    HeaderStoryBinding,
+    HeaderStoryPath,
+    parse_header_story_path,
+    resolve_header_story,
+)
 
 _HWP_UNITS_PER_MM = 7200 / 25.4
 _SHAPE_KINDS = frozenset({"line", "rect", "ellipse", "arc", "polygon", "curve", "connectLine"})
@@ -129,7 +136,7 @@ class HwpxAgentDocument:
     def __enter__(self) -> "HwpxAgentDocument":
         return self
 
-    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:  # type: ignore[exit-return]  # frozen public signature
         self.close()
         return False
 
@@ -689,6 +696,25 @@ class HwpxAgentDocument:
             raise AgentContractError("volatile_target", "target has a positional path", target=canonical)
         return record
 
+    def _resolve_header_story(
+        self,
+        path: str | HeaderStoryPath,
+        *,
+        expected_revision: str | None = None,
+    ) -> HeaderStoryBinding:
+        """Resolve the private command-only existing-header seam.
+
+        Header stories deliberately remain absent from ``records``, ``get``,
+        and ``query`` so the frozen public projection/catalog does not drift.
+        """
+
+        parsed = parse_header_story_path(path) if isinstance(path, str) else path
+        if expected_revision is not None and expected_revision != self.revision:
+            raise AgentContractError(
+                "stale_revision", "document revision does not match", target=parsed.canonical
+            )
+        return resolve_header_story(self.document, parsed)
+
     def _public_node(self, record: NodeRecord, *, depth: int, child_limit: int) -> AgentNode:
         supported_total = len(record.child_paths)
         selected_paths = record.child_paths[:child_limit] if depth > 0 else []
@@ -751,7 +777,8 @@ class HwpxAgentDocument:
         if expected_revision is not None and expected_revision != self.revision:
             raise AgentContractError("stale_revision", "document revision does not match", target="selector")
         parsed = parse_selector(selector)
-        matches, truncated = evaluate_selector(self.records, parsed, limit=limit)
+        query_records = cast(Sequence[_QueryRecord], self.records)
+        matches, truncated = evaluate_selector(query_records, parsed, limit=limit)
         if not 0 <= node_depth <= MAX_VIEW_DEPTH:
             raise AgentContractError("resource_limit", "nodeDepth is out of bounds", target="nodeDepth")
         if not 1 <= child_limit <= MAX_CHILDREN_PER_NODE:
@@ -760,7 +787,12 @@ class HwpxAgentDocument:
             selector=selector,
             revision=self.revision,
             nodes=tuple(
-                self._public_node(record, depth=node_depth, child_limit=child_limit) for record in matches
+                self._public_node(
+                    cast(NodeRecord, record),
+                    depth=node_depth,
+                    child_limit=child_limit,
+                )
+                for record in matches
             ),
             truncated=truncated,
         )