python-hwpx 1.0__py3-none-any.whl

hwpx/oxml/utils.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Tuple, Union
+
+from lxml import etree
+
+_TRUE_VALUES = {"1", "true", "True", "TRUE"}
+_FALSE_VALUES = {"0", "false", "False", "FALSE"}
+
+
+def local_name(node: etree._Element) -> str:
+    """Return the local (namespace-stripped) tag name for *node*."""
+    return etree.QName(node).localname
+
+
+def parse_int(value: Optional[str], *, allow_none: bool = True) -> Optional[int]:
+    """Parse *value* as an integer.
+
+    When *allow_none* is ``True`` (the default) ``None`` is returned unchanged.
+    ``ValueError`` is raised if conversion fails.
+    """
+
+    if value is None:
+        if allow_none:
+            return None
+        raise ValueError("Missing integer value")
+    try:
+        return int(value)
+    except (TypeError, ValueError) as exc:  # pragma: no cover - defensive branch
+        raise ValueError(f"Invalid integer value: {value!r}") from exc
+
+
+def parse_bool(value: Optional[str], *, default: Optional[bool] = None) -> Optional[bool]:
+    """Convert a string attribute into a boolean."""
+
+    if value is None:
+        return default
+    if value in _TRUE_VALUES:
+        return True
+    if value in _FALSE_VALUES:
+        return False
+    raise ValueError(f"Invalid boolean value: {value!r}")
+
+
+def text_or_none(node: etree._Element) -> Optional[str]:
+    """Return the text content of *node* stripped of leading/trailing whitespace."""
+
+    if node.text is None:
+        return None
+    text = node.text.strip()
+    return text if text else None
+
+
+XmlSource = Union[str, bytes, Path, etree._Element, etree._ElementTree]
+
+
+def coerce_xml_source(source: XmlSource) -> Tuple[etree._Element, etree._ElementTree]:
+    """Return ``(root, tree)`` for *source*.
+
+    *source* may be an ``lxml`` element, element tree, path-like object or
+    raw XML (``str``/``bytes``). The helper normalises the input so that callers
+    always receive both the element and the owning tree which is handy for XSD
+    validation.
+    """
+
+    if isinstance(source, etree._Element):
+        return source, source.getroottree()
+    if isinstance(source, etree._ElementTree):
+        return source.getroot(), source
+
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        if path.exists():
+            tree = etree.parse(str(path))
+            return tree.getroot(), tree
+        xml_bytes = str(source).encode("utf-8")
+    else:
+        xml_bytes = bytes(source)
+
+    root = etree.fromstring(xml_bytes)
+    return root, root.getroottree()

hwpx/package.py

@@ -0,0 +1,202 @@
+"""Utilities for working with the container format used by HWPX files."""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+from typing import BinaryIO, Dict, Iterable, Mapping, MutableMapping
+import xml.etree.ElementTree as ET
+from zipfile import ZIP_DEFLATED, ZipFile
+
+_OPF_NS = "http://www.idpf.org/2007/opf/"
+
+
+def _ensure_bytes(value: bytes | str | ET.Element) -> bytes:
+    if isinstance(value, bytes):
+        return value
+    if isinstance(value, str):
+        return value.encode("utf-8")
+    if isinstance(value, ET.Element):
+        return ET.tostring(value, encoding="utf-8", xml_declaration=True)
+    raise TypeError(f"unsupported part payload type: {type(value)!r}")
+
+
+class HwpxPackage:
+    """Represents the OPC-style package that stores HWPX parts."""
+
+    MANIFEST_PATH = "Contents/content.hpf"
+    HEADER_PATH = "Contents/header.xml"
+
+    def __init__(
+        self,
+        parts: MutableMapping[str, bytes],
+        source_path: Path | None = None,
+    ):
+        self._parts: MutableMapping[str, bytes] = dict(parts)
+        self._source_path = source_path
+        self._manifest_tree: ET.Element | None = None
+        self._spine_cache: list[str] | None = None
+        self._section_paths_cache: list[str] | None = None
+        self._header_paths_cache: list[str] | None = None
+
+    # -- construction ----------------------------------------------------
+    @classmethod
+    def open(cls, source: str | Path | bytes | BinaryIO) -> "HwpxPackage":
+        if isinstance(source, (str, Path)):
+            path = Path(source)
+            with ZipFile(path) as archive:
+                parts = {info.filename: archive.read(info.filename) for info in archive.infolist()}
+            return cls(parts, source_path=path)
+
+        if isinstance(source, (bytes, bytearray)):
+            buffer = io.BytesIO(source)
+            with ZipFile(buffer) as archive:
+                parts = {info.filename: archive.read(info.filename) for info in archive.infolist()}
+            return cls(parts)
+
+        if hasattr(source, "read"):
+            data = source.read()
+            buffer = io.BytesIO(data)
+            with ZipFile(buffer) as archive:
+                parts = {info.filename: archive.read(info.filename) for info in archive.infolist()}
+            package = cls(parts)
+            package._source_path = None
+            return package
+
+        raise TypeError("unsupported source type for HwpxPackage")
+
+    # -- accessors -------------------------------------------------------
+    def part_names(self) -> Iterable[str]:
+        return list(self._parts.keys())
+
+    def has_part(self, part_name: str) -> bool:
+        return part_name in self._parts
+
+    def get_part(self, part_name: str) -> bytes:
+        try:
+            return self._parts[part_name]
+        except KeyError as exc:
+            raise KeyError(f"package does not contain part '{part_name}'") from exc
+
+    def set_part(self, part_name: str, payload: bytes | str | ET.Element) -> None:
+        self._parts[part_name] = _ensure_bytes(payload)
+        if part_name == self.MANIFEST_PATH:
+            self._manifest_tree = None
+            self._spine_cache = None
+            self._section_paths_cache = None
+            self._header_paths_cache = None
+
+    def get_xml(self, part_name: str) -> ET.Element:
+        return ET.fromstring(self.get_part(part_name))
+
+    def set_xml(self, part_name: str, element: ET.Element) -> None:
+        self.set_part(part_name, element)
+
+    def get_text(self, part_name: str, encoding: str = "utf-8") -> str:
+        return self.get_part(part_name).decode(encoding)
+
+    # -- manifest helpers ------------------------------------------------
+    def manifest_tree(self) -> ET.Element:
+        if self._manifest_tree is None:
+            self._manifest_tree = self.get_xml(self.MANIFEST_PATH)
+        return self._manifest_tree
+
+    def _resolve_spine_paths(self) -> list[str]:
+        if self._spine_cache is None:
+            manifest = self.manifest_tree()
+            ns = {"opf": _OPF_NS}
+            manifest_items: Dict[str, str] = {}
+            for item in manifest.findall("./opf:manifest/opf:item", ns):
+                item_id = item.attrib.get("id")
+                href = item.attrib.get("href", "")
+                if item_id and href:
+                    manifest_items[item_id] = href
+            spine_paths: list[str] = []
+            for itemref in manifest.findall("./opf:spine/opf:itemref", ns):
+                idref = itemref.attrib.get("idref")
+                if not idref:
+                    continue
+                href = manifest_items.get(idref)
+                if href:
+                    spine_paths.append(href)
+            self._spine_cache = spine_paths
+        return self._spine_cache
+
+    def section_paths(self) -> list[str]:
+        if self._section_paths_cache is None:
+            from pathlib import PurePosixPath
+
+            paths = [
+                path
+                for path in self._resolve_spine_paths()
+                if path and PurePosixPath(path).name.startswith("section")
+            ]
+            if not paths:
+                # Fallback: include known section files if they exist.
+                paths = [
+                    name
+                    for name in self._parts.keys()
+                    if PurePosixPath(name).name.startswith("section")
+                ]
+            self._section_paths_cache = paths
+        return list(self._section_paths_cache)
+
+    def header_paths(self) -> list[str]:
+        if self._header_paths_cache is None:
+            from pathlib import PurePosixPath
+
+            paths = [
+                path
+                for path in self._resolve_spine_paths()
+                if path and PurePosixPath(path).name.startswith("header")
+            ]
+            if not paths and self.has_part(self.HEADER_PATH):
+                paths = [self.HEADER_PATH]
+            self._header_paths_cache = paths
+        return list(self._header_paths_cache)
+
+    # -- saving ----------------------------------------------------------
+    def save(
+        self,
+        path_or_stream: str | Path | BinaryIO | None = None,
+        updates: Mapping[str, bytes | str | ET.Element] | None = None,
+    ) -> str | Path | BinaryIO | bytes | None:
+        if updates:
+            for part_name, payload in updates.items():
+                self.set_part(part_name, payload)
+
+        destination = path_or_stream or self._source_path
+
+        if destination is None:
+            buffer = io.BytesIO()
+            self._write_to_stream(buffer)
+            return buffer.getvalue()
+
+        if isinstance(destination, (str, Path)):
+            dest_path = Path(destination)
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+            with ZipFile(dest_path, "w", compression=ZIP_DEFLATED) as archive:
+                self._write_archive(archive)
+            self._source_path = dest_path
+            return dest_path
+
+        stream = destination
+        if hasattr(stream, "seek"):
+            stream.seek(0)
+        if hasattr(stream, "truncate"):
+            stream.truncate(0)
+        with ZipFile(stream, "w", compression=ZIP_DEFLATED) as archive:
+            self._write_archive(archive)
+        if hasattr(stream, "seek"):
+            stream.seek(0)
+        return stream
+
+    # -- internals -------------------------------------------------------
+    def _write_to_stream(self, stream: BinaryIO) -> None:
+        with ZipFile(stream, "w", compression=ZIP_DEFLATED) as archive:
+            self._write_archive(archive)
+        stream.seek(0)
+
+    def _write_archive(self, archive: ZipFile) -> None:
+        for part_name in sorted(self._parts.keys()):
+            archive.writestr(part_name, self._parts[part_name])

hwpx/tools/__init__.py

@@ -0,0 +1,36 @@
+"""Tooling helpers for inspecting HWPX archives."""
+
+from .object_finder import FoundElement, ObjectFinder
+from .text_extractor import (
+    DEFAULT_NAMESPACES,
+    ParagraphInfo,
+    SectionInfo,
+    TextExtractor,
+    build_parent_map,
+    describe_element_path,
+    strip_namespace,
+)
+from .validator import (
+    DocumentSchemas,
+    ValidationIssue,
+    ValidationReport,
+    load_default_schemas,
+    validate_document,
+)
+
+__all__ = [
+    "DEFAULT_NAMESPACES",
+    "ParagraphInfo",
+    "SectionInfo",
+    "TextExtractor",
+    "build_parent_map",
+    "describe_element_path",
+    "strip_namespace",
+    "FoundElement",
+    "ObjectFinder",
+    "DocumentSchemas",
+    "ValidationIssue",
+    "ValidationReport",
+    "load_default_schemas",
+    "validate_document",
+]

hwpx/tools/_schemas/header.xsd

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    targetNamespace="http://www.hancom.co.kr/hwpml/2011/head"
+    xmlns:hh="http://www.hancom.co.kr/hwpml/2011/head"
+    elementFormDefault="qualified">
+    <xs:element name="head" type="hh:HeadType"/>
+    <xs:complexType name="HeadType">
+        <xs:sequence>
+            <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
+        </xs:sequence>
+        <xs:attribute name="version" type="xs:string" use="required"/>
+        <xs:attribute name="secCnt" type="xs:nonNegativeInteger" use="required"/>
+    </xs:complexType>
+</xs:schema>

hwpx/tools/_schemas/section.xsd

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    targetNamespace="http://www.hancom.co.kr/hwpml/2011/section"
+    xmlns:hs="http://www.hancom.co.kr/hwpml/2011/section"
+    elementFormDefault="qualified">
+    <xs:element name="sec" type="hs:SectionType"/>
+    <xs:complexType name="SectionType">
+        <xs:sequence>
+            <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
+        </xs:sequence>
+    </xs:complexType>
+</xs:schema>

hwpx/tools/object_finder.py

@@ -0,0 +1,347 @@
+"""Helper utilities that locate XML objects inside HWPX archives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import (
+    Callable,
+    Dict,
+    Iterator,
+    List,
+    Mapping,
+    Optional,
+    Pattern,
+    Sequence,
+    Tuple,
+    Union,
+)
+from xml.etree import ElementTree as ET
+from zipfile import ZipFile
+
+from .text_extractor import (
+    DEFAULT_NAMESPACES,
+    AnnotationOptions,
+    SectionInfo,
+    TextExtractor,
+    _resolve_control_nested_text,
+    _resolve_hyperlink_target,
+    _resolve_note_text,
+    build_parent_map,
+    describe_element_path,
+    strip_namespace,
+    tag_matches,
+)
+
+__all__ = ["AttrMatcher", "AnnotationMatch", "FoundElement", "ObjectFinder"]
+
+
+AttrMatcher = Union[str, Sequence[str], Pattern[str], Callable[[str], bool]]
+
+
+@dataclass(frozen=True)
+class FoundElement:
+    """Location information for an XML element that matched a query."""
+
+    section: SectionInfo
+    path: str
+    element: ET.Element
+
+    @property
+    def tag(self) -> str:
+        """Return the local tag name for the matched element."""
+
+        return strip_namespace(self.element.tag)
+
+    @property
+    def hierarchy(self) -> Tuple[str, ...]:
+        """Return the split representation of :pyattr:`path`."""
+
+        return tuple(self.path.split("/"))
+
+    @property
+    def text(self) -> Optional[str]:
+        """Expose ``element.text`` for convenience."""
+
+        return self.element.text
+
+    def get(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """Fetch an attribute value from the underlying element."""
+
+        return self.element.attrib.get(name, default)
+
+    def __str__(self) -> str:  # pragma: no cover - debugging helper
+        section = self.section.name
+        return f"{section}:{self.path} <{self.tag}>"
+
+
+@dataclass(frozen=True)
+class AnnotationMatch:
+    """Representation of a document annotation located by the finder."""
+
+    kind: str
+    element: FoundElement
+    value: Optional[str]
+
+
+class ObjectFinder:
+    """Perform element searches across the XML payload in an HWPX document."""
+
+    def __init__(
+        self,
+        source: Union[str, Path, ZipFile],
+        *,
+        namespaces: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        self._source = source
+        merged_namespaces = dict(DEFAULT_NAMESPACES)
+        if namespaces:
+            merged_namespaces.update(namespaces)
+        self.namespaces: Dict[str, str] = merged_namespaces
+
+    def iter(
+        self,
+        *,
+        tag: Union[str, Sequence[str], None] = None,
+        attrs: Optional[Mapping[str, AttrMatcher]] = None,
+        xpath: Optional[str] = None,
+        limit: Optional[int] = None,
+        section_filter: Optional[Callable[[SectionInfo], bool]] = None,
+    ) -> Iterator[FoundElement]:
+        """Yield elements that match a combination of criteria."""
+
+        with TextExtractor(self._source, namespaces=self.namespaces) as extractor:
+            for section in extractor.iter_sections():
+                if section_filter is not None and not section_filter(section):
+                    continue
+                parent_map = build_parent_map(section.element)
+                if xpath is not None:
+                    candidates = section.element.findall(xpath, namespaces=self.namespaces)
+                else:
+                    candidates = section.element.iter()
+                for element in candidates:
+                    if tag is not None and not tag_matches(element.tag, tag, self.namespaces):
+                        continue
+                    if attrs and not self._match_attributes(element, attrs):
+                        continue
+                    path = describe_element_path(element, parent_map)
+                    yield FoundElement(section=section, path=path, element=element)
+                    if limit is not None:
+                        limit -= 1
+                        if limit <= 0:
+                            return
+
+    def find_first(
+        self,
+        *,
+        tag: Union[str, Sequence[str], None] = None,
+        attrs: Optional[Mapping[str, AttrMatcher]] = None,
+        xpath: Optional[str] = None,
+        section_filter: Optional[Callable[[SectionInfo], bool]] = None,
+    ) -> Optional[FoundElement]:
+        """Return the first element that matches or ``None`` when absent."""
+
+        return next(
+            self.iter(
+                tag=tag,
+                attrs=attrs,
+                xpath=xpath,
+                limit=1,
+                section_filter=section_filter,
+            ),
+            None,
+        )
+
+    def find_all(
+        self,
+        *,
+        tag: Union[str, Sequence[str], None] = None,
+        attrs: Optional[Mapping[str, AttrMatcher]] = None,
+        xpath: Optional[str] = None,
+        section_filter: Optional[Callable[[SectionInfo], bool]] = None,
+        limit: Optional[int] = None,
+    ) -> List[FoundElement]:
+        """Return every matching element eagerly as a list."""
+
+        return list(
+            self.iter(
+                tag=tag,
+                attrs=attrs,
+                xpath=xpath,
+                limit=limit,
+                section_filter=section_filter,
+            )
+        )
+
+    def iter_annotations(
+        self,
+        *,
+        kinds: Optional[Sequence[str]] = None,
+        options: Optional[AnnotationOptions] = None,
+        section_filter: Optional[Callable[[SectionInfo], bool]] = None,
+        preserve_breaks: bool = True,
+    ) -> Iterator[AnnotationMatch]:
+        """Yield annotations such as highlights or notes with formatted values."""
+
+        requested = {
+            kind.lower() for kind in (kinds or ("highlight", "footnote", "endnote", "hyperlink", "control"))
+        }
+        if not requested:
+            return
+
+        render_options = options or AnnotationOptions()
+
+        with TextExtractor(self._source, namespaces=self.namespaces) as extractor:
+            for section in extractor.iter_sections():
+                if section_filter is not None and not section_filter(section):
+                    continue
+                parent_map = build_parent_map(section.element)
+
+                if "highlight" in requested:
+                    for element in section.element.findall(
+                        ".//hp:markpenBegin", namespaces=self.namespaces
+                    ):
+                        path = describe_element_path(element, parent_map)
+                        found = FoundElement(section=section, path=path, element=element)
+                        color = element.get("color") or ""
+                        if render_options.highlight == "markers":
+                            value = render_options.highlight_start.format(color=color)
+                        else:
+                            value = render_options.highlight_summary.format(color=color)
+                        yield AnnotationMatch("highlight", found, value)
+
+                if "footnote" in requested:
+                    for element in section.element.findall(
+                        ".//hp:footNote", namespaces=self.namespaces
+                    ):
+                        yield self._format_note_annotation(
+                            extractor,
+                            section,
+                            parent_map,
+                            element,
+                            kind="footnote",
+                            options=render_options,
+                            preserve_breaks=preserve_breaks,
+                        )
+
+                if "endnote" in requested:
+                    for element in section.element.findall(
+                        ".//hp:endNote", namespaces=self.namespaces
+                    ):
+                        yield self._format_note_annotation(
+                            extractor,
+                            section,
+                            parent_map,
+                            element,
+                            kind="endnote",
+                            options=render_options,
+                            preserve_breaks=preserve_breaks,
+                        )
+
+                if "hyperlink" in requested:
+                    for element in section.element.findall(
+                        ".//hp:fieldBegin", namespaces=self.namespaces
+                    ):
+                        field_type = (element.get("type") or "").upper()
+                        if field_type != "HYPERLINK":
+                            continue
+                        path = describe_element_path(element, parent_map)
+                        found = FoundElement(section=section, path=path, element=element)
+                        target = _resolve_hyperlink_target(element, self.namespaces) or ""
+                        behavior = render_options.hyperlink
+                        if behavior == "target":
+                            value = render_options.hyperlink_target_format.format(target=target)
+                        elif behavior == "placeholder":
+                            value = render_options.hyperlink_placeholder.format(target=target)
+                        else:
+                            value = render_options.hyperlink_summary.format(target=target)
+                        yield AnnotationMatch("hyperlink", found, value)
+
+                if "control" in requested:
+                    for element in section.element.findall(
+                        ".//hp:ctrl", namespaces=self.namespaces
+                    ):
+                        field_begin = element.find("hp:fieldBegin", namespaces=self.namespaces)
+                        if field_begin is not None and (field_begin.get("type") or "").upper() == "HYPERLINK":
+                            continue
+                        if element.find("hp:fieldEnd", namespaces=self.namespaces) is not None:
+                            continue
+                        path = describe_element_path(element, parent_map)
+                        found = FoundElement(section=section, path=path, element=element)
+                        first_child = next(iter(element), None)
+                        name = strip_namespace(first_child.tag) if first_child is not None else "ctrl"
+                        ctrl_type = (
+                            first_child.get("type") if first_child is not None else element.get("type") or ""
+                        )
+                        behavior = render_options.control
+                        if behavior == "nested":
+                            value = _resolve_control_nested_text(
+                                extractor,
+                                element,
+                                render_options,
+                                preserve_breaks=preserve_breaks,
+                            )
+                        elif behavior == "placeholder":
+                            value = render_options.control_placeholder.format(name=name, type=ctrl_type)
+                        else:
+                            value = render_options.control_summary.format(name=name, type=ctrl_type)
+                        yield AnnotationMatch("control", found, value)
+
+    def _format_note_annotation(
+        self,
+        extractor: TextExtractor,
+        section: SectionInfo,
+        parent_map: Mapping[ET.Element, ET.Element],
+        element: ET.Element,
+        *,
+        kind: str,
+        options: AnnotationOptions,
+        preserve_breaks: bool,
+    ) -> AnnotationMatch:
+        path = describe_element_path(element, parent_map)
+        found = FoundElement(section=section, path=path, element=element)
+        inst_id = element.get("instId") or ""
+        behavior = options.footnote if kind == "footnote" else options.endnote
+        if behavior == "inline":
+            text = _resolve_note_text(
+                extractor,
+                element,
+                options,
+                preserve_breaks=preserve_breaks,
+            )
+            value = options.note_inline_format.format(kind=kind, inst_id=inst_id, text=text)
+        elif behavior == "placeholder":
+            value = options.note_placeholder.format(kind=kind, inst_id=inst_id)
+        else:
+            value = options.note_summary.format(kind=kind, inst_id=inst_id)
+        return AnnotationMatch(kind, found, value)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+    @staticmethod
+    def _match_attributes(
+        element: ET.Element,
+        expected: Mapping[str, AttrMatcher],
+    ) -> bool:
+        for name, matcher in expected.items():
+            value = element.attrib.get(name)
+            if value is None:
+                return False
+            if isinstance(matcher, str):
+                if value != matcher:
+                    return False
+            elif isinstance(matcher, Sequence) and not isinstance(matcher, (str, bytes)):
+                if value not in matcher:
+                    return False
+            elif hasattr(matcher, "search"):
+                if not matcher.search(value):  # type: ignore[call-arg]
+                    return False
+            elif callable(matcher):
+                if not matcher(value):
+                    return False
+            else:
+                raise TypeError(
+                    "Attribute matchers must be str, Sequence, Pattern or callable",
+                )
+        return True