python-hwpx 1.0__py3-none-any.whl

hwpx/opc/package.py

@@ -0,0 +1,274 @@
+"""Utilities for reading and writing HWPX OPC packages."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from io import BytesIO
+from typing import BinaryIO, Iterable, Iterator, Mapping, MutableMapping
+from xml.etree import ElementTree as ET
+from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile, ZipInfo
+
+__all__ = ["HwpxPackage", "HwpxPackageError", "HwpxStructureError", "RootFile", "VersionInfo"]
+
+
+class HwpxPackageError(Exception):
+    """Base error raised for issues related to :class:`HwpxPackage`."""
+
+
+class HwpxStructureError(HwpxPackageError):
+    """Raised when the underlying HWPX package violates the required structure."""
+
+
+@dataclass(frozen=True)
+class RootFile:
+    """Represents a ``rootfile`` entry from ``META-INF/container.xml``."""
+
+    full_path: str
+    media_type: str | None = None
+
+    def ensure_exists(self, files: Mapping[str, bytes]) -> None:
+        """Ensure that the referenced root file actually exists in ``files``."""
+
+        if self.full_path not in files:
+            raise HwpxStructureError(
+                f"Root content '{self.full_path}' declared in container.xml is missing."
+            )
+
+
+class VersionInfo:
+    """Model for the ``version.xml`` document."""
+
+    def __init__(
+        self,
+        element: ET.Element,
+        namespaces: Mapping[str, str],
+        xml_declaration: bytes | None,
+    ) -> None:
+        self._element = element
+        self._namespaces = dict(namespaces)
+        self._xml_declaration = xml_declaration
+        self._dirty = False
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> VersionInfo:
+        element = ET.fromstring(data)
+        namespaces = cls._collect_namespaces(data)
+        declaration = cls._extract_declaration(data)
+        return cls(element, namespaces, declaration)
+
+    @staticmethod
+    def _collect_namespaces(data: bytes) -> Mapping[str, str]:
+        namespaces: dict[str, str] = {}
+        for event, elem in ET.iterparse(BytesIO(data), events=("start-ns",)):
+            prefix, uri = elem
+            namespaces[prefix or ""] = uri
+        return namespaces
+
+    @staticmethod
+    def _extract_declaration(data: bytes) -> bytes | None:
+        data = data.lstrip()
+        if not data.startswith(b"<?xml"):
+            return None
+        end = data.find(b"?>")
+        if end == -1:
+            return None
+        return data[: end + 2]
+
+    @property
+    def attributes(self) -> Mapping[str, str]:
+        return dict(self._element.attrib)
+
+    def get(self, key: str, default: str | None = None) -> str | None:
+        return self._element.attrib.get(key, default)
+
+    def set(self, key: str, value: str) -> None:
+        self._element.attrib[key] = value
+        self._dirty = True
+
+    @property
+    def tag(self) -> str:
+        return self._element.tag
+
+    def to_bytes(self) -> bytes:
+        for prefix, uri in self._namespaces.items():
+            ET.register_namespace(prefix, uri)
+        stream = BytesIO()
+        tree = ET.ElementTree(self._element)
+        tree.write(stream, encoding="utf-8", xml_declaration=False)
+        xml_body = stream.getvalue()
+        if self._xml_declaration:
+            return self._xml_declaration + xml_body
+        return xml_body
+
+    @property
+    def dirty(self) -> bool:
+        return self._dirty
+
+    def mark_clean(self) -> None:
+        self._dirty = False
+
+
+class HwpxPackage:
+    """Represents an HWPX package backed by an Open Packaging Convention container."""
+
+    CONTAINER_PATH = "META-INF/container.xml"
+    VERSION_PATH = "version.xml"
+    MIMETYPE_PATH = "mimetype"
+    DEFAULT_MIMETYPE = "application/hwp+zip"
+
+    def __init__(
+        self,
+        files: MutableMapping[str, bytes],
+        rootfiles: Iterable[RootFile],
+        version_info: VersionInfo,
+        mimetype: str,
+    ) -> None:
+        self._files = files
+        self._rootfiles = list(rootfiles)
+        self._version = version_info
+        self._mimetype = mimetype
+        self._validate_structure()
+
+    @classmethod
+    def open(cls, pkg_file: str | BinaryIO) -> HwpxPackage:
+        with ZipFile(pkg_file, "r") as zf:
+            files = {info.filename: zf.read(info) for info in zf.infolist()}
+        if cls.MIMETYPE_PATH not in files:
+            raise HwpxStructureError("HWPX package is missing the mandatory 'mimetype' file.")
+        mimetype = files[cls.MIMETYPE_PATH].decode("utf-8")
+        rootfiles = cls._parse_container(files.get(cls.CONTAINER_PATH))
+        version_info = cls._parse_version(files.get(cls.VERSION_PATH))
+        package = cls(files, rootfiles, version_info, mimetype)
+        return package
+
+    @staticmethod
+    def _parse_container(data: bytes | None) -> list[RootFile]:
+        if data is None:
+            raise HwpxStructureError(
+                "HWPX package is missing 'META-INF/container.xml'."
+            )
+        root = ET.fromstring(data)
+        rootfiles = []
+        for elem in root.findall(".//{*}rootfile"):
+            full_path = (
+                elem.get("full-path")
+                or elem.get("fullPath")
+                or elem.get("full_path")
+            )
+            if not full_path:
+                raise HwpxStructureError("container.xml contains a rootfile without 'full-path'.")
+            media_type = (
+                elem.get("media-type")
+                or elem.get("mediaType")
+                or elem.get("media_type")
+            )
+            rootfiles.append(RootFile(full_path, media_type))
+        if not rootfiles:
+            raise HwpxStructureError("container.xml does not declare any rootfiles.")
+        return rootfiles
+
+    @staticmethod
+    def _parse_version(data: bytes | None) -> VersionInfo:
+        if data is None:
+            raise HwpxStructureError("HWPX package is missing 'version.xml'.")
+        return VersionInfo.from_bytes(data)
+
+    def _validate_structure(self) -> None:
+        for rootfile in self._rootfiles:
+            rootfile.ensure_exists(self._files)
+        if not any(path.startswith(("Contents/", "Content/")) for path in self._files):
+            raise HwpxStructureError(
+                "HWPX package does not contain a 'Contents' directory."
+            )
+
+    @property
+    def mimetype(self) -> str:
+        return self._mimetype
+
+    @property
+    def rootfiles(self) -> tuple[RootFile, ...]:
+        return tuple(self._rootfiles)
+
+    def iter_rootfiles(self) -> Iterator[RootFile]:
+        yield from self._rootfiles
+
+    @property
+    def main_content(self) -> RootFile:
+        for rootfile in self._rootfiles:
+            if rootfile.media_type == "application/hwpml-package+xml":
+                return rootfile
+        return self._rootfiles[0]
+
+    @property
+    def version_info(self) -> VersionInfo:
+        return self._version
+
+    def read(self, path: str) -> bytes:
+        norm_path = self._normalize_path(path)
+        try:
+            return self._files[norm_path]
+        except KeyError as exc:
+            raise HwpxPackageError(f"File '{norm_path}' is not present in the package.") from exc
+
+    def write(self, path: str, data: bytes | str) -> None:
+        norm_path = self._normalize_path(path)
+        if isinstance(data, str):
+            data = data.encode("utf-8")
+        pending_rootfiles: list[RootFile] | None = None
+        pending_version: VersionInfo | None = None
+        if norm_path == self.MIMETYPE_PATH:
+            mimetype = data.decode("utf-8")
+        elif norm_path == self.CONTAINER_PATH:
+            pending_rootfiles = self._parse_container(data)
+        elif norm_path == self.VERSION_PATH:
+            pending_version = self._parse_version(data)
+        self._files[norm_path] = data
+        if norm_path == self.MIMETYPE_PATH:
+            self._mimetype = mimetype
+        elif norm_path == self.CONTAINER_PATH:
+            assert pending_rootfiles is not None
+            self._rootfiles = pending_rootfiles
+        elif norm_path == self.VERSION_PATH:
+            assert pending_version is not None
+            self._version = pending_version
+        self._validate_structure()
+
+    def delete(self, path: str) -> None:
+        norm_path = self._normalize_path(path)
+        if norm_path not in self._files:
+            raise HwpxPackageError(f"File '{norm_path}' is not present in the package.")
+        if norm_path in {self.MIMETYPE_PATH, self.CONTAINER_PATH, self.VERSION_PATH}:
+            raise HwpxStructureError(
+                "Cannot remove mandatory files ('mimetype', 'container.xml', 'version.xml')."
+            )
+        del self._files[norm_path]
+        self._validate_structure()
+
+    @staticmethod
+    def _normalize_path(path: str) -> str:
+        return path.replace("\\", "/")
+
+    def files(self) -> list[str]:
+        return sorted(self._files)
+
+    def save(self, pkg_file: str | BinaryIO) -> None:
+        self._files[self.MIMETYPE_PATH] = self._mimetype.encode("utf-8")
+        if self._version.dirty:
+            self._files[self.VERSION_PATH] = self._version.to_bytes()
+            self._version.mark_clean()
+        self._validate_structure()
+        with ZipFile(pkg_file, "w") as zf:
+            self._write_mimetype(zf)
+            for name in sorted(self._files):
+                if name == self.MIMETYPE_PATH:
+                    continue
+                data = self._files[name]
+                info = ZipInfo(name)
+                info.compress_type = ZIP_DEFLATED
+                zf.writestr(info, data)
+
+    def _write_mimetype(self, zf: ZipFile) -> None:
+        info = ZipInfo(self.MIMETYPE_PATH)
+        info.compress_type = ZIP_STORED
+        zf.writestr(info, self._files[self.MIMETYPE_PATH])
+

hwpx/oxml/__init__.py

@@ -0,0 +1,138 @@
+
+"""Open XML helpers for the HWPX document format."""
+
+from __future__ import annotations
+
+from .body import (
+    Paragraph,
+    Run,
+    Section,
+    TextSpan,
+    parse_paragraph_element,
+    parse_run_element,
+    parse_section_element,
+    parse_text_span,
+)
+from .common import GenericElement, parse_generic_element
+
+from .document import (
+    DocumentNumbering,
+    HwpxOxmlDocument,
+    HwpxOxmlHeader,
+    HwpxOxmlInlineObject,
+    HwpxOxmlMemo,
+    HwpxOxmlMemoGroup,
+    HwpxOxmlParagraph,
+    HwpxOxmlRun,
+    HwpxOxmlSection,
+    HwpxOxmlSectionHeaderFooter,
+    HwpxOxmlSectionProperties,
+    HwpxOxmlTable,
+    HwpxOxmlTableCell,
+    HwpxOxmlTableRow,
+    PageMargins,
+    PageSize,
+    RunStyle,
+    SectionStartNumbering,
+)
+
+from .header import (
+    BeginNum,
+    BorderFillList,
+    CharProperty,
+    CharPropertyList,
+    DocOption,
+    Font,
+    FontFace,
+    FontFaceList,
+    FontSubstitution,
+    FontTypeInfo,
+    ForbiddenWordList,
+    Header,
+    KeyDerivation,
+    KeyEncryption,
+    LinkInfo,
+    LicenseMark,
+    MemoProperties,
+    MemoShape,
+    NumberingList,
+    RefList,
+    TabProperties,
+    TrackChangeConfig,
+    memo_shape_from_attributes,
+    parse_begin_num,
+    parse_doc_option,
+    parse_header_element,
+    parse_memo_properties,
+    parse_memo_shape,
+    parse_ref_list,
+)
+from .parser import element_to_model, parse_header_xml, parse_section_xml
+from .schema import load_schema
+from .utils import XmlSource
+
+__all__ = [
+    "BeginNum",
+    "BorderFillList",
+    "CharProperty",
+    "CharPropertyList",
+    "DocOption",
+    "Font",
+    "FontFace",
+    "FontFaceList",
+    "FontSubstitution",
+    "FontTypeInfo",
+    "ForbiddenWordList",
+    "GenericElement",
+    "Header",
+    "DocumentNumbering",
+    "HwpxOxmlDocument",
+    "HwpxOxmlHeader",
+    "HwpxOxmlInlineObject",
+    "HwpxOxmlMemo",
+    "HwpxOxmlMemoGroup",
+    "HwpxOxmlParagraph",
+    "HwpxOxmlRun",
+    "HwpxOxmlSection",
+    "HwpxOxmlSectionHeaderFooter",
+    "HwpxOxmlSectionProperties",
+    "HwpxOxmlTable",
+    "HwpxOxmlTableCell",
+    "HwpxOxmlTableRow",
+    "KeyDerivation",
+    "KeyEncryption",
+    "LinkInfo",
+    "LicenseMark",
+    "MemoProperties",
+    "MemoShape",
+    "NumberingList",
+    "Paragraph",
+    "PageMargins",
+    "PageSize",
+    "RunStyle",
+    "memo_shape_from_attributes",
+    "RefList",
+    "Run",
+    "Section",
+    "SectionStartNumbering",
+    "TabProperties",
+    "TextSpan",
+    "TrackChangeConfig",
+    "XmlSource",
+    "element_to_model",
+    "load_schema",
+    "parse_begin_num",
+    "parse_doc_option",
+    "parse_generic_element",
+    "parse_header_element",
+    "parse_memo_properties",
+    "parse_memo_shape",
+    "parse_header_xml",
+    "parse_paragraph_element",
+    "parse_ref_list",
+    "parse_run_element",
+    "parse_section_element",
+    "parse_section_xml",
+    "parse_text_span",
+]
+

hwpx/oxml/body.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from lxml import etree
+
+from .common import GenericElement, parse_generic_element
+from .utils import local_name, parse_bool, parse_int
+
+
+INLINE_OBJECT_NAMES = {
+    "line",
+    "rect",
+    "ellipse",
+    "arc",
+    "polyline",
+    "polygon",
+    "curve",
+    "picture",
+    "tbl",
+    "shape",
+    "drawingObject",
+    "equation",
+    "ole",
+    "chart",
+    "video",
+    "audio",
+}
+
+
+@dataclass(slots=True)
+class TextSpan:
+    text: str
+    marks: List[GenericElement] = field(default_factory=list)
+    attributes: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class Run:
+    char_pr_id_ref: Optional[int]
+    section_properties: List[GenericElement] = field(default_factory=list)
+    controls: List[GenericElement] = field(default_factory=list)
+    inline_objects: List[GenericElement] = field(default_factory=list)
+    text_spans: List[TextSpan] = field(default_factory=list)
+    other_children: List[GenericElement] = field(default_factory=list)
+    attributes: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class Paragraph:
+    id: Optional[int]
+    para_pr_id_ref: Optional[int]
+    style_id_ref: Optional[int]
+    page_break: Optional[bool]
+    column_break: Optional[bool]
+    merged: Optional[bool]
+    runs: List[Run] = field(default_factory=list)
+    attributes: Dict[str, str] = field(default_factory=dict)
+    other_children: List[GenericElement] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class Section:
+    attributes: Dict[str, str]
+    paragraphs: List[Paragraph] = field(default_factory=list)
+    other_children: List[GenericElement] = field(default_factory=list)
+
+
+def parse_text_span(node: etree._Element) -> TextSpan:
+    parts: List[str] = []
+    marks: List[GenericElement] = []
+
+    if node.text:
+        parts.append(node.text)
+
+    for child in node:
+        marks.append(parse_generic_element(child))
+        if child.tail:
+            parts.append(child.tail)
+
+    text = "".join(parts)
+    return TextSpan(text=text, marks=marks, attributes={key: value for key, value in node.attrib.items()})
+
+
+def parse_run_element(node: etree._Element) -> Run:
+    attributes = {key: value for key, value in node.attrib.items()}
+    char_pr_id_ref = parse_int(attributes.pop("charPrIDRef", None))
+
+    run = Run(char_pr_id_ref=char_pr_id_ref, attributes=attributes)
+
+    for child in node:
+        name = local_name(child)
+        if name == "secPr":
+            run.section_properties.append(parse_generic_element(child))
+        elif name == "ctrl":
+            run.controls.append(parse_generic_element(child))
+        elif name == "t":
+            run.text_spans.append(parse_text_span(child))
+        elif name in INLINE_OBJECT_NAMES:
+            run.inline_objects.append(parse_generic_element(child))
+        else:
+            run.other_children.append(parse_generic_element(child))
+
+    return run
+
+
+def parse_paragraph_element(node: etree._Element) -> Paragraph:
+    attributes = {key: value for key, value in node.attrib.items()}
+
+    paragraph = Paragraph(
+        id=parse_int(attributes.pop("id", None)),
+        para_pr_id_ref=parse_int(attributes.pop("paraPrIDRef", None)),
+        style_id_ref=parse_int(attributes.pop("styleIDRef", None)),
+        page_break=parse_bool(attributes.pop("pageBreak", None)),
+        column_break=parse_bool(attributes.pop("columnBreak", None)),
+        merged=parse_bool(attributes.pop("merged", None)),
+        attributes=attributes,
+    )
+
+    for child in node:
+        if local_name(child) == "run":
+            paragraph.runs.append(parse_run_element(child))
+        else:
+            paragraph.other_children.append(parse_generic_element(child))
+
+    return paragraph
+
+
+def parse_section_element(node: etree._Element) -> Section:
+    section = Section(attributes={key: value for key, value in node.attrib.items()})
+
+    for child in node:
+        if local_name(child) == "p":
+            section.paragraphs.append(parse_paragraph_element(child))
+        else:
+            section.other_children.append(parse_generic_element(child))
+
+    return section
+
+
+__all__ = [
+    "Paragraph",
+    "Run",
+    "Section",
+    "TextSpan",
+    "parse_paragraph_element",
+    "parse_run_element",
+    "parse_section_element",
+    "parse_text_span",
+]

hwpx/oxml/common.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from lxml import etree
+
+from .utils import local_name
+
+
+@dataclass(slots=True)
+class GenericElement:
+    """Fallback representation for XML elements without a specialised model."""
+
+    name: str
+    attributes: Dict[str, str] = field(default_factory=dict)
+    children: List["GenericElement"] = field(default_factory=list)
+    text: Optional[str] = None
+
+
+def parse_generic_element(node: etree._Element) -> GenericElement:
+    """Convert *node* into a :class:`GenericElement`."""
+
+    children = [parse_generic_element(child) for child in node]
+    text = node.text if node.text is not None else None
+    return GenericElement(
+        name=local_name(node),
+        attributes={key: value for key, value in node.attrib.items()},
+        children=children,
+        text=text,
+    )