docwow 0.1.0__py3-none-any.whl

docwow/__init__.py

@@ -0,0 +1,108 @@
+"""
+docwow — pixel-perfect Word ↔ HTML conversion.
+
+Public API
+----------
+Parse::
+
+    doc = docwow.open("report.docx")          # DOCX → Document
+    doc = docwow.open(html_string)             # docwow HTML → Document
+
+Convert::
+
+    html = docwow.to_html("report.docx")      # DOCX → HTML string
+    data = docwow.to_docx(html_string)        # HTML → DOCX bytes
+    data = docwow.to_docx(html_string, target="out.docx")
+
+Low-level::
+
+    doc  = docwow.parse_docx(source)           # bytes | str | Path → Document
+    doc  = docwow.parse_html(source)           # str | bytes → Document
+    html = docwow.render_document(doc)         # Document → HTML string
+    data = docwow.write_docx(doc, target=None) # Document → DOCX bytes
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from docwow.html_parser.html_parser import parse_html
+from docwow.parser.docx_parser import parse_docx
+from docwow.renderer.html_renderer import render_document
+from docwow.writer.docx_writer import write_docx
+
+__all__ = [
+    "open",
+    "to_html",
+    "to_docx",
+    "parse_docx",
+    "parse_html",
+    "render_document",
+    "write_docx",
+]
+
+__version__ = "0.1.0"
+
+
+# ---------------------------------------------------------------------------
+# Convenience API
+# ---------------------------------------------------------------------------
+
+def open(source: str | Path | bytes) -> "Document":
+    """Parse a DOCX file *or* a docwow HTML string into a Document model.
+
+    Args:
+        source: A file path (``str`` or :class:`~pathlib.Path`) or raw bytes
+                pointing to a ``.docx`` file, **or** an HTML string produced
+                by :func:`render_document`.
+
+    Returns:
+        A :class:`~docwow.models.document.Document` instance.
+    """
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        try:
+            is_docx = path.exists() and path.suffix.lower() in (".docx", ".doc")
+        except (OSError, ValueError):
+            is_docx = False
+        if is_docx:
+            return parse_docx(source)
+        # Treat as HTML string
+        return parse_html(str(source))
+    # bytes — try DOCX first (ZIP magic bytes), fall back to HTML
+    if isinstance(source, bytes):
+        if source[:2] == b"PK":
+            return parse_docx(source)
+        return parse_html(source)
+    raise TypeError(f"Expected str, Path, or bytes; got {type(source).__name__}")
+
+
+def to_html(source: str | Path | bytes) -> str:
+    """Convert a DOCX file to a self-contained HTML string.
+
+    Args:
+        source: Path to a ``.docx`` file, or raw DOCX bytes.
+
+    Returns:
+        UTF-8 HTML string produced by :func:`render_document`.
+    """
+    doc = parse_docx(source)
+    return render_document(doc)
+
+
+def to_docx(
+    html: str | bytes,
+    target: str | Path | None = None,
+) -> bytes:
+    """Convert a docwow HTML string back to a DOCX file.
+
+    Args:
+        html:   HTML string or bytes produced by :func:`render_document` /
+                :func:`to_html`.
+        target: Optional output path.  When provided the bytes are also
+                written to disk.
+
+    Returns:
+        Raw DOCX bytes (a valid ZIP archive).
+    """
+    doc = parse_html(html)
+    return write_docx(doc, target=target)

docwow/html_parser/__init__.py

@@ -0,0 +1,4 @@
+"""HTML → Document model parser for docwow."""
+from .html_parser import parse_html
+
+__all__ = ["parse_html"]

docwow/html_parser/_utils.py

@@ -0,0 +1,28 @@
+"""Shared low-level helpers for the HTML parser."""
+from __future__ import annotations
+
+
+def has_class(el, cls: str) -> bool:
+    """Return True if *el* carries the given CSS class."""
+    return cls in el.get("class", "").split()
+
+
+def pt_val(s: str | None, default: float | None = None) -> float | None:
+    """Parse a CSS pt string to float.
+
+    Examples::
+
+        pt_val("36pt")       -> 36.0
+        pt_val("36.5pt")     -> 36.5
+        pt_val(None)         -> None  (or *default*)
+        pt_val(None, 0.0)    -> 0.0
+    """
+    if s is None:
+        return default
+    s = s.strip()
+    if s.endswith("pt"):
+        try:
+            return float(s[:-2])
+        except ValueError:
+            return default
+    return default

docwow/html_parser/html_parser.py

@@ -0,0 +1,148 @@
+"""
+Parse docwow-generated HTML back into a Document model.
+
+The HTML produced by render_document() encodes all Word metadata in
+data-dw-* attributes, so the round-trip is lossless for structure and
+formatting.  Styles are reconstructed as minimal Style objects (style_id
+and name only); full style declarations are preserved per-paragraph via
+the data attributes on each <p> element.
+"""
+from __future__ import annotations
+
+import lxml.html
+
+from docwow.html_parser._utils import has_class, pt_val
+from docwow.html_parser.paragraph_parser import parse_paragraph
+from docwow.html_parser.table_parser import parse_table
+from docwow.models.document import Document
+from docwow.models.lists import ListLevel, NumberingDefinition
+from docwow.models.paragraph import Paragraph
+from docwow.models.styles import Style
+from docwow.models.table import Table
+
+
+def parse_html(source: str | bytes) -> Document:
+    """Parse a docwow HTML string back into a Document model.
+
+    Args:
+        source: HTML produced by ``render_document()``, as a string or
+                UTF-8 bytes.
+
+    Returns:
+        A :class:`~docwow.models.document.Document` whose body, geometry,
+        styles, and numbering reflect the content of the HTML.
+
+    Raises:
+        ValueError: If the HTML does not contain a ``dw-document`` element.
+    """
+    if isinstance(source, str):
+        source = source.encode("utf-8")
+    root = lxml.html.document_fromstring(source)
+
+    divs = root.xpath('.//div[contains(@class,"dw-document")]')
+    if not divs:
+        raise ValueError("HTML does not contain a dw-document element")
+    doc_div = divs[0]
+
+    # Page geometry — fall back to A4 / 1-inch margins if attributes absent
+    g = doc_div.get
+    page_width_pt    = pt_val(g("data-dw-page-width"),    595.28)
+    page_height_pt   = pt_val(g("data-dw-page-height"),   841.89)
+    margin_top_pt    = pt_val(g("data-dw-margin-top"),    72.0)
+    margin_bottom_pt = pt_val(g("data-dw-margin-bottom"), 72.0)
+    margin_left_pt   = pt_val(g("data-dw-margin-left"),   72.0)
+    margin_right_pt  = pt_val(g("data-dw-margin-right"),  72.0)
+
+    body, numbering, style_ids = _parse_body(doc_div)
+
+    # Minimal Style objects: carry the style_id so the writer can reference them
+    styles = tuple(
+        Style(style_id=sid, name=sid, style_type="paragraph")
+        for sid in sorted(style_ids)
+    )
+
+    return Document(
+        body=body,
+        styles=styles,
+        numbering=numbering,
+        page_width_pt=page_width_pt,
+        page_height_pt=page_height_pt,
+        margin_top_pt=margin_top_pt,
+        margin_bottom_pt=margin_bottom_pt,
+        margin_left_pt=margin_left_pt,
+        margin_right_pt=margin_right_pt,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Body traversal
+# ---------------------------------------------------------------------------
+
+def _parse_body(
+    doc_div,
+) -> tuple[tuple[Paragraph | Table, ...], tuple[NumberingDefinition, ...], set[str]]:
+    """Walk direct children of the dw-document div and build the body tuple."""
+    body: list[Paragraph | Table] = []
+    style_ids: set[str] = set()
+    # num_id → {level → num_fmt}
+    numbering_levels: dict[str, dict[int, str]] = {}
+
+    for child in doc_div:
+        tag = child.tag
+        if tag == "p" and has_class(child, "dw-p"):
+            para = parse_paragraph(child)
+            body.append(para)
+            _collect_style(para, style_ids)
+
+        elif tag == "table" and has_class(child, "dw-table"):
+            body.append(parse_table(child))
+
+        elif tag in ("ul", "ol") and has_class(child, "dw-list"):
+            _collect_list(child, body, style_ids, numbering_levels)
+
+    return tuple(body), _build_numbering(numbering_levels), style_ids
+
+
+def _collect_list(
+    list_el,
+    body: list,
+    style_ids: set[str],
+    numbering_levels: dict[str, dict[int, str]],
+) -> None:
+    """Extract paragraphs from a dw-list element, handling nesting."""
+    num_id = list_el.get("data-dw-num-id", "")
+    num_fmt = "bullet" if list_el.tag == "ul" else "decimal"
+
+    for li in list_el:
+        if li.tag != "li":
+            continue
+        level = int(li.get("data-dw-level", "0"))
+        numbering_levels.setdefault(num_id, {})[level] = num_fmt
+
+        for child in li:
+            if child.tag == "p" and has_class(child, "dw-p"):
+                para = parse_paragraph(child)
+                body.append(para)
+                _collect_style(para, style_ids)
+            elif child.tag in ("ul", "ol") and has_class(child, "dw-list"):
+                _collect_list(child, body, style_ids, numbering_levels)
+
+
+def _collect_style(para: Paragraph, style_ids: set[str]) -> None:
+    if para.formatting.style_id:
+        style_ids.add(para.formatting.style_id)
+
+
+def _build_numbering(
+    numbering_levels: dict[str, dict[int, str]],
+) -> tuple[NumberingDefinition, ...]:
+    return tuple(
+        NumberingDefinition(
+            abstract_num_id=num_id,
+            levels=tuple(
+                ListLevel(level=lvl, num_fmt=fmt)
+                for lvl, fmt in sorted(levels.items())
+            ),
+        )
+        for num_id, levels in sorted(numbering_levels.items())
+    )

docwow/html_parser/paragraph_parser.py

@@ -0,0 +1,127 @@
+"""Parse <p class="dw-p"> elements into Paragraph model objects."""
+from __future__ import annotations
+
+import base64
+
+from docwow.html_parser._utils import has_class, pt_val
+from docwow.models.image import InlineImage
+from docwow.models.lists import ListInfo
+from docwow.models.paragraph import ImageRun, Paragraph, Run, TextRun
+from docwow.models.styles import ParagraphFormatting, RunFormatting
+
+
+def parse_paragraph(p_el) -> Paragraph:
+    """Parse a <p class="dw-p"> lxml element into a Paragraph."""
+    return Paragraph(
+        runs=tuple(_parse_runs(p_el)),
+        formatting=_parse_para_formatting(p_el),
+        list_info=_parse_list_info(p_el),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Paragraph-level
+# ---------------------------------------------------------------------------
+
+def _parse_para_formatting(p_el) -> ParagraphFormatting:
+    g = p_el.get
+    return ParagraphFormatting(
+        style_id=g("data-dw-style"),
+        alignment=g("data-dw-alignment"),
+        indent_left_pt=pt_val(g("data-dw-indent-left"), 0.0),
+        indent_right_pt=pt_val(g("data-dw-indent-right"), 0.0),
+        indent_first_line_pt=pt_val(g("data-dw-indent-first-line"), 0.0),
+        space_before_pt=pt_val(g("data-dw-space-before"), 0.0),
+        space_after_pt=pt_val(g("data-dw-space-after"), 0.0),
+        line_spacing_pt=pt_val(g("data-dw-line-spacing")),
+        keep_together=g("data-dw-keep-together") == "true",
+        keep_with_next=g("data-dw-keep-with-next") == "true",
+        page_break_before=g("data-dw-page-break-before") == "true",
+    )
+
+
+def _parse_list_info(p_el) -> ListInfo | None:
+    num_id = p_el.get("data-dw-num-id")
+    if num_id is None:
+        return None
+    return ListInfo(num_id=num_id, level=int(p_el.get("data-dw-level", "0")))
+
+
+# ---------------------------------------------------------------------------
+# Run-level
+# ---------------------------------------------------------------------------
+
+def _parse_runs(p_el) -> list[Run]:
+    runs: list[Run] = []
+    for child in p_el:
+        if child.tag == "span" and has_class(child, "dw-r"):
+            runs.append(_parse_text_run(child))
+        elif child.tag == "img" and has_class(child, "dw-img"):
+            runs.append(_parse_image_run(child))
+    return runs
+
+
+def _parse_text_run(span_el) -> TextRun:
+    return TextRun(
+        text=_extract_text(span_el),
+        formatting=_parse_run_formatting(span_el),
+    )
+
+
+def _extract_text(span_el) -> str:
+    """Reconstruct text content, turning <br> elements back into newlines."""
+    parts: list[str] = []
+    if span_el.text:
+        parts.append(span_el.text)
+    for child in span_el:
+        if child.tag == "br":
+            parts.append("\n")
+        if child.tail:
+            parts.append(child.tail)
+    return "".join(parts)
+
+
+def _parse_run_formatting(span_el) -> RunFormatting:
+    g = span_el.get
+    return RunFormatting(
+        bold=g("data-dw-bold") == "true",
+        italic=g("data-dw-italic") == "true",
+        underline=g("data-dw-underline") == "true",
+        strike=g("data-dw-strike") == "true",
+        font_name=g("data-dw-font-name"),
+        font_size_pt=pt_val(g("data-dw-font-size")),
+        color=g("data-dw-color"),
+        highlight=g("data-dw-highlight"),
+        vertical_align=g("data-dw-vertical-align"),
+    )
+
+
+def _parse_image_run(img_el) -> ImageRun:
+    width_pt = pt_val(img_el.get("data-dw-width"), 0.0)
+    height_pt = pt_val(img_el.get("data-dw-height"), 0.0)
+    content_type, data = _parse_data_uri(img_el.get("src", ""))
+    return ImageRun(
+        image=InlineImage(
+            relationship_id=img_el.get("data-dw-rid", ""),
+            content_type=content_type,
+            data=data,
+            width_pt=width_pt,
+            height_pt=height_pt,
+            alt_text=img_el.get("alt", ""),
+        )
+    )
+
+
+def _parse_data_uri(src: str) -> tuple[str, bytes]:
+    """Decode a base64 data URI into (content_type, raw_bytes)."""
+    if not src.startswith("data:"):
+        return ("", b"")
+    rest = src[5:]          # "{content_type};base64,{b64}"
+    if "," not in rest:
+        return ("", b"")
+    meta, b64_data = rest.split(",", 1)
+    content_type = meta.split(";")[0]
+    try:
+        return content_type, base64.b64decode(b64_data)
+    except Exception:
+        return content_type, b""

docwow/html_parser/table_parser.py

@@ -0,0 +1,45 @@
+"""Parse <table class="dw-table"> elements into Table model objects."""
+from __future__ import annotations
+
+from docwow.html_parser._utils import has_class, pt_val
+from docwow.html_parser.paragraph_parser import parse_paragraph
+from docwow.models.table import Table, TableCell, TableRow
+
+
+def parse_table(table_el) -> Table:
+    """Parse a <table class="dw-table"> lxml element into a Table."""
+    col_widths_str = table_el.get("data-dw-col-widths", "")
+    col_widths_pt = tuple(
+        pt_val(w.strip()) or 0.0
+        for w in col_widths_str.split(",")
+        if w.strip()
+    )
+    return Table(
+        rows=tuple(_parse_row(tr) for tr in table_el if tr.tag == "tr"),
+        style_id=table_el.get("data-dw-style"),
+        width_pt=pt_val(table_el.get("data-dw-width")),
+        col_widths_pt=col_widths_pt,
+    )
+
+
+def _parse_row(tr_el) -> TableRow:
+    return TableRow(
+        cells=tuple(_parse_cell(td) for td in tr_el if td.tag == "td"),
+        height_pt=pt_val(tr_el.get("data-dw-height")),
+    )
+
+
+def _parse_cell(td_el) -> TableCell:
+    paragraphs = tuple(
+        parse_paragraph(child)
+        for child in td_el
+        if child.tag == "p" and has_class(child, "dw-p")
+    )
+    return TableCell(
+        paragraphs=paragraphs,
+        col_span=int(td_el.get("colspan", "1")),
+        row_span=int(td_el.get("rowspan", "1")),
+        width_pt=pt_val(td_el.get("data-dw-width")),
+        v_merge_start=td_el.get("data-dw-v-merge-start") == "true",
+        v_merge_continue=td_el.get("data-dw-v-merge-continue") == "true",
+    )

docwow/models/__init__.py

@@ -0,0 +1,25 @@
+from docwow.models.document import Document, BodyElement
+from docwow.models.image import InlineImage
+from docwow.models.lists import ListInfo, ListLevel, NumberingDefinition
+from docwow.models.paragraph import ImageRun, Paragraph, Run, TextRun
+from docwow.models.styles import ParagraphFormatting, RunFormatting, Style
+from docwow.models.table import Table, TableCell, TableRow
+
+__all__ = [
+    "BodyElement",
+    "Document",
+    "ImageRun",
+    "InlineImage",
+    "ListInfo",
+    "ListLevel",
+    "NumberingDefinition",
+    "Paragraph",
+    "ParagraphFormatting",
+    "Run",
+    "RunFormatting",
+    "Style",
+    "Table",
+    "TableCell",
+    "TableRow",
+    "TextRun",
+]

docwow/models/document.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from docwow.models.lists import NumberingDefinition
+from docwow.models.paragraph import Paragraph
+from docwow.models.styles import Style
+from docwow.models.table import Table
+
+# Top-level body elements (v0.1: paragraphs and tables only)
+BodyElement: TypeAlias = Paragraph | Table
+
+
+@dataclass(frozen=True)
+class Document:
+    """
+    Root of the internal document model.
+
+    All lengths are in points (pt).  EMU→pt conversion happens in the parser;
+    pt→CSS conversion happens in the renderer.
+
+    Default page size: A4 (595.28 × 841.89 pt).
+    Default margins: 1 inch (72 pt) on all sides.
+    """
+
+    body: tuple[BodyElement, ...]
+    styles: tuple[Style, ...]
+    numbering: tuple[NumberingDefinition, ...]
+
+    # Page geometry (pt)
+    page_width_pt: float = 595.28    # A4 width
+    page_height_pt: float = 841.89   # A4 height
+    margin_top_pt: float = 72.0      # 1 inch
+    margin_bottom_pt: float = 72.0
+    margin_left_pt: float = 72.0
+    margin_right_pt: float = 72.0

docwow/models/image.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class InlineImage:
+    """An inline image embedded in a paragraph run."""
+
+    relationship_id: str   # rId key from the DOCX relationships file
+    content_type: str      # MIME type e.g. "image/png", "image/jpeg"
+    data: bytes            # raw image bytes
+    width_pt: float        # rendered width in points (converted from EMU at parse time)
+    height_pt: float       # rendered height in points (converted from EMU at parse time)
+    alt_text: str = ""     # accessibility description

docwow/models/lists.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from docwow.models.styles import RunFormatting
+
+
+@dataclass(frozen=True)
+class ListLevel:
+    """Formatting definition for one level of a numbered/bulleted list (0-based)."""
+
+    level: int       # 0–8 (Word supports up to 9 levels)
+    num_fmt: str     # "bullet" | "decimal" | "lowerLetter" | "upperLetter"
+                     # | "lowerRoman" | "upperRoman" | "none"
+    start_value: int = 1
+    text_template: str = "%1."   # e.g. "%1." → "1.", "%1.%2." → "1.1."
+    indent_pt: float = 0.0       # left indent for the list item text
+    hanging_pt: float = 0.0      # hanging indent (bullet/number protrudes left)
+    run_fmt: RunFormatting | None = None   # formatting applied to the list label
+
+
+@dataclass(frozen=True)
+class NumberingDefinition:
+    """Maps an abstract numbering definition to its per-level configurations."""
+
+    abstract_num_id: str
+    levels: tuple[ListLevel, ...]
+
+
+@dataclass(frozen=True)
+class ListInfo:
+    """Attached to a Paragraph when it is a list item."""
+
+    num_id: str    # references a NumberingDefinition via its concrete num ID
+    level: int     # 0-based level in the list hierarchy

docwow/models/paragraph.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TypeAlias
+
+from docwow.models.image import InlineImage
+from docwow.models.lists import ListInfo
+from docwow.models.styles import ParagraphFormatting, RunFormatting
+
+
+@dataclass(frozen=True)
+class TextRun:
+    """A contiguous run of text sharing the same character formatting."""
+
+    text: str
+    formatting: RunFormatting = field(default_factory=RunFormatting)
+
+
+@dataclass(frozen=True)
+class ImageRun:
+    """An inline image treated as a run within a paragraph."""
+
+    image: InlineImage
+    formatting: RunFormatting = field(default_factory=RunFormatting)
+
+
+# A paragraph's content is a sequence of runs — either text or an inline image.
+Run: TypeAlias = TextRun | ImageRun
+
+
+@dataclass(frozen=True)
+class Paragraph:
+    """A Word paragraph: an ordered sequence of runs with paragraph-level formatting."""
+
+    runs: tuple[Run, ...]
+    formatting: ParagraphFormatting = field(default_factory=ParagraphFormatting)
+    list_info: ListInfo | None = None   # set when this paragraph is a list item

docwow/models/styles.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class RunFormatting:
+    """Character-level formatting for a run of text."""
+
+    bold: bool = False
+    italic: bool = False
+    underline: bool = False
+    strike: bool = False
+    font_name: str | None = None
+    font_size_pt: float | None = None  # points; converted from half-points at parse time
+    color: str | None = None           # hex RGB e.g. "FF0000"; None = auto
+    highlight: str | None = None       # Word highlight color name e.g. "yellow"
+    vertical_align: str | None = None  # "superscript" | "subscript" | None
+
+
+@dataclass(frozen=True)
+class ParagraphFormatting:
+    """Paragraph-level formatting."""
+
+    style_id: str | None = None
+    alignment: str | None = None        # "left" | "center" | "right" | "justify" | None
+    indent_left_pt: float = 0.0
+    indent_right_pt: float = 0.0
+    indent_first_line_pt: float = 0.0  # negative = hanging indent
+    space_before_pt: float = 0.0
+    space_after_pt: float = 0.0
+    line_spacing_pt: float | None = None  # None = single/auto
+    keep_together: bool = False
+    keep_with_next: bool = False
+    page_break_before: bool = False
+
+
+@dataclass(frozen=True)
+class Style:
+    """A named Word style definition (paragraph, character, table, or numbering)."""
+
+    style_id: str
+    name: str
+    style_type: str                          # "paragraph" | "character" | "table" | "numbering"
+    based_on: str | None = None              # style_id of parent style
+    paragraph_fmt: ParagraphFormatting | None = None
+    run_fmt: RunFormatting | None = None