pywpdoc 0.44.0rc1__py3-none-any.whl

pywpdoc/__init__.py

@@ -0,0 +1,27 @@
+"""PyWPDoc: Python word-processing document automation API.
+
+Use ``pywpdoc.Document`` for the high-level format-neutral API.
+Use ``pywpdoc.hwpx`` or ``pywpdoc.docx`` for backend-specific APIs.
+"""
+from .document import Document, UnifiedDocument
+from .core import (
+    Length, Pt, Mm, HwpUnit, Cm, Inches,
+    WD_CELL_VERTICAL_ALIGNMENT, WD_ALIGN_VERTICAL,
+    WD_ORIENTATION, WD_ORIENT, WD_STYLE_TYPE,
+    DocumentError, DocumentValueError, DocumentStateError, DocumentUnsupportedError,
+)
+
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError, version as _pkg_version
+try:
+    __version__ = _pkg_version("pywpdoc")
+except _PackageNotFoundError:
+    __version__ = "0+unknown"  # direct source import without installed package metadata
+
+__all__ = [
+    "Document", "UnifiedDocument",
+    "Length", "Pt", "Mm", "HwpUnit", "Cm", "Inches",
+    "WD_CELL_VERTICAL_ALIGNMENT", "WD_ALIGN_VERTICAL",
+    "WD_ORIENTATION", "WD_ORIENT", "WD_STYLE_TYPE",
+    "DocumentError", "DocumentValueError", "DocumentStateError", "DocumentUnsupportedError",
+    "__version__",
+]

pywpdoc/_engine/__init__.py

@@ -0,0 +1,26 @@
+from .document import Document
+from .reverse import reverse_hwpx
+from .model import Paragraph, Run, Table, Row, Column, Cell, Shape, Rectangle, Picture, ElementModel, Section, PageSetup, HeaderFooter, Note, Hyperlink
+from .styles import Styles, Style, Font, ParagraphFormat, CellBorder, TabStop, TabStops
+from .shared import Length, Pt, Mm, Cm, Inches, HwpUnit
+from .enum.text import WD_BREAK, WD_BREAK_TYPE, WD_TAB_ALIGNMENT, WD_TAB_LEADER
+from .enum.table import WD_CELL_VERTICAL_ALIGNMENT, WD_ALIGN_VERTICAL
+from .enum.section import WD_ORIENTATION, WD_ORIENT
+from .enum.style import WD_STYLE_TYPE
+from .metadata import CoreProperties, Settings, CaretPosition
+from .validation import ValidationIssue, ValidationReport, validate_hwpx_file
+from .errors import HwpxError, HwpxValueError, HwpxStateError, HwpxUnsupportedError, HwpxValidationError
+
+__all__ = [
+    "Document", "reverse_hwpx",
+    "Paragraph", "Run", "Table", "Row", "Column", "Cell", "Shape", "Rectangle", "Picture", "ElementModel",
+    "Section", "PageSetup", "HeaderFooter", "Note", "Hyperlink",
+    "Styles", "Style", "Font", "ParagraphFormat", "CellBorder", "TabStop", "TabStops",
+    "Length", "Pt", "Mm", "Cm", "Inches", "HwpUnit",
+    "WD_BREAK", "WD_BREAK_TYPE", "WD_TAB_ALIGNMENT", "WD_TAB_LEADER",
+    "WD_CELL_VERTICAL_ALIGNMENT", "WD_ALIGN_VERTICAL", "WD_ORIENTATION", "WD_ORIENT",
+    "WD_STYLE_TYPE",
+    "CoreProperties", "Settings", "CaretPosition",
+    "ValidationIssue", "ValidationReport", "validate_hwpx_file",
+    "HwpxError", "HwpxValueError", "HwpxStateError", "HwpxUnsupportedError", "HwpxValidationError",
+]

pywpdoc/_engine/_hwpx_section.py

@@ -0,0 +1,86 @@
+"""Low-level HWPX section/story authoring policy.
+
+This module belongs to the native HWPX engine, below the standalone ``hwpx``
+backend wrappers.  It intentionally knows nothing about DOCX or the common
+facade.
+"""
+from __future__ import annotations
+from typing import Any
+
+
+
+def invalidate_layout_cache(section: Any) -> int:
+    """Drop stale paragraph line-layout caches for a section.
+
+    Hancom persists ``hp:linesegarray`` as a derived layout cache.  Page size,
+    margin, orientation, and header/footer-area changes can invalidate every
+    cached line position in the section.  Keeping those coordinates after a
+    geometry mutation can make Hancom lay out visible content against the old
+    page box, so native geometry setters clear them instead of trying to patch
+    opaque cached coordinates.
+    """
+    from .model import local_name
+
+    removed = 0
+    for node in section.element_model.iter():
+        if local_name(node.tag) != "p":
+            continue
+        kept = []
+        for child in node.children:
+            if local_name(child.tag).lower() == "linesegarray":
+                removed += 1
+            else:
+                kept.append(child)
+        if len(kept) != len(node.children):
+            node.children[:] = kept
+    return removed
+
+def content_width(section: Any) -> int:
+    """Return the section's writable horizontal extent in HWPUNIT."""
+    page = section.page_setup
+    return max(int(page.width) - int(page.left_margin) - int(page.right_margin), 0)
+
+
+def story_style_refs(section: Any, kind: str) -> tuple[str, str, str]:
+    """Return native style/paragraph/character refs for a story's first line.
+
+    The bundled Hancom skeleton has a dedicated ``Header``/``머리말`` style
+    but no independent Footer style.  Hancom uses the story-specific style as
+    the best native baseline for authored header/footer text; later paragraphs
+    added explicitly keep ordinary paragraph defaults unless a style is given.
+    """
+    document = section.document
+    if document is not None:
+        style = document.styles.get("Header") or document.styles.get("머리말")
+        if style is not None:
+            return (str(style.id), str(style.para_pr_id_ref or "0"), str(style.char_pr_id_ref or "0"))
+    return ("0", "0", "0")
+
+
+def story_sublist_attrs(section: Any, kind: str) -> list[tuple[str, str]]:
+    from .authoring import sublist_attrs
+
+    attrs = dict(sublist_attrs())
+    attrs["vertAlign"] = "TOP" if kind == "header" else "BOTTOM"
+    attrs["textWidth"] = str(content_width(section))
+    page = section.page_setup
+    attrs["textHeight"] = str(int(page.header_distance if kind == "header" else page.footer_distance))
+    return list(attrs.items())
+
+
+def simple_story(section: Any, kind: str, page_type: str, text: str):
+    from .authoring import object_id, paragraph_attrs
+    from .model import ElementModel, HP
+
+    style_ref, para_ref, char_ref = story_style_refs(section, kind)
+    story = ElementModel(HP + kind, attrs=[("id", object_id()), ("applyPageType", page_type)])
+    sub = ElementModel(HP + "subList", attrs=story_sublist_attrs(section, kind))
+    if "\n" in text:
+        sub.set("textHeight", "0")
+    p = ElementModel(HP + "p", attrs=paragraph_attrs(para_pr_id_ref=para_ref, style_id_ref=style_ref))
+    run = ElementModel(HP + "run", attrs=[("charPrIDRef", char_ref)])
+    run.children.append(ElementModel(HP + "t", text=text))
+    p.children.append(run)
+    sub.children.append(p)
+    story.children.append(sub)
+    return story

pywpdoc/_engine/_hwpx_story.py

@@ -0,0 +1,35 @@
+"""Low-level HWPX header/footer content policy.
+
+Kept below the standalone HWPX backend so ``hwpx.story`` can remain a thin
+object adapter.  No imports from ``common`` or ``docx`` are allowed here.
+"""
+from __future__ import annotations
+from typing import Any
+
+
+def paragraph_text(story: Any) -> str:
+    """Return block paragraph text without leaking nested-table cell text."""
+    texts: list[str] = []
+    for item in story.iter_inner_content():
+        if type(item).__name__ == "Paragraph":
+            texts.append(item.text)
+    return "\n".join(texts)
+
+
+
+def enable_auto_story_height(story: Any) -> None:
+    """Let Hancom size a rich header/footer story from its block content.
+
+    ``hp:subList/@textHeight`` is the story text-area height.  A fixed value
+    equal to the header/footer distance is only suitable for a simple single
+    line story.  Once additional paragraphs, tables, fields, or runs are
+    authored, keeping that fixed box can make content overflow into the body.
+    HWPX ParaList containers use ``0`` for content-sized text areas, so rich
+    authored stories switch to that native auto-size form.
+    """
+    sub = story._ensure_sublist()
+    sub.set("textHeight", "0")
+
+def normalize_story_table(table: Any) -> None:
+    from ._hwpx_table import normalize_authored_table
+    normalize_authored_table(table)

pywpdoc/_engine/_hwpx_table.py

@@ -0,0 +1,37 @@
+"""Native HWPX table authoring defaults shared by HWPX entry points only."""
+from __future__ import annotations
+from typing import Any
+
+
+def normalize_authored_table(table: Any) -> None:
+    """Apply the HWPX backend's authored-cell defaults to *table*."""
+    from .core import defaults
+    from .core.units import Mm
+    from .model import local_name
+
+    margin = next((c for c in table.element_model.children if local_name(c.tag) == "inMargin"), None)
+    if margin is not None:
+        margin.set("left", str(int(Mm(defaults.CELL_MARGIN_LEFT_MM))))
+        margin.set("right", str(int(Mm(defaults.CELL_MARGIN_RIGHT_MM))))
+        margin.set("top", str(int(Mm(defaults.CELL_MARGIN_TOP_MM))))
+        margin.set("bottom", str(int(Mm(defaults.CELL_MARGIN_BOTTOM_MM))))
+    for row in table.rows:
+        for cell in row.physical_cells:
+            cell.vertical_alignment = defaults.DEFAULT_CELL_VERTICAL_ALIGNMENT
+
+
+def fit_nested_table(table: Any, cell: Any, cols: int) -> None:
+    if cols <= 0:
+        return
+    from .authoring import distribute_size
+    from .core import defaults
+    from .core.units import Mm
+
+    target = max(
+        int(cell.width)
+        - int(Mm(defaults.CELL_MARGIN_LEFT_MM))
+        - int(Mm(defaults.CELL_MARGIN_RIGHT_MM)),
+        0,
+    )
+    for index, width in enumerate(distribute_size(target, cols)):
+        table.columns[index].width = width

pywpdoc/_engine/authoring.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import random
+import zipfile
+from typing import TYPE_CHECKING
+
+from .model import ElementModel, HP, HC, local_name
+from .package import PackageEntryInfo
+
+if TYPE_CHECKING:
+    from .document import Document
+
+OPF_NS = "http://www.idpf.org/2007/opf/"
+OPF = f"{{{OPF_NS}}}"
+
+
+def object_id() -> str:
+    return str(random.SystemRandom().randrange(1, 2**31 - 1))
+
+
+def paragraph_id() -> str:
+    return object_id()
+
+
+def distribute_size(total: int, parts: int) -> list[int]:
+    if parts <= 0:
+        return []
+    base, rem = divmod(max(int(total), 0), parts)
+    return [base + (1 if i < rem else 0) for i in range(parts)]
+
+
+def sublist_attrs() -> list[tuple[str, str]]:
+    return [
+        ("id", ""), ("textDirection", "HORIZONTAL"), ("lineWrap", "BREAK"),
+        ("vertAlign", "CENTER"), ("linkListIDRef", "0"),
+        ("linkListNextIDRef", "0"), ("textWidth", "0"), ("textHeight", "0"),
+        ("hasTextRef", "0"), ("hasNumRef", "0"),
+    ]
+
+
+def paragraph_attrs(*, para_pr_id_ref: str | int = "0", style_id_ref: str | int = "0") -> list[tuple[str, str]]:
+    return [
+        ("id", paragraph_id()), ("paraPrIDRef", str(para_pr_id_ref)),
+        ("styleIDRef", str(style_id_ref)), ("pageBreak", "0"),
+        ("columnBreak", "0"), ("merged", "0"),
+    ]
+
+
+def cell_inner_margin() -> list[tuple[str, str]]:
+    return [("left", "510"), ("right", "510"), ("top", "141"), ("bottom", "141")]
+
+
+def zero_margin() -> list[tuple[str, str]]:
+    return [("left", "0"), ("right", "0"), ("top", "0"), ("bottom", "0")]
+
+
+def create_table(
+    rows: int,
+    cols: int,
+    *,
+    width: int | None,
+    height: int | None,
+    border_fill_id_ref: str | int,
+) -> ElementModel:
+    if rows <= 0 or cols <= 0:
+        raise ValueError("rows and cols must be positive integers")
+    table_width = int(width if width is not None else cols * 7200)
+    table_height = int(height if height is not None else rows * 282)
+    border = str(border_fill_id_ref)
+
+    tbl = ElementModel(HP + "tbl", attrs=[
+        ("id", object_id()), ("zOrder", "0"), ("numberingType", "TABLE"),
+        ("textWrap", "TOP_AND_BOTTOM"), ("textFlow", "BOTH_SIDES"), ("lock", "0"),
+        ("dropcapstyle", "None"), ("pageBreak", "CELL"), ("repeatHeader", "0"),
+        ("rowCnt", str(rows)), ("colCnt", str(cols)), ("cellSpacing", "0"),
+        ("borderFillIDRef", border), ("noAdjust", "0"),
+    ])
+    tbl.children.extend([
+        ElementModel(HP + "sz", attrs=[
+            ("width", str(table_width)), ("widthRelTo", "ABSOLUTE"),
+            ("height", str(table_height)), ("heightRelTo", "ABSOLUTE"), ("protect", "0"),
+        ]),
+        ElementModel(HP + "pos", attrs=[
+            ("treatAsChar", "1"), ("affectLSpacing", "0"), ("flowWithText", "1"),
+            ("allowOverlap", "0"), ("holdAnchorAndSO", "0"), ("vertRelTo", "PARA"),
+            ("horzRelTo", "COLUMN"), ("vertAlign", "TOP"), ("horzAlign", "LEFT"),
+            ("vertOffset", "0"), ("horzOffset", "0"),
+        ]),
+        ElementModel(HP + "outMargin", attrs=zero_margin()),
+        ElementModel(HP + "inMargin", attrs=cell_inner_margin()),
+    ])
+    col_widths = distribute_size(table_width, cols)
+    row_heights = distribute_size(table_height, rows)
+    for r in range(rows):
+        tr = ElementModel(HP + "tr")
+        for c in range(cols):
+            tc = ElementModel(HP + "tc", attrs=[
+                ("name", ""), ("header", "0"), ("hasMargin", "0"), ("protect", "0"),
+                ("editable", "0"), ("dirty", "0"), ("borderFillIDRef", border),
+            ])
+            sub = ElementModel(HP + "subList", attrs=sublist_attrs())
+            p = ElementModel(HP + "p", attrs=paragraph_attrs())
+            run = ElementModel(HP + "run", attrs=[("charPrIDRef", "0")])
+            run.children.append(ElementModel(HP + "t", text=""))
+            p.children.append(run)
+            sub.children.append(p)
+            tc.children.extend([
+                sub,
+                ElementModel(HP + "cellAddr", attrs=[("colAddr", str(c)), ("rowAddr", str(r))]),
+                ElementModel(HP + "cellSpan", attrs=[("colSpan", "1"), ("rowSpan", "1")]),
+                ElementModel(HP + "cellSz", attrs=[("width", str(col_widths[c])), ("height", str(row_heights[r]))]),
+                ElementModel(HP + "cellMargin", attrs=cell_inner_margin()),
+            ])
+            tr.children.append(tc)
+        tbl.children.append(tr)
+    return tbl
+
+
+_IDENTITY = [("e1", "1"), ("e2", "0"), ("e3", "0"), ("e4", "0"), ("e5", "1"), ("e6", "0")]
+
+
+def _shape_common(parent: ElementModel, width: int, height: int, *, treat_as_char: bool) -> None:
+    ident = object_id()
+    for k, v in [
+        ("id", ident), ("zOrder", "0"), ("numberingType", "NONE"), ("textWrap", "SQUARE"),
+        ("textFlow", "BOTH_SIDES"), ("lock", "0"), ("dropcapstyle", "None"),
+        ("href", ""), ("groupLevel", "0"), ("instid", ident),
+    ]:
+        parent.set(k, v)
+    parent.children.extend([
+        ElementModel(HP + "offset", attrs=[("x", "0"), ("y", "0")]),
+        ElementModel(HP + "orgSz", attrs=[("width", str(width)), ("height", str(height))]),
+        ElementModel(HP + "curSz", attrs=[("width", str(width)), ("height", str(height))]),
+        ElementModel(HP + "flip", attrs=[("horizontal", "0"), ("vertical", "0")]),
+        ElementModel(HP + "rotationInfo", attrs=[
+            ("angle", "0"), ("centerX", str(width // 2)), ("centerY", str(height // 2)), ("rotateimage", "1")
+        ]),
+    ])
+    rendering = ElementModel(HP + "renderingInfo")
+    rendering.children.extend([
+        ElementModel(HC + "transMatrix", attrs=list(_IDENTITY)),
+        ElementModel(HC + "scaMatrix", attrs=list(_IDENTITY)),
+        ElementModel(HC + "rotMatrix", attrs=list(_IDENTITY)),
+    ])
+    parent.children.append(rendering)
+    parent.set("_treatAsChar", "1" if treat_as_char else "0")
+
+
+def _shape_drawing(parent: ElementModel, *, line_color: str, line_width: str, fill_color: str | None) -> None:
+    parent.children.append(ElementModel(HP + "lineShape", attrs=[
+        ("color", line_color.upper()), ("width", str(line_width)), ("style", "SOLID"),
+        ("endCap", "FLAT"), ("headStyle", "NORMAL"), ("tailStyle", "NORMAL"),
+        ("headfill", "1"), ("tailfill", "1"), ("headSz", "SMALL_SMALL"),
+        ("tailSz", "SMALL_SMALL"), ("outlineStyle", "NORMAL"), ("alpha", "0"),
+    ]))
+    if fill_color is not None:
+        fill = ElementModel(HC + "fillBrush")
+        fill.children.append(ElementModel(HC + "winBrush", attrs=[
+            ("faceColor", fill_color.upper()), ("hatchColor", "#FFFFFF"), ("alpha", "0")
+        ]))
+        parent.children.append(fill)
+    parent.children.append(ElementModel(HP + "shadow", attrs=[
+        ("type", "NONE"), ("color", "#B2B2B2"), ("offsetX", "0"), ("offsetY", "0"), ("alpha", "0")
+    ]))
+
+
+def _shape_base(parent: ElementModel, width: int, height: int) -> None:
+    treat = parent.get("_treatAsChar", "1") == "1"
+    parent.remove_attr("_treatAsChar")
+    parent.children.extend([
+        ElementModel(HP + "sz", attrs=[
+            ("width", str(width)), ("height", str(height)), ("widthRelTo", "ABSOLUTE"),
+            ("heightRelTo", "ABSOLUTE"), ("protect", "0"),
+        ]),
+        ElementModel(HP + "pos", attrs=[
+            ("treatAsChar", "1" if treat else "0"), ("affectLSpacing", "0"),
+            ("flowWithText", "1" if treat else "0"), ("allowOverlap", "0" if treat else "1"),
+            ("holdAnchorAndSO", "0"), ("vertRelTo", "PARA"), ("horzRelTo", "COLUMN"),
+            ("vertAlign", "TOP"), ("horzAlign", "LEFT"), ("vertOffset", "0"), ("horzOffset", "0"),
+        ]),
+        ElementModel(HP + "outMargin", attrs=zero_margin()),
+    ])
+
+
+def create_rectangle(
+    width: int,
+    height: int,
+    *,
+    line_color: str = "#000000",
+    line_width: str = "33",
+    fill_color: str | None = None,
+    treat_as_char: bool = True,
+    text: str | None = None,
+    para_pr_id_ref: str | int = "0",
+    char_pr_id_ref: str | int = "0",
+) -> ElementModel:
+    rect = ElementModel(HP + "rect", attrs=[("ratio", "0")])
+    _shape_common(rect, int(width), int(height), treat_as_char=treat_as_char)
+    _shape_drawing(rect, line_color=line_color, line_width=line_width, fill_color=fill_color)
+    if text is not None:
+        draw = ElementModel(HP + "drawText", attrs=[("lastWidth", str(width)), ("name", ""), ("editable", "0")])
+        sub = ElementModel(HP + "subList", attrs=sublist_attrs())
+        p = ElementModel(HP + "p", attrs=paragraph_attrs(para_pr_id_ref=para_pr_id_ref))
+        run = ElementModel(HP + "run", attrs=[("charPrIDRef", str(char_pr_id_ref))])
+        run.children.append(ElementModel(HP + "t", text=text))
+        p.children.append(run)
+        sub.children.append(p)
+        draw.children.extend([sub, ElementModel(HP + "textMargin", attrs=[("left", "283"), ("right", "283"), ("top", "283"), ("bottom", "283")])])
+        rect.children.append(draw)
+    rect.children.extend([
+        ElementModel(HC + "pt0", attrs=[("x", "0"), ("y", "0")]),
+        ElementModel(HC + "pt1", attrs=[("x", str(width)), ("y", "0")]),
+        ElementModel(HC + "pt2", attrs=[("x", str(width)), ("y", str(height))]),
+        ElementModel(HC + "pt3", attrs=[("x", "0"), ("y", str(height))]),
+    ])
+    _shape_base(rect, int(width), int(height))
+    return rect
+
+
+def create_picture(binary_item_id_ref: str, width: int, height: int, *, treat_as_char: bool = True) -> ElementModel:
+    pic = ElementModel(HP + "pic", attrs=[
+        ("textWrap", "SQUARE"), ("textFlow", "BOTH_SIDES"), ("reverse", "0")
+    ])
+    _shape_common(pic, int(width), int(height), treat_as_char=treat_as_char)
+    pic.set("numberingType", "PICTURE")
+    rect = ElementModel(HP + "imgRect")
+    rect.children.extend([
+        ElementModel(HC + "pt0", attrs=[("x", "0"), ("y", "0")]),
+        ElementModel(HC + "pt1", attrs=[("x", str(width)), ("y", "0")]),
+        ElementModel(HC + "pt2", attrs=[("x", str(width)), ("y", str(height))]),
+        ElementModel(HC + "pt3", attrs=[("x", "0"), ("y", str(height))]),
+    ])
+    pic.children.extend([
+        rect,
+        ElementModel(HP + "imgClip", attrs=[("left", "0"), ("right", str(width)), ("top", "0"), ("bottom", str(height))]),
+        ElementModel(HP + "inMargin", attrs=zero_margin()),
+        ElementModel(HP + "imgDim", attrs=[("dimwidth", str(width)), ("dimheight", str(height))]),
+        ElementModel(HC + "img", attrs=[
+            ("binaryItemIDRef", binary_item_id_ref), ("bright", "0"), ("contrast", "0"),
+            ("effect", "REAL_PIC"), ("alpha", "0"),
+        ]),
+        ElementModel(HP + "effects"),
+    ])
+    _shape_base(pic, int(width), int(height))
+    return pic
+
+
+_MEDIA_TYPES = {
+    "png": "image/png", "jpg": "image/jpeg", "jpeg": "image/jpeg", "gif": "image/gif", "bmp": "image/bmp",
+}
+
+
+def add_binary_image(document: "Document", data: bytes, image_format: str) -> str:
+    fmt = image_format.lower().lstrip(".")
+    if fmt not in _MEDIA_TYPES:
+        raise ValueError(f"unsupported image format: {image_format}")
+    manifest = next((n for n in document.content_model.iter() if local_name(n.tag) == "manifest"), None)
+    if manifest is None:
+        raise ValueError("content.hpf has no manifest")
+    used = {n.get("id") for n in manifest.children if local_name(n.tag) == "item"}
+    index = 1
+    while f"image{index}" in used or f"BinData/image{index}.{fmt}" in document._package.parts:
+        index += 1
+    item_id = f"image{index}"
+    name = f"BinData/{item_id}.{fmt}"
+    manifest.children.append(ElementModel(OPF + "item", attrs=[
+        ("id", item_id), ("href", name), ("media-type", _MEDIA_TYPES[fmt]), ("isEmbeded", "1")
+    ]))
+    # Use the section entry's metadata conventions for the new ZIP member.
+    ref = document._package.infos.get("Contents/section0.xml")
+    date_time = ref.date_time if ref is not None else (2026, 1, 1, 0, 0, 0)
+    document._package.set(name, bytes(data), PackageEntryInfo(name, zipfile.ZIP_DEFLATED, date_time))
+    return item_id

pywpdoc/_engine/common/__init__.py

@@ -0,0 +1,3 @@
+from .document import Document, UnifiedDocument
+
+__all__ = ["Document", "UnifiedDocument"]

pywpdoc/_engine/common/document.py

@@ -0,0 +1,133 @@
+"""Thin optional facade over independently usable DOCX and HWPX backends.
+
+The common layer deliberately owns no text-replacement algorithm, table
+geometry, XML handling, or backend option normalization. It only selects a
+backend and delegates the shared surface.
+"""
+from __future__ import annotations
+from pathlib import Path
+from typing import Any
+
+from ..core.errors import DocumentUnsupportedError, DocumentValueError
+from ..core.contracts import DocumentBackend
+
+
+class Document:
+    """Thin common wrapper around a standalone backend document."""
+
+    def __init__(self, backend: DocumentBackend):
+        self.backend = backend
+
+    @classmethod
+    def open(cls, source: str | Path) -> "Document":
+        path = Path(source)
+        suffix = path.suffix.lower()
+        if suffix == ".hwpx":
+            from ..hwpx import Document as HwpxDocument
+            return cls(HwpxDocument.open(path))
+        if suffix == ".docx":
+            from ..docx import Document as DocxDocument
+            return cls(DocxDocument.open(path))
+        raise DocumentValueError(
+            f"cannot infer document format from {path.name!r}",
+            code="common-format-unknown",
+            context={"suffix": suffix},
+        )
+
+    @classmethod
+    def new(cls, format: str = "hwpx", *, compatibility: str | None = None) -> "Document":
+        fmt = str(format).lower().lstrip(".")
+        if fmt == "hwpx":
+            from ..hwpx import Document as HwpxDocument
+            return cls(HwpxDocument.new(compatibility=compatibility or "hancom2020"))
+        if fmt == "docx":
+            if compatibility is not None:
+                raise DocumentValueError(
+                    "compatibility profiles are only supported for HWPX",
+                    code="common-compatibility-not-applicable",
+                    context={"format": fmt, "compatibility": compatibility},
+                )
+            from ..docx import Document as DocxDocument
+            return cls(DocxDocument.new())
+        raise DocumentValueError("format must be 'hwpx' or 'docx'", code="common-format-invalid")
+
+    @classmethod
+    def rebuild(
+        cls,
+        source: "Document | str | Path",
+        *,
+        format: str | None = None,
+        preserve_layout: bool = True,
+    ) -> "Document":
+        """Rebuild *source* through the selected backend.
+
+        Common only transports the backend-neutral snapshot. Export/import
+        semantics and all format fidelity rules remain backend-owned.
+        """
+        src = source if isinstance(source, cls) else cls.open(source)
+        target = cls.new(format or src.format)
+        snapshot = src.backend.export_snapshot(preserve_layout=preserve_layout)
+        if src.format == "docx" and target.format == "hwpx":
+            raise DocumentUnsupportedError(
+                "DOCX to HWPX rebuild is not supported: no verified portable snapshot importer",
+                code="rebuild-docx-to-hwpx-unsupported",
+            )
+        target.backend.import_snapshot(snapshot, preserve_layout=preserve_layout)
+        return target
+
+    def export_snapshot(self, *, preserve_layout: bool = True):
+        return self.backend.export_snapshot(preserve_layout=preserve_layout)
+
+    def rebuild_from(self, source: "Document", *, preserve_layout: bool = True) -> "Document":
+        snapshot = source.backend.export_snapshot(preserve_layout=preserve_layout)
+        if source.format == "docx" and self.format == "hwpx":
+            raise DocumentUnsupportedError(
+                "DOCX to HWPX rebuild is not supported: no verified portable snapshot importer",
+                code="rebuild-docx-to-hwpx-unsupported",
+            )
+        self.backend.import_snapshot(snapshot, preserve_layout=preserve_layout)
+        return self
+
+    @property
+    def format(self) -> str:
+        return self.backend.format
+
+    @property
+    def native(self) -> Any:
+        """Deep native/expert object (legacy HWPX Document or python-docx Document)."""
+        return self.backend.native
+
+    def unwrap(self) -> Any:
+        """Return the current backend/native object via an explicit escape hatch.
+
+        Code using this method is backend-specific and therefore has weaker
+        compatibility guarantees than the common or format-specific API.
+        """
+        return self.native
+
+    @property
+    def hwpx(self):
+        if self.format != "hwpx":
+            raise DocumentUnsupportedError(
+                "this document uses the DOCX backend; HWPX expert API is unavailable",
+                code="common-hwpx-expert-unavailable",
+            )
+        return self.native
+
+    @property
+    def docx(self):
+        if self.format != "docx":
+            raise DocumentUnsupportedError(
+                "this document uses the HWPX backend; DOCX expert API is unavailable",
+                code="common-docx-expert-unavailable",
+            )
+        return self.native
+
+    def __getattr__(self, name: str):
+        # Backend implementation remains independent of the small common facade.
+        return getattr(self.backend, name)
+
+
+UnifiedDocument = Document
+
+__all__ = ["Document", "UnifiedDocument"]

pywpdoc/_engine/common_api.py

@@ -0,0 +1,9 @@
+"""Compatibility shim for the v0.12 experimental common API import path.
+
+The implementation moved to :mod:`pywpdoc._engine.common` in v0.13. The
+common layer is now intentionally thin; all real behavior lives in the
+independently usable DOCX/HWPX backend modules.
+"""
+from .common import Document, UnifiedDocument
+
+__all__ = ["Document", "UnifiedDocument"]

pywpdoc/_engine/core/__init__.py

@@ -0,0 +1,11 @@
+from .units import Length, Pt, Mm, HwpUnit, Cm, Inches
+from .enums import WD_CELL_VERTICAL_ALIGNMENT, WD_ALIGN_VERTICAL, WD_ORIENTATION, WD_ORIENT, WD_STYLE_TYPE
+from .errors import DocumentError, DocumentValueError, DocumentStateError, DocumentUnsupportedError
+from .contracts import DocumentBackend, ParagraphBackend, TableBackend, CellBackend
+
+__all__ = [
+    "Length", "Pt", "Mm", "HwpUnit", "Cm", "Inches",
+    "WD_CELL_VERTICAL_ALIGNMENT", "WD_ALIGN_VERTICAL", "WD_ORIENTATION", "WD_ORIENT", "WD_STYLE_TYPE",
+    "DocumentError", "DocumentValueError", "DocumentStateError", "DocumentUnsupportedError",
+    "DocumentBackend", "ParagraphBackend", "TableBackend", "CellBackend",
+]