python-hwpx 2.7.1__py3-none-any.whl → 2.8.2__py3-none-any.whl

hwpx/opc/package.py

@@ -7,12 +7,21 @@ import io
 import os
 import tempfile
 from dataclasses import dataclass
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import BinaryIO, Iterable, Iterator, Mapping, MutableMapping
 from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile, ZipInfo
 
-from lxml import etree
+from lxml import etree  # type: ignore[reportAttributeAccessIssue]
 
+from .relationships import (
+    MAIN_ROOTFILE_MEDIA_TYPE,
+    OPF_NS,
+    is_header_part_name,
+    is_section_part_name,
+    normalize_part_name,
+    parse_container_rootfiles,
+    parse_manifest_relationships,
+)
 from .xml_utils import (
     extract_xml_declaration,
     iter_declared_namespaces,
@@ -24,8 +33,6 @@ __all__ = ["HwpxPackage", "HwpxPackageError", "HwpxStructureError", "RootFile",
 
 logger = logging.getLogger(__name__)
 
-_OPF_NS = "http://www.idpf.org/2007/opf/"
-
 
 class HwpxPackageError(Exception):
     """Base error raised for issues related to :class:`HwpxPackage`."""
@@ -169,25 +176,10 @@ class HwpxPackage:
         except Exception:
             logger.exception("container.xml 파싱에 실패했습니다.")
             raise
-        rootfiles = []
-        for elem in root.findall(".//{*}rootfile"):
-            full_path_attr = elem.get("full-path")
-            full_path = full_path_attr or elem.get("fullPath") or elem.get("full_path")
-            if full_path and not full_path_attr:
-                logger.warning(
-                    "container.xml rootfile이 비표준 경로 속성명을 사용했습니다: %s",
-                    elem.attrib,
-                )
-            if not full_path:
-                raise HwpxStructureError("container.xml contains a rootfile without 'full-path'.")
-            media_type_attr = elem.get("media-type")
-            media_type = media_type_attr or elem.get("mediaType") or elem.get("media_type")
-            if media_type and not media_type_attr:
-                logger.warning(
-                    "container.xml rootfile이 비표준 media-type 속성명을 사용했습니다: %s",
-                    elem.attrib,
-                )
-            rootfiles.append(RootFile(full_path, media_type))
+        rootfiles = [
+            RootFile(ref.full_path, ref.media_type)
+            for ref in parse_container_rootfiles(root)
+        ]
         if not rootfiles:
             raise HwpxStructureError("container.xml does not declare any rootfiles.")
         return rootfiles
@@ -201,10 +193,6 @@ class HwpxPackage:
     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:
@@ -220,7 +208,7 @@ class HwpxPackage:
     @property
     def main_content(self) -> RootFile:
         for rootfile in self._rootfiles:
-            if rootfile.media_type == "application/hwpml-package+xml":
+            if rootfile.media_type == MAIN_ROOTFILE_MEDIA_TYPE:
                 return rootfile
         selected = self._rootfiles[0]
         logger.warning(
@@ -254,7 +242,6 @@ class HwpxPackage:
         elif norm_path == self.VERSION_PATH:
             pending_version = self._parse_version(data)
         self._files[norm_path] = data
-        self._invalidate_caches(norm_path)
         if norm_path == self.MIMETYPE_PATH:
             self._mimetype = mimetype
         elif norm_path == self.CONTAINER_PATH:
@@ -263,6 +250,7 @@ class HwpxPackage:
         elif norm_path == self.VERSION_PATH:
             assert pending_version is not None
             self._version = pending_version
+        self._invalidate_caches(norm_path)
         self._validate_structure()
 
     def delete(self, path: str) -> None:
@@ -274,11 +262,12 @@ class HwpxPackage:
                 "Cannot remove mandatory files ('mimetype', 'container.xml', 'version.xml')."
             )
         del self._files[norm_path]
+        self._invalidate_caches(norm_path)
         self._validate_structure()
 
     @staticmethod
     def _normalize_path(path: str) -> str:
-        return path.replace("\\", "/")
+        return normalize_part_name(path)
 
     def files(self) -> list[str]:
         return sorted(self._files)
@@ -314,13 +303,12 @@ class HwpxPackage:
 
     def manifest_tree(self) -> etree._Element:
         if self._manifest_tree is None:
-            self._manifest_tree = self.get_xml(self.MANIFEST_PATH)
+            self._manifest_tree = self.get_xml(self.main_content.full_path)
         return self._manifest_tree
 
     def _manifest_items(self) -> list[etree._Element]:
         manifest = self.manifest_tree()
-        ns = {"opf": _OPF_NS}
-        return list(manifest.findall("./opf:manifest/opf:item", ns))
+        return list(manifest.findall("./opf:manifest/opf:item", OPF_NS))
 
     @staticmethod
     def _normalized_manifest_value(element: etree._Element) -> str:
@@ -339,52 +327,37 @@ class HwpxPackage:
 
     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
+            relationships = parse_manifest_relationships(
+                self.manifest_tree(),
+                self.main_content.full_path,
+                known_parts=self._files.keys(),
+            )
+            self._spine_cache = list(relationships.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 path and is_section_part_name(path)
             ]
             if not paths:
                 logger.warning("manifest spine에서 section 경로를 찾지 못해 파일명 기반 fallback을 사용합니다.")
                 paths = [
                     name
                     for name in self._files.keys()
-                    if PurePosixPath(name).name.startswith("section")
+                    if is_section_part_name(name)
                 ]
             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 path and is_header_part_name(path)
             ]
             if not paths and self.has_part(self.HEADER_PATH):
                 logger.warning(
@@ -397,14 +370,13 @@ class HwpxPackage:
 
     def master_page_paths(self) -> list[str]:
         if self._master_page_paths_cache is None:
-            from pathlib import PurePosixPath
-
-            paths = [
-                item.attrib.get("href", "")
-                for item in self._manifest_items()
-                if self._manifest_matches(item, "masterpage", "master-page")
-                and item.attrib.get("href")
-            ]
+            paths = list(
+                parse_manifest_relationships(
+                    self.manifest_tree(),
+                    self.main_content.full_path,
+                    known_parts=self._files.keys(),
+                ).master_page_paths
+            )
             if not paths:
                 logger.warning("manifest에서 masterPage를 찾지 못해 파일명 탐색 fallback을 사용합니다.")
                 paths = [
@@ -418,13 +390,13 @@ class HwpxPackage:
 
     def history_paths(self) -> list[str]:
         if self._history_paths_cache is None:
-            from pathlib import PurePosixPath
-
-            paths = [
-                item.attrib.get("href", "")
-                for item in self._manifest_items()
-                if self._manifest_matches(item, "history") and item.attrib.get("href")
-            ]
+            paths = list(
+                parse_manifest_relationships(
+                    self.manifest_tree(),
+                    self.main_content.full_path,
+                    known_parts=self._files.keys(),
+                ).history_paths
+            )
             if not paths:
                 logger.warning("manifest에서 history를 찾지 못해 파일명 탐색 fallback을 사용합니다.")
                 paths = [
@@ -437,13 +409,11 @@ class HwpxPackage:
 
     def version_path(self) -> str | None:
         if not self._version_path_cache_resolved:
-            path: str | None = None
-            for item in self._manifest_items():
-                if self._manifest_matches(item, "version"):
-                    href = item.attrib.get("href", "").strip()
-                    if href:
-                        path = href
-                        break
+            path = parse_manifest_relationships(
+                self.manifest_tree(),
+                self.main_content.full_path,
+                known_parts=self._files.keys(),
+            ).version_path
             if path is None and self.has_part(self.VERSION_PATH):
                 logger.warning(
                     "manifest에서 version 파트를 찾지 못해 기본 경로 fallback을 사용합니다: %s",
@@ -461,8 +431,7 @@ class HwpxPackage:
     def _manifest_element(self) -> etree._Element | None:
         """Return the ``<opf:manifest>`` element."""
         manifest = self.manifest_tree()
-        ns = {"opf": _OPF_NS}
-        return manifest.find("opf:manifest", ns)
+        return manifest.find("opf:manifest", OPF_NS)
 
     def add_manifest_item(
         self,
@@ -475,13 +444,12 @@ class HwpxPackage:
         if manifest_el is None:
             raise HwpxStructureError("Manifest does not contain an <opf:manifest> element.")
 
-        ns = {"opf": _OPF_NS}
-        for existing in manifest_el.findall("opf:item", ns):
+        for existing in manifest_el.findall("opf:item", OPF_NS):
             if existing.get("id") == item_id:
                 return  # already present
 
         new_item = manifest_el.makeelement(
-            f"{{{_OPF_NS}}}item",
+            f"{{{OPF_NS['opf']}}}item",
             {"id": item_id, "href": href, "media-type": media_type},
         )
         manifest_el.append(new_item)
@@ -493,8 +461,7 @@ class HwpxPackage:
         if manifest_el is None:
             return False
 
-        ns = {"opf": _OPF_NS}
-        for existing in manifest_el.findall("opf:item", ns):
+        for existing in manifest_el.findall("opf:item", OPF_NS):
             if existing.get("id") == item_id:
                 manifest_el.remove(existing)
                 self._persist_manifest()
@@ -505,20 +472,18 @@ class HwpxPackage:
         """Write the in-memory manifest tree back to the package."""
         tree = self._manifest_tree
         if tree is not None:
-            self.set_part(self.MANIFEST_PATH, tree)
+            self.set_part(self.main_content.full_path, tree)
 
     def _invalidate_caches(self, changed_path: str) -> None:
-        if changed_path == self.MANIFEST_PATH:
+        if changed_path in {self.CONTAINER_PATH, self.main_content.full_path}:
             self._manifest_tree = None
-            self._spine_cache = None
-            self._section_paths_cache = None
-            self._header_paths_cache = None
-            self._master_page_paths_cache = None
-            self._history_paths_cache = None
-            self._version_path_cache = None
-            self._version_path_cache_resolved = False
-        elif changed_path == self.VERSION_PATH:
-            self._version_path_cache_resolved = False
+        self._spine_cache = None
+        self._section_paths_cache = None
+        self._header_paths_cache = None
+        self._master_page_paths_cache = None
+        self._history_paths_cache = None
+        self._version_path_cache = None
+        self._version_path_cache_resolved = False
 
     def save(
         self,

hwpx/opc/relationships.py

@@ -0,0 +1,227 @@
+"""Helpers for resolving HWPX container and manifest relationships."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from typing import Any, Collection, Iterable
+
+CONTAINER_NAMESPACES = (
+    "urn:oasis:names:tc:opendocument:xmlns:container",
+)
+MAIN_ROOTFILE_MEDIA_TYPE = "application/hwpml-package+xml"
+OPF_NS = {"opf": "http://www.idpf.org/2007/opf/"}
+
+__all__ = [
+    "CONTAINER_NAMESPACES",
+    "MAIN_ROOTFILE_MEDIA_TYPE",
+    "OPF_NS",
+    "ManifestItemRef",
+    "ManifestRelationships",
+    "RootFileRef",
+    "is_header_part_name",
+    "is_section_part_name",
+    "normalize_part_name",
+    "parse_container_rootfiles",
+    "parse_manifest_relationships",
+    "resolve_part_name",
+    "select_main_rootfile",
+]
+
+
+@dataclass(frozen=True)
+class RootFileRef:
+    full_path: str
+    media_type: str | None = None
+
+
+@dataclass(frozen=True)
+class ManifestItemRef:
+    item_id: str | None
+    href: str
+    resolved_path: str
+    media_type: str | None = None
+    properties: str | None = None
+
+
+@dataclass(frozen=True)
+class ManifestRelationships:
+    manifest_path: str
+    items: tuple[ManifestItemRef, ...]
+    spine_paths: tuple[str, ...]
+    dangling_idrefs: tuple[str, ...]
+    header_paths: tuple[str, ...]
+    master_page_paths: tuple[str, ...]
+    history_paths: tuple[str, ...]
+    version_path: str | None
+
+
+def normalize_part_name(path: str) -> str:
+    raw = path.replace("\\", "/").strip()
+    parts: list[str] = []
+    for part in PurePosixPath(raw).parts:
+        if part in {"", ".", "/"}:
+            continue
+        if part == "..":
+            if parts:
+                parts.pop()
+            continue
+        parts.append(part)
+    return "/".join(parts)
+
+
+def resolve_part_name(
+    base_part: str,
+    href: str,
+    *,
+    known_parts: Collection[str] | None = None,
+) -> str:
+    raw_href = href.replace("\\", "/").strip()
+    if not raw_href:
+        return ""
+    if raw_href.startswith("/"):
+        return normalize_part_name(raw_href)
+    base_dir = PurePosixPath(normalize_part_name(base_part)).parent
+    normalized_href = normalize_part_name(raw_href)
+    if known_parts is not None:
+        normalized_parts = {normalize_part_name(part) for part in known_parts}
+        if normalized_href in normalized_parts:
+            return normalized_href
+        relative_candidate = normalize_part_name(str(base_dir / raw_href))
+        if relative_candidate in normalized_parts:
+            return relative_candidate
+    base_dir_name = normalize_part_name(str(base_dir))
+    if base_dir_name and normalized_href.startswith(f"{base_dir_name}/"):
+        return normalized_href
+    return normalize_part_name(str(base_dir / raw_href))
+
+
+def parse_container_rootfiles(container_root: Any) -> tuple[RootFileRef, ...]:
+    rootfiles: list[RootFileRef] = []
+    seen: set[tuple[str, str | None]] = set()
+    candidates = list(container_root.findall(".//rootfile"))
+    for namespace in CONTAINER_NAMESPACES:
+        candidates.extend(container_root.findall(f".//{{{namespace}}}rootfile"))
+
+    for elem in candidates:
+            full_path = (
+                elem.get("full-path")
+                or elem.get("fullPath")
+                or elem.get("full_path")
+            )
+            if not full_path:
+                continue
+            media_type = (
+                elem.get("media-type")
+                or elem.get("mediaType")
+                or elem.get("media_type")
+            )
+            root = RootFileRef(
+                full_path=normalize_part_name(full_path),
+                media_type=media_type,
+            )
+            key = (root.full_path, root.media_type)
+            if key in seen:
+                continue
+            seen.add(key)
+            rootfiles.append(root)
+    return tuple(rootfiles)
+
+
+def select_main_rootfile(rootfiles: Iterable[RootFileRef]) -> tuple[RootFileRef | None, bool]:
+    ordered = list(rootfiles)
+    if not ordered:
+        return None, False
+    for rootfile in ordered:
+        if rootfile.media_type == MAIN_ROOTFILE_MEDIA_TYPE:
+            return rootfile, False
+    return ordered[0], True
+
+
+def is_section_part_name(path: str) -> bool:
+    name = PurePosixPath(path).name.lower()
+    return name.startswith("section") and name.endswith(".xml")
+
+
+def is_header_part_name(path: str) -> bool:
+    name = PurePosixPath(path).name.lower()
+    return name.startswith("header") and name.endswith(".xml")
+
+
+def _manifest_matches(item: ManifestItemRef, *candidates: str) -> bool:
+    haystack = " ".join(
+        part.lower()
+        for part in (
+            item.item_id or "",
+            item.href,
+            item.media_type or "",
+            item.properties or "",
+        )
+        if part
+    )
+    return any(candidate in haystack for candidate in candidates if candidate)
+
+
+def parse_manifest_relationships(
+    manifest_root: Any,
+    manifest_path: str,
+    *,
+    known_parts: Collection[str] | None = None,
+) -> ManifestRelationships:
+    items: list[ManifestItemRef] = []
+    id_to_path: dict[str, str] = {}
+
+    for item in manifest_root.findall(".//opf:item", OPF_NS):
+        href = (item.get("href") or "").strip()
+        if not href:
+            continue
+        resolved_path = resolve_part_name(manifest_path, href, known_parts=known_parts)
+        item_ref = ManifestItemRef(
+            item_id=item.get("id"),
+            href=href,
+            resolved_path=resolved_path,
+            media_type=item.get("media-type"),
+            properties=item.get("properties"),
+        )
+        items.append(item_ref)
+        if item_ref.item_id:
+            id_to_path[item_ref.item_id] = resolved_path
+
+    spine_paths: list[str] = []
+    dangling_idrefs: list[str] = []
+    for itemref in manifest_root.findall(".//opf:itemref", OPF_NS):
+        idref = (itemref.get("idref") or "").strip()
+        if not idref:
+            continue
+        spine_path = id_to_path.get(idref)
+        if spine_path:
+            spine_paths.append(spine_path)
+        else:
+            dangling_idrefs.append(idref)
+
+    header_paths = tuple(path for path in spine_paths if is_header_part_name(path))
+    master_page_paths = tuple(
+        item.resolved_path
+        for item in items
+        if _manifest_matches(item, "masterpage", "master-page")
+    )
+    history_paths = tuple(
+        item.resolved_path
+        for item in items
+        if _manifest_matches(item, "history")
+    )
+    version_path = next(
+        (item.resolved_path for item in items if _manifest_matches(item, "version")),
+        None,
+    )
+
+    return ManifestRelationships(
+        manifest_path=normalize_part_name(manifest_path),
+        items=tuple(items),
+        spine_paths=tuple(spine_paths),
+        dangling_idrefs=tuple(dangling_idrefs),
+        header_paths=header_paths,
+        master_page_paths=master_page_paths,
+        history_paths=history_paths,
+        version_path=version_path,
+    )