python-hwpx-automation 6.0.3__py3-none-any.whl

hwpx_automation/core/handles.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Helpers for generating stable handles for logical nodes."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Iterable, Tuple
+
+
+def _normalize_parts(parts: Iterable[str | int]) -> Tuple[str, ...]:
+    normalized: list[str] = []
+    for part in parts:
+        text = str(part)
+        normalized.append(text)
+    return tuple(normalized)
+
+
+def stable_node_id(parts: Iterable[str | int]) -> str:
+    """Return a deterministic identifier for the provided structural path."""
+
+    normalized = _normalize_parts(parts)
+    joined = "::".join(normalized)
+    digest = hashlib.sha256(joined.encode("utf-8")).hexdigest()[:16]
+    return f"n_{digest}"

hwpx_automation/core/locations.py

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterator
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedParagraph:
+    paragraph: Any
+    location: dict[str, Any]
+
+
+def body_paragraph_location(paragraph_index: int) -> dict[str, Any]:
+    return {"kind": "body_paragraph", "paragraph_index": paragraph_index}
+
+
+def table_cell_paragraph_location(
+    table_index: int,
+    row: int,
+    col: int,
+    cell_paragraph_index: int,
+) -> dict[str, Any]:
+    return {
+        "kind": "table_cell_paragraph",
+        "table_index": table_index,
+        "row": row,
+        "col": col,
+        "cell_paragraph_index": cell_paragraph_index,
+    }
+
+
+def location_anchor(location: dict[str, Any], position: int | None = None) -> dict[str, Any]:
+    anchor_id = _anchor_id(location, position)
+    payload: dict[str, Any] = {"anchor_id": anchor_id, "location": dict(location)}
+    if position is not None:
+        payload["position"] = position
+    return payload
+
+
+def location_from_anchor(anchor: dict[str, Any] | str) -> dict[str, Any]:
+    if isinstance(anchor, dict):
+        if isinstance(anchor.get("location"), dict):
+            return dict(anchor["location"])
+        if "kind" in anchor:
+            return dict(anchor)
+    if not isinstance(anchor, str):
+        raise ValueError("anchor must be an object with location or an anchor_id string")
+
+    head = anchor.split("@", 1)[0]
+    parts = head.split(":")
+    if parts[0] == "body" and len(parts) == 2:
+        return body_paragraph_location(_int(parts[1], "paragraph_index"))
+    if parts[0] == "table" and len(parts) == 5:
+        return table_cell_paragraph_location(
+            _int(parts[1], "table_index"),
+            _int(parts[2], "row"),
+            _int(parts[3], "col"),
+            _int(parts[4], "cell_paragraph_index"),
+        )
+    raise ValueError(f"unsupported anchor_id: {anchor}")
+
+
+def iter_indexed_tables(doc: Any) -> Iterator[tuple[int, Any]]:
+    table_index = 0
+    for paragraph in getattr(doc, "paragraphs", []):
+        for table in _iter_tables_from_paragraph(paragraph):
+            yield table_index, table
+            table_index += 1
+
+
+def iter_paragraph_locations(doc: Any) -> Iterator[ResolvedParagraph]:
+    for paragraph_index, paragraph in enumerate(getattr(doc, "paragraphs", [])):
+        yield ResolvedParagraph(paragraph, body_paragraph_location(paragraph_index))
+
+    for table_index, table in iter_indexed_tables(doc):
+        for row, col, cell in _iter_anchor_cells(table):
+            for cell_paragraph_index, paragraph in enumerate(getattr(cell, "paragraphs", []) or []):
+                yield ResolvedParagraph(
+                    paragraph,
+                    table_cell_paragraph_location(table_index, row, col, cell_paragraph_index),
+                )
+
+
+def resolve_paragraph_reference(
+    doc: Any,
+    *,
+    paragraph_index: int | None = None,
+    location: dict[str, Any] | None = None,
+    create: bool = False,
+) -> ResolvedParagraph:
+    if location is None:
+        if paragraph_index is None:
+            raise ValueError("paragraph_index 또는 location 중 하나를 제공해야 합니다.")
+        return _resolve_body_paragraph(doc, paragraph_index)
+
+    kind = str(location.get("kind") or "").strip()
+    if kind in {"body", "paragraph", "body_paragraph"}:
+        index_value = location.get("paragraph_index", paragraph_index)
+        if index_value is None:
+            raise ValueError("body_paragraph location에는 paragraph_index가 필요합니다.")
+        return _resolve_body_paragraph(doc, int(index_value))
+
+    if kind in {"table_cell_paragraph", "cell_paragraph"}:
+        return _resolve_table_cell_paragraph(doc, location, create=create)
+
+    raise ValueError(f"지원하지 않는 location kind: {kind or '<missing>'}")
+
+
+def _resolve_body_paragraph(doc: Any, paragraph_index: int) -> ResolvedParagraph:
+    paragraphs = list(getattr(doc, "paragraphs", []))
+    if paragraph_index < 0 or paragraph_index >= len(paragraphs):
+        raise ValueError(f"유효하지 않은 paragraph_index: {paragraph_index}")
+    return ResolvedParagraph(paragraphs[paragraph_index], body_paragraph_location(paragraph_index))
+
+
+def _resolve_table_cell_paragraph(
+    doc: Any,
+    location: dict[str, Any],
+    *,
+    create: bool,
+) -> ResolvedParagraph:
+    table_index = _int(location.get("table_index"), "table_index")
+    row = _int(location.get("row"), "row")
+    col = _int(location.get("col"), "col")
+    cell_paragraph_index = _int(
+        location.get("cell_paragraph_index", location.get("p", 0)),
+        "cell_paragraph_index",
+    )
+
+    tables = [table for _, table in iter_indexed_tables(doc)]
+    if table_index < 0 or table_index >= len(tables):
+        raise ValueError(f"유효하지 않은 table_index: {table_index}")
+
+    try:
+        cell = tables[table_index].cell(row, col)
+    except (IndexError, ValueError) as exc:
+        raise ValueError(f"유효하지 않은 table cell 좌표: table={table_index}, row={row}, col={col}") from exc
+
+    paragraphs = list(getattr(cell, "paragraphs", []) or [])
+    if create and not paragraphs and hasattr(cell, "add_paragraph"):
+        paragraphs = [cell.add_paragraph("")]
+
+    if cell_paragraph_index < 0 or cell_paragraph_index >= len(paragraphs):
+        raise ValueError(
+            "유효하지 않은 cell_paragraph_index: "
+            f"{cell_paragraph_index} (table={table_index}, row={row}, col={col})"
+        )
+
+    normalized = table_cell_paragraph_location(table_index, row, col, cell_paragraph_index)
+    return ResolvedParagraph(paragraphs[cell_paragraph_index], normalized)
+
+
+def _iter_tables_from_paragraph(paragraph: Any) -> Iterator[Any]:
+    for table in getattr(paragraph, "tables", []) or []:
+        yield table
+        yield from _iter_nested_tables(table)
+
+
+def _iter_nested_tables(table: Any) -> Iterator[Any]:
+    for row in getattr(table, "rows", []) or []:
+        for cell in getattr(row, "cells", []) or []:
+            for paragraph in getattr(cell, "paragraphs", []) or []:
+                yield from _iter_tables_from_paragraph(paragraph)
+
+
+def _iter_anchor_cells(table: Any) -> Iterator[tuple[int, int, Any]]:
+    if hasattr(table, "iter_grid"):
+        seen: set[int] = set()
+        for position in table.iter_grid():
+            if not getattr(position, "is_anchor", False):
+                continue
+            cell = position.cell
+            marker = id(getattr(cell, "element", cell))
+            if marker in seen:
+                continue
+            seen.add(marker)
+            row, col = getattr(position, "anchor", (position.row, position.column))
+            yield int(row), int(col), cell
+        return
+
+    for row_index, row in enumerate(getattr(table, "rows", []) or []):
+        for col_index, cell in enumerate(getattr(row, "cells", []) or []):
+            yield row_index, col_index, cell
+
+
+def _int(value: Any, name: str) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be an integer") from exc
+
+
+def _anchor_id(location: dict[str, Any], position: int | None) -> str:
+    suffix = "" if position is None else f"@{position}"
+    kind = location.get("kind")
+    if kind == "body_paragraph":
+        return f"body:{location['paragraph_index']}{suffix}"
+    if kind == "table_cell_paragraph":
+        return (
+            "table:"
+            f"{location['table_index']}:{location['row']}:{location['col']}:"
+            f"{location['cell_paragraph_index']}{suffix}"
+        )
+    return f"{kind or 'unknown'}{suffix}"

hwpx_automation/core/locator.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Document locator models used across tool schemas."""
+
+from __future__ import annotations
+
+from typing import Annotated, Dict, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from typing_extensions import Literal
+
+
+_LOCATOR_KEYS = {"type", "path", "uri", "backend", "handleId"}
+
+
+class _LocatorModel(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class PathLocator(_LocatorModel):
+    type: Literal["path"] = Field("path", alias="type")
+    path: str
+    backend: Optional[str] = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _default_type(cls, data: object) -> object:
+        if isinstance(data, dict) and "type" not in data and "path" in data:
+            enriched = dict(data)
+            enriched.setdefault("type", "path")
+            return enriched
+        return data
+
+
+class UriLocator(_LocatorModel):
+    type: Literal["uri"] = Field("uri", alias="type")
+    uri: str
+    backend: Optional[str] = None
+
+
+class HandleLocator(_LocatorModel):
+    type: Literal["handle"] = Field("handle", alias="type")
+    handle_id: str = Field(alias="handleId")
+    backend: Optional[str] = None
+
+
+class RegisteredHandle(_LocatorModel):
+    """서버가 관리하는 등록 핸들의 읽기 전용 직렬화 모델."""
+
+    type: Literal["handle"] = Field("handle", alias="type")
+    handle_id: str = Field(alias="handleId")
+    path: str
+    backend: Optional[str] = None
+
+
+DocumentLocator = Annotated[
+    PathLocator | UriLocator | HandleLocator,
+    Field(discriminator="type"),
+]
+
+
+def normalize_locator_payload(data: Dict[str, object], *, field_name: str = "document") -> Dict[str, object]:
+    """Return *data* with locator keys grouped under *field_name*.
+
+    The function accepts legacy payloads that specify ``path`` at the top level
+    while also supporting fully qualified discriminated union inputs.
+    """
+
+    if field_name in data:
+        return data
+
+    locator: Dict[str, object] = {}
+    remainder: Dict[str, object] = {}
+    for key, value in data.items():
+        if key in _LOCATOR_KEYS:
+            locator[key] = value
+        else:
+            remainder[key] = value
+
+    if not locator:
+        raise ValueError("document locator must include path, uri, or handleId")
+
+    if "type" not in locator:
+        if "path" in locator:
+            locator["type"] = "path"
+        elif "uri" in locator:
+            locator["type"] = "uri"
+        elif "handleId" in locator:
+            locator["type"] = "handle"
+        else:  # pragma: no cover - defensive guard
+            raise ValueError("document locator requires a discriminator")
+
+    remainder[field_name] = locator
+    return remainder
+
+
+def locator_identifier(locator: DocumentLocator) -> str:
+    """Return a stable identifier for *locator*."""
+
+    if isinstance(locator, PathLocator):
+        return locator.path
+    if isinstance(locator, UriLocator):
+        return locator.uri
+    if isinstance(locator, HandleLocator):
+        return locator.handle_id
+    raise TypeError(f"Unsupported locator type: {type(locator)!r}")
+
+
+def locator_path(locator: DocumentLocator) -> Optional[str]:
+    """Return the preferred path-like value for *locator* if available."""
+
+    if isinstance(locator, PathLocator):
+        return locator.path
+    if isinstance(locator, UriLocator):
+        return locator.uri
+    return None
+
+
+def locator_backend(locator: DocumentLocator) -> Optional[str]:
+    """Return the backend hint provided by *locator*, if any."""
+
+    return getattr(locator, "backend", None)
+
+
+def document_locator_schema() -> Dict[str, object]:
+    """Return a sanitized JSON schema fragment for document locators."""
+
+    return {
+        "type": "object",
+        "description": (
+            "Discriminated locator supporting legacy paths, HTTP URIs, or opaque handles. "
+            "Top-level path/uri/handleId shorthands remain supported for backwards compatibility."
+        ),
+        "properties": {
+            "type": {
+                "type": "string",
+                "enum": ["path", "uri", "handle"],
+                "description": "Locator variant; defaults to 'path' when omitted.",
+            },
+            "path": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Filesystem-relative path resolved by the configured storage backend.",
+            },
+            "uri": {
+                "type": "string",
+                "minLength": 1,
+                "description": "HTTP or backend-specific URI when using remote storage.",
+            },
+            "handleId": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Opaque identifier for a previously registered document handle.",
+            },
+            "backend": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Optional hint describing the storage backend to use (e.g. 'http').",
+            },
+        },
+        "required": ["type"],
+        "additionalProperties": False,
+    }