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

hwpx/tools/archive_cli.py

@@ -0,0 +1,337 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Sequence
+from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
+
+from lxml import etree
+
+from .package_validator import validate_package
+
+_XML_SUFFIXES = (".xml", ".hpf")
+_PACK_METADATA_NAME = ".hwpx-pack-metadata.json"
+
+__all__ = [
+    "ArchiveEntryInfo",
+    "UnpackResult",
+    "PackResult",
+    "pack_hwpx",
+    "unpack_hwpx",
+    "pack_main",
+    "unpack_main",
+    "main",
+]
+
+
+@dataclass(frozen=True)
+class ArchiveEntryInfo:
+    path: str
+    compress_type: int
+
+
+@dataclass(frozen=True)
+class UnpackResult:
+    output_dir: Path
+    metadata_path: Path
+    entries: tuple[ArchiveEntryInfo, ...]
+
+
+@dataclass(frozen=True)
+class PackResult:
+    output_path: Path
+    entries: tuple[str, ...]
+
+
+def _guard_destructive_target(path: Path) -> None:
+    resolved = path.resolve()
+    if resolved == Path(resolved.anchor):
+        raise ValueError(f"refusing to overwrite filesystem root: {resolved}")
+    if resolved == Path.cwd().resolve():
+        raise ValueError(f"refusing to overwrite current working directory: {resolved}")
+
+
+def _prepare_output_dir(output_dir: Path, *, overwrite: bool) -> None:
+    if output_dir.exists() and not output_dir.is_dir():
+        raise NotADirectoryError(f"output exists and is not a directory: {output_dir}")
+    if output_dir.exists():
+        if any(output_dir.iterdir()):
+            if not overwrite:
+                raise FileExistsError(f"output directory is not empty: {output_dir}")
+            _guard_destructive_target(output_dir)
+            shutil.rmtree(output_dir)
+        else:
+            output_dir.rmdir()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+
+def _prepare_output_path(output_path: Path, *, overwrite: bool) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    if output_path.exists() and not overwrite:
+        raise FileExistsError(f"output file already exists: {output_path}")
+
+
+def _format_xml_bytes(payload: bytes) -> bytes:
+    try:
+        element = etree.fromstring(payload)
+    except etree.XMLSyntaxError:
+        return payload
+    etree.indent(element, space="  ")
+    return etree.tostring(
+        element,
+        pretty_print=True,
+        xml_declaration=True,
+        encoding="UTF-8",
+    )
+
+
+def _iter_file_entries(archive: ZipFile) -> tuple[ArchiveEntryInfo, ...]:
+    entries: list[ArchiveEntryInfo] = []
+    for info in archive.infolist():
+        if info.is_dir():
+            continue
+        entries.append(ArchiveEntryInfo(path=info.filename, compress_type=info.compress_type))
+    return tuple(entries)
+
+
+def _metadata_path(root: Path) -> Path:
+    return root / _PACK_METADATA_NAME
+
+
+def _write_pack_metadata(root: Path, entries: tuple[ArchiveEntryInfo, ...]) -> Path:
+    destination = _metadata_path(root)
+    payload = {
+        "format_version": 1,
+        "entries": [asdict(entry) for entry in entries],
+    }
+    destination.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    return destination
+
+
+def _read_pack_metadata(root: Path) -> tuple[ArchiveEntryInfo, ...]:
+    metadata_file = _metadata_path(root)
+    if not metadata_file.is_file():
+        return ()
+
+    data = json.loads(metadata_file.read_text(encoding="utf-8"))
+    entries: list[ArchiveEntryInfo] = []
+    for entry in data.get("entries", []):
+        path = str(entry.get("path", "")).strip()
+        if not path:
+            continue
+        entries.append(
+            ArchiveEntryInfo(
+                path=path.replace("\\", "/"),
+                compress_type=int(entry.get("compress_type", ZIP_DEFLATED)),
+            )
+        )
+    return tuple(entries)
+
+
+def _discover_files(root: Path) -> set[str]:
+    paths: set[str] = set()
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        rel_path = path.relative_to(root).as_posix()
+        if rel_path == _PACK_METADATA_NAME:
+            continue
+        paths.add(rel_path)
+    return paths
+
+
+def _resolve_write_order(paths: set[str], metadata: tuple[ArchiveEntryInfo, ...]) -> tuple[str, ...]:
+    ordered: list[str] = []
+    seen: set[str] = set()
+
+    if "mimetype" in paths:
+        ordered.append("mimetype")
+        seen.add("mimetype")
+
+    for entry in metadata:
+        if entry.path in paths and entry.path not in seen:
+            ordered.append(entry.path)
+            seen.add(entry.path)
+
+    for path in sorted(paths):
+        if path in seen:
+            continue
+        ordered.append(path)
+        seen.add(path)
+
+    return tuple(ordered)
+
+
+def _summarize_pack_validation(output_path: Path) -> None:
+    report = validate_package(output_path)
+    if report.ok:
+        return
+    summary = "\n".join(f"- {issue}" for issue in report.issues[:10])
+    raise ValueError(f"packed archive failed validation:\n{summary}")
+
+
+def unpack_hwpx(
+    source: str | Path,
+    output_dir: str | Path,
+    *,
+    overwrite: bool = False,
+    pretty_xml: bool = True,
+) -> UnpackResult:
+    source_path = Path(source)
+    if not source_path.is_file():
+        raise FileNotFoundError(f"input file not found: {source_path}")
+
+    destination = Path(output_dir)
+    _prepare_output_dir(destination, overwrite=overwrite)
+
+    with ZipFile(source_path, "r") as archive:
+        entries = _iter_file_entries(archive)
+        for entry in entries:
+            data = archive.read(entry.path)
+            if pretty_xml and entry.path.endswith(_XML_SUFFIXES):
+                data = _format_xml_bytes(data)
+            target = destination / entry.path
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(data)
+
+    metadata_path = _write_pack_metadata(destination, entries)
+    return UnpackResult(output_dir=destination, metadata_path=metadata_path, entries=entries)
+
+
+def pack_hwpx(
+    input_dir: str | Path,
+    output_path: str | Path,
+    *,
+    overwrite: bool = False,
+) -> PackResult:
+    root = Path(input_dir)
+    if not root.is_dir():
+        raise FileNotFoundError(f"input directory not found: {root}")
+
+    destination = Path(output_path)
+    _prepare_output_path(destination, overwrite=overwrite)
+
+    files = _discover_files(root)
+    if "mimetype" not in files:
+        raise FileNotFoundError(f"missing required 'mimetype' file in {root}")
+
+    metadata = _read_pack_metadata(root)
+    compress_types = {entry.path: entry.compress_type for entry in metadata}
+    ordered_paths = _resolve_write_order(files, metadata)
+
+    fd, tmp_name = tempfile.mkstemp(dir=str(destination.parent), suffix=".hwpx.tmp")
+    os.close(fd)
+    tmp_path = Path(tmp_name)
+    try:
+        with ZipFile(tmp_path, "w", ZIP_DEFLATED) as archive:
+            archive.write(root / "mimetype", "mimetype", compress_type=ZIP_STORED)
+            for rel_path in ordered_paths:
+                if rel_path == "mimetype":
+                    continue
+                compress_type = compress_types.get(rel_path, ZIP_DEFLATED)
+                if compress_type != ZIP_STORED:
+                    compress_type = ZIP_DEFLATED
+                archive.write(root / rel_path, rel_path, compress_type=compress_type)
+
+        _summarize_pack_validation(tmp_path)
+        os.replace(tmp_path, destination)
+    except BaseException:
+        try:
+            tmp_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise
+
+    return PackResult(output_path=destination, entries=ordered_paths)
+
+
+def unpack_main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Unpack an HWPX file into a directory")
+    parser.add_argument("input", help="Input .hwpx path")
+    parser.add_argument("output", help="Output directory")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Allow deleting an existing non-empty output directory",
+    )
+    parser.add_argument(
+        "--no-pretty-xml",
+        action="store_true",
+        help="Keep XML payloads in their original byte formatting",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        result = unpack_hwpx(
+            args.input,
+            args.output,
+            overwrite=args.force,
+            pretty_xml=not args.no_pretty_xml,
+        )
+    except Exception as exc:
+        print(f"ERROR: {exc}")
+        return 1
+
+    print(f"Unpacked {args.input} -> {result.output_dir}")
+    print(f"Recorded archive metadata at {result.metadata_path}")
+    return 0
+
+
+def pack_main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Pack a directory into an HWPX archive")
+    parser.add_argument("input", help="Input directory")
+    parser.add_argument("output", help="Output .hwpx path")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Allow replacing an existing output file",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        result = pack_hwpx(args.input, args.output, overwrite=args.force)
+    except Exception as exc:
+        print(f"ERROR: {exc}")
+        return 1
+
+    print(f"Packed {args.input} -> {result.output_path}")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="HWPX archive utility helpers")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    unpack_parser = subparsers.add_parser("unpack", help="Unpack an HWPX file")
+    unpack_parser.add_argument("input")
+    unpack_parser.add_argument("output")
+    unpack_parser.add_argument("--force", action="store_true")
+    unpack_parser.add_argument("--no-pretty-xml", action="store_true")
+
+    pack_parser = subparsers.add_parser("pack", help="Pack a directory into HWPX")
+    pack_parser.add_argument("input")
+    pack_parser.add_argument("output")
+    pack_parser.add_argument("--force", action="store_true")
+
+    args = parser.parse_args(argv)
+    if args.command == "unpack":
+        forward = [args.input, args.output]
+        if args.force:
+            forward.append("--force")
+        if args.no_pretty_xml:
+            forward.append("--no-pretty-xml")
+        return unpack_main(forward)
+
+    forward = [args.input, args.output]
+    if args.force:
+        forward.append("--force")
+    return pack_main(forward)
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI convenience
+    raise SystemExit(main())

hwpx/tools/package_validator.py

@@ -68,13 +68,15 @@ def _parse_xml(payload: bytes) -> ET.Element:
 def _container_rootfiles(container_root: ET.Element) -> list[str]:
     paths: list[str] = []
     for namespace in CONTAINER_NS.values():
-        paths.extend(
-            elem.get("full-path")
-            or elem.get("fullPath")
-            or elem.get("full_path")
-            for elem in container_root.findall(f".//{{{namespace}}}rootfile")
-        )
-    return [path for path in paths if path]
+        for elem in container_root.findall(f".//{{{namespace}}}rootfile"):
+            path = (
+                elem.get("full-path")
+                or elem.get("fullPath")
+                or elem.get("full_path")
+            )
+            if path:
+                paths.append(path)
+    return paths
 
 
 def _manifest_hrefs(manifest_root: ET.Element) -> set[str]:

hwpx/tools/page_guard.py

@@ -1,3 +1,9 @@
+"""Proxy checks for layout drift between a reference and an output HWPX.
+
+This module does not calculate rendered page counts. It compares structural and
+textual metrics that often correlate with page-layout drift.
+"""
+
 from __future__ import annotations
 
 import argparse
@@ -16,6 +22,22 @@ NS = {
     "opf": "http://www.idpf.org/2007/opf/",
 }
 
+_SHAPE_TAGS = {
+    "line",
+    "rect",
+    "ellipse",
+    "arc",
+    "polygon",
+    "curve",
+    "connectLine",
+    "textart",
+    "pic",
+    "compose",
+    "equation",
+    "ole",
+    "container",
+}
+
 __all__ = [
     "DocumentMetrics",
     "collect_metrics",
@@ -31,7 +53,11 @@ class DocumentMetrics:
     page_break_count: int
     column_break_count: int
     table_count: int
+    shape_count: int
+    control_count: int
     table_shapes: list[tuple[str, str, str, str, str, str]]
+    shape_types: list[tuple[str, int]]
+    control_types: list[tuple[str, int]]
     text_char_total: int
     text_char_total_nospace: int
     paragraph_text_lengths: list[int]
@@ -66,6 +92,12 @@ def _text_of_t_node(node: etree._Element) -> str:
     return "".join(node.itertext())
 
 
+def _local_name(tag: str) -> str:
+    if "}" in tag:
+        return tag.split("}", 1)[1]
+    return tag
+
+
 def _iter_section_roots(source: str | Path | bytes | BinaryIO) -> Iterable[etree._Element]:
     if isinstance(source, bytes):
         archive = ZipFile(io.BytesIO(source), "r")
@@ -85,6 +117,8 @@ def collect_metrics(source: str | Path | bytes | BinaryIO) -> DocumentMetrics:
     paragraphs: list[etree._Element] = []
     tables: list[etree._Element] = []
     table_shapes: list[tuple[str, str, str, str, str, str]] = []
+    shape_types: dict[str, int] = {}
+    control_types: dict[str, int] = {}
     paragraph_text_lengths: list[int] = []
     text_char_total = 0
     text_char_total_nospace = 0
@@ -100,6 +134,19 @@ def collect_metrics(source: str | Path | bytes | BinaryIO) -> DocumentMetrics:
         section_tables = root.xpath(".//hp:tbl", namespaces=NS)
         tables.extend(section_tables)
 
+        for element in root.iter():
+            name = _local_name(element.tag)
+            if name in _SHAPE_TAGS:
+                shape_types[name] = shape_types.get(name, 0) + 1
+            if name == "ctrl":
+                control_counted = False
+                for child in element:
+                    child_name = _local_name(child.tag)
+                    control_types[child_name] = control_types.get(child_name, 0) + 1
+                    control_counted = True
+                if not control_counted:
+                    control_types["ctrl"] = control_types.get("ctrl", 0) + 1
+
         for table in section_tables:
             size = table.find("hp:sz", namespaces=NS)
             table_shapes.append(
@@ -132,7 +179,11 @@ def collect_metrics(source: str | Path | bytes | BinaryIO) -> DocumentMetrics:
         page_break_count=page_break_count,
         column_break_count=column_break_count,
         table_count=len(tables),
+        shape_count=sum(shape_types.values()),
+        control_count=sum(control_types.values()),
         table_shapes=table_shapes,
+        shape_types=sorted(shape_types.items()),
+        control_types=sorted(control_types.items()),
         text_char_total=text_char_total,
         text_char_total_nospace=text_char_total_nospace,
         paragraph_text_lengths=paragraph_text_lengths,
@@ -173,8 +224,18 @@ def compare_metrics(
         )
     if reference.table_count != output.table_count:
         errors.append(f"table count mismatch: ref={reference.table_count}, out={output.table_count}")
+    if reference.shape_count != output.shape_count:
+        errors.append(f"shape count mismatch: ref={reference.shape_count}, out={output.shape_count}")
+    if reference.control_count != output.control_count:
+        errors.append(
+            f"control count mismatch: ref={reference.control_count}, out={output.control_count}"
+        )
     if reference.table_shapes != output.table_shapes:
         errors.append("table shape mismatch (rowCnt/colCnt/width/height/repeatHeader/pageBreak)")
+    if reference.shape_types != output.shape_types:
+        errors.append("shape type histogram mismatch")
+    if reference.control_types != output.control_types:
+        errors.append("control type histogram mismatch")
 
     text_delta = _ratio_delta(reference.text_char_total_nospace, output.text_char_total_nospace)
     if text_delta > max_text_delta_ratio:
@@ -202,7 +263,9 @@ def compare_metrics(
 
 
 def main(argv: Sequence[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="Reference-vs-output HWPX page drift guard")
+    parser = argparse.ArgumentParser(
+        description="Reference-vs-output HWPX layout-drift proxy checker"
+    )
     parser.add_argument("--reference", "-r", required=True, help="Reference HWPX path")
     parser.add_argument("--output", "-o", required=True, help="Output HWPX path")
     parser.add_argument("--max-text-delta-ratio", type=float, default=0.15)

hwpx/tools/template_analyzer.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Sequence
+from xml.etree import ElementTree as ET
+
+from ..opc.package import HwpxPackage
+from .page_guard import DocumentMetrics, collect_metrics
+
+_HH_NS = "http://www.hancom.co.kr/hwpml/2011/head"
+_HH = {"hh": _HH_NS}
+
+__all__ = [
+    "HeaderSummary",
+    "TemplateAnalysis",
+    "analyze_template",
+    "extract_template_parts",
+    "main",
+]
+
+
+@dataclass(frozen=True)
+class HeaderSummary:
+    font_count: int
+    char_pr_count: int
+    para_pr_count: int
+    border_fill_count: int
+
+
+@dataclass(frozen=True)
+class TemplateAnalysis:
+    source_name: str
+    part_names: tuple[str, ...]
+    rootfiles: tuple[str, ...]
+    manifest_path: str
+    header_paths: tuple[str, ...]
+    section_paths: tuple[str, ...]
+    version_path: str | None
+    header_summary: HeaderSummary
+    proxy_metrics: DocumentMetrics
+
+
+def _summarize_header(element: ET.Element | None) -> HeaderSummary:
+    if element is None:
+        return HeaderSummary(font_count=0, char_pr_count=0, para_pr_count=0, border_fill_count=0)
+
+    font_count = len(element.findall(".//hh:fontface/hh:font", _HH))
+    char_pr_count = len(element.findall(".//hh:charPr", _HH))
+    para_pr_count = len(element.findall(".//hh:paraPr", _HH))
+    border_fill_count = len(element.findall(".//hh:borderFill", _HH))
+    return HeaderSummary(
+        font_count=font_count,
+        char_pr_count=char_pr_count,
+        para_pr_count=para_pr_count,
+        border_fill_count=border_fill_count,
+    )
+
+
+def analyze_template(source: str | Path) -> TemplateAnalysis:
+    source_path = Path(source)
+    package = HwpxPackage.open(source_path)
+
+    header_paths = tuple(package.header_paths())
+    header_xml = package.get_xml(header_paths[0]) if header_paths else None
+    manifest_path = package.main_content.full_path
+    version_path = package.version_path()
+
+    return TemplateAnalysis(
+        source_name=source_path.name,
+        part_names=tuple(package.part_names()),
+        rootfiles=tuple(rootfile.full_path for rootfile in package.iter_rootfiles()),
+        manifest_path=manifest_path,
+        header_paths=header_paths,
+        section_paths=tuple(package.section_paths()),
+        version_path=version_path,
+        header_summary=_summarize_header(header_xml),
+        proxy_metrics=collect_metrics(source_path),
+    )
+
+
+def _write_part(package: HwpxPackage, part_name: str, destination: Path) -> Path:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_bytes(package.get_part(part_name))
+    return destination
+
+
+def extract_template_parts(
+    source: str | Path,
+    *,
+    extract_dir: str | Path | None = None,
+    extract_header: str | Path | None = None,
+    extract_section: str | Path | None = None,
+    extract_section_dir: str | Path | None = None,
+) -> tuple[Path, ...]:
+    source_path = Path(source)
+    package = HwpxPackage.open(source_path)
+    written: list[Path] = []
+
+    if extract_dir is not None:
+        root = Path(extract_dir)
+        root.mkdir(parents=True, exist_ok=True)
+        written.append(_write_part(package, package.main_content.full_path, root / package.main_content.full_path))
+        for part_name in package.header_paths():
+            written.append(_write_part(package, part_name, root / part_name))
+        for part_name in package.section_paths():
+            written.append(_write_part(package, part_name, root / part_name))
+        version_path = package.version_path()
+        if version_path and package.has_part(version_path):
+            written.append(_write_part(package, version_path, root / version_path))
+        if package.has_part(package.CONTAINER_PATH):
+            written.append(_write_part(package, package.CONTAINER_PATH, root / package.CONTAINER_PATH))
+
+    if extract_header is not None:
+        header_paths = package.header_paths()
+        if not header_paths:
+            raise FileNotFoundError("package does not contain a header part")
+        written.append(_write_part(package, header_paths[0], Path(extract_header)))
+
+    if extract_section is not None:
+        section_paths = package.section_paths()
+        if not section_paths:
+            raise FileNotFoundError("package does not contain a section part")
+        written.append(_write_part(package, section_paths[0], Path(extract_section)))
+
+    if extract_section_dir is not None:
+        section_root = Path(extract_section_dir)
+        section_root.mkdir(parents=True, exist_ok=True)
+        for part_name in package.section_paths():
+            written.append(_write_part(package, part_name, section_root / Path(part_name).name))
+
+    return tuple(written)
+
+
+def _print_summary(analysis: TemplateAnalysis) -> None:
+    metrics = analysis.proxy_metrics
+    print(f"source: {analysis.source_name}")
+    print(f"manifest: {analysis.manifest_path}")
+    print(f"rootfiles: {', '.join(analysis.rootfiles) or '(none)'}")
+    print(f"headers: {', '.join(analysis.header_paths) or '(none)'}")
+    print(f"sections: {', '.join(analysis.section_paths) or '(none)'}")
+    if analysis.version_path:
+        print(f"version part: {analysis.version_path}")
+    print(
+        "header styles: "
+        f"fonts={analysis.header_summary.font_count}, "
+        f"charPr={analysis.header_summary.char_pr_count}, "
+        f"paraPr={analysis.header_summary.para_pr_count}, "
+        f"borderFill={analysis.header_summary.border_fill_count}"
+    )
+    print(
+        "layout-drift proxy: "
+        f"paragraphs={metrics.paragraph_count}, "
+        f"tables={metrics.table_count}, "
+        f"shapes={metrics.shape_count}, "
+        f"controls={metrics.control_count}, "
+        f"pageBreaks={metrics.page_break_count}, "
+        f"columnBreaks={metrics.column_break_count}"
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Analyze a reference HWPX template for template-preserving workflows"
+    )
+    parser.add_argument("input", help="Input HWPX path")
+    parser.add_argument("--json", action="store_true", help="Print machine-readable JSON summary")
+    parser.add_argument("--output-json", help="Write the JSON summary to a file")
+    parser.add_argument(
+        "--extract-dir",
+        help="Copy manifest, header, sections, version, and container.xml into a directory",
+    )
+    parser.add_argument("--extract-header", help="Copy the first header.xml part to a path")
+    parser.add_argument("--extract-section", help="Copy the first section XML part to a path")
+    parser.add_argument(
+        "--extract-section-dir",
+        help="Backward-compatible alias that copies section*.xml files into a directory",
+    )
+    args = parser.parse_args(argv)
+
+    input_path = Path(args.input)
+    if not input_path.is_file():
+        print(f"ERROR: file not found: {input_path}")
+        return 1
+
+    try:
+        analysis = analyze_template(input_path)
+        written = extract_template_parts(
+            input_path,
+            extract_dir=args.extract_dir,
+            extract_header=args.extract_header,
+            extract_section=args.extract_section,
+            extract_section_dir=args.extract_section_dir,
+        )
+    except Exception as exc:
+        print(f"ERROR: {exc}")
+        return 1
+
+    if args.json or args.output_json:
+        payload = json.dumps(asdict(analysis), ensure_ascii=False, indent=2)
+        if args.json:
+            print(payload)
+        if args.output_json:
+            output_path = Path(args.output_json)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(payload, encoding="utf-8")
+    else:
+        _print_summary(analysis)
+
+    for path in written:
+        print(f"extracted: {path}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI convenience
+    raise SystemExit(main())

{python_hwpx-2.6.dist-info → python_hwpx-2.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 2.6
+Version: 2.7.1
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License: Non-Commercial License
@@ -165,7 +165,8 @@ doc.save_to_path("결과물.hwpx")
 | 🔎 **객체 검색** | 태그/속성/XPath | 특정 요소 탐색, 주석 이터레이터 |
 | 🎨 **스타일 치환** | 서식 기반 필터 | 색상/밑줄/charPrIDRef 기반 Run 검색 및 교체 |
 | 📤 **내보내기** | 텍스트/HTML/Markdown | 문서 변환 출력 |
-| ✅ **유효성 검사** | XSD 스키마 | CLI(`hwpx-validate`) 및 API |
+| ✅ **유효성 검사** | XSD + 패키지 구조 | CLI(`hwpx-validate`, `hwpx-validate-package`) 및 API |
+| 🧰 **워크플로 도구** | unpack/pack/template analyze/page guard | 템플릿 보존형 XML-first 작업 보조 |
 | 🏗️ **저수준 XML** | 데이터클래스 매핑 | OWPML 스키마 ↔ Python 객체 직접 조작 |
 | 🔄 **네임스페이스 호환** | 자동 정규화 | HWPML 2016 → 2011 자동 변환 |
 
@@ -262,10 +263,15 @@ python-hwpx
 │   ├── body.py          #   타입이 지정된 본문 모델
 │   └── common.py        #   범용 XML ↔ 데이터클래스
 ├── hwpx.tools
+│   ├── archive_cli      #   unpack/pack CLI 및 재패킹 메타데이터
 │   ├── text_extractor   #   텍스트 추출 파이프라인
+│   ├── text_extract_cli #   텍스트 추출 CLI
 │   ├── object_finder    #   객체 탐색 유틸리티
 │   ├── exporter         #   텍스트/HTML/Markdown 내보내기
-│   └── validator        #   스키마 유효성 검사 (hwpx-validate CLI)
+│   ├── validator        #   스키마 유효성 검사 (hwpx-validate CLI)
+│   ├── package_validator#   ZIP/OPC/HWPX 구조 검사
+│   ├── page_guard       #   layout-drift proxy
+│   └── template_analyzer#   레퍼런스 문서 분석/추출
 └── hwpx.templates       # 내장 빈 문서 템플릿
 ```
 
@@ -274,8 +280,26 @@ python-hwpx
 ```bash
 # HWPX 문서 스키마 유효성 검사
 hwpx-validate 문서.hwpx
+
+# ZIP/OPC/HWPX 패키지 구조 검사
+hwpx-validate-package 문서.hwpx
+
+# HWPX 풀기 / 다시 묶기
+hwpx-unpack 문서.hwpx ./unpacked
+hwpx-pack ./unpacked ./repacked.hwpx
+
+# 레퍼런스 템플릿 분석과 파트 추출
+hwpx-analyze-template 문서.hwpx --extract-dir ./template-parts --json
+
+# plain / markdown 텍스트 추출
+hwpx-text-extract 문서.hwpx --format markdown --output 문서.md
+
+# 레이아웃 드리프트 프록시 비교
+hwpx-page-guard --reference 원본.hwpx --output 결과.hwpx
 ```
 
+`hwpx-page-guard`는 렌더된 실제 쪽수를 계산하지 않습니다. 대신 단락 수, 표 수, shape/control 수, 명시적 page/column break, 텍스트 길이 통계를 비교해 레이아웃 드리프트 위험을 탐지하는 프록시 도구입니다.
+
 ## 문서
 
 | | |

{python_hwpx-2.6.dist-info → python_hwpx-2.7.1.dist-info}/RECORD

@@ -21,18 +21,20 @@ hwpx/oxml/section.py,sha256=WwxZ6PWPeMrj2L9mz4JlqFGXwd7E7qAuSBuM5dgRjZk,199
 hwpx/oxml/table.py,sha256=pdO2TTAcbEC6Z4cnaOnB-bcmuZ1KVado7J3RiY_zOfE,193
 hwpx/oxml/utils.py,sha256=to0yytS7vtLSvWl-dQyegT6MWClMK55b1Sp1uagEkI4,2591
 hwpx/tools/__init__.py,sha256=e1OaIVdbkmjTvLOzQ7qVRfuuQ1611225pNZByB2ln9w,1270
+hwpx/tools/archive_cli.py,sha256=ih14UmayJTpOw14cRBmrPKbfMFNFfoyiHzFQ2CYt_sE,10419
 hwpx/tools/exporter.py,sha256=GcbNtV4rIWOJv5nBcgdX0yfkXQa-xQhfrCzXWgaNbTE,8862
 hwpx/tools/object_finder.py,sha256=vbZ8FuIpGF-2vpbWDeZWi4UgZ2-3PK_ddQCs0oq1dRw,13440
-hwpx/tools/package_validator.py,sha256=ZixhRjv_RYwBshk3NEJXyakRVsN7hM4WI47euvWFETU,7379
-hwpx/tools/page_guard.py,sha256=nholL2cMv249yieVBWGqW3WHqkFR1qVutBVz59V_kYo,8351
+hwpx/tools/package_validator.py,sha256=JpXLcWxM0orD38G1v_eeWtuScDXtGqT7Tgh6GR-qOto,7420
+hwpx/tools/page_guard.py,sha256=AaKDWet8QHduoB8smIUgBf8muYBuYenj-xAIv1uFbVA,10454
+hwpx/tools/template_analyzer.py,sha256=QCqZRMxLFMTwoyYAzEmtzc8B4AwtqTMHV2hBCWXLKtQ,7919
 hwpx/tools/text_extract_cli.py,sha256=pIBMIFuFX10IEegw7fQ3gtUbQyjNgbAUYkQWh2S3aQs,2150
 hwpx/tools/text_extractor.py,sha256=r2OJRgDOiR6n14hXRcvkYuSFtEHpAV6jasHv-ZLHx1Y,24238
 hwpx/tools/validator.py,sha256=KThqBQKKQfZkuLMGtzONbPkzy877-2FgT22FHPmt_gI,5979
 hwpx/tools/_schemas/header.xsd,sha256=mJXuFMuHGT1JnFFaluUpYUglwjMCNlfbFCRVM26eHXE,664
 hwpx/tools/_schemas/section.xsd,sha256=MgvavVHG05RDfUnVPxVU10H4FQOja5ON04_m9Uk_m7E,522
-python_hwpx-2.6.dist-info/licenses/LICENSE,sha256=3F1-JUTcmjmxMpHGeB77ZzaSdhms3h8p1DBBa3lvV08,1609
-python_hwpx-2.6.dist-info/METADATA,sha256=9LDnFWuCNTEqQpF_WMyH7Mm3Ah7uYYnGazGI3C8pE20,12974
-python_hwpx-2.6.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
-python_hwpx-2.6.dist-info/entry_points.txt,sha256=KvwTIdfB-3OL8BEAmoiICdfqqndolqiET-zBEgbIyiM,216
-python_hwpx-2.6.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-2.6.dist-info/RECORD,,
+python_hwpx-2.7.1.dist-info/licenses/LICENSE,sha256=3F1-JUTcmjmxMpHGeB77ZzaSdhms3h8p1DBBa3lvV08,1609
+python_hwpx-2.7.1.dist-info/METADATA,sha256=o8tMskFmig6pQFTG92dD5vXNKoGQLps3tW3OfkPZGGk,14238
+python_hwpx-2.7.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+python_hwpx-2.7.1.dist-info/entry_points.txt,sha256=zKneV9VceQKwbJUo-mUUbwRmQjNyNSzrv44XuMhsaUU,368
+python_hwpx-2.7.1.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-2.7.1.dist-info/RECORD,,

{python_hwpx-2.6.dist-info → python_hwpx-2.7.1.dist-info}/entry_points.txt

@@ -1,5 +1,8 @@
 [console_scripts]
+hwpx-analyze-template = hwpx.tools.template_analyzer:main
+hwpx-pack = hwpx.tools.archive_cli:pack_main
 hwpx-page-guard = hwpx.tools.page_guard:main
 hwpx-text-extract = hwpx.tools.text_extract_cli:main
+hwpx-unpack = hwpx.tools.archive_cli:unpack_main
 hwpx-validate = hwpx.tools.validator:main
 hwpx-validate-package = hwpx.tools.package_validator:main