fancydocx 0.1.0__py3-none-any.whl

fancydocx/__init__.py

@@ -0,0 +1,155 @@
+"""
+fancydocx - pure-Python DOCX -> single self-contained HTML converter.
+
+    import fancydocx
+    fancydocx.convert("resume.docx", "resume.html")   # write a file
+    html = fancydocx.convert("resume.docx")            # or get the HTML string
+
+No external engines, no LibreOffice, no network. Images are inlined as data
+URIs and embedded fonts are recovered as @font-face, so the output is one
+portable .html file.
+"""
+from __future__ import annotations
+import html as _html
+import pathlib
+
+from .core import local
+from .package import DocxPackage
+from .theme import Theme
+from .styles import Styles, rpr_to_css, ppr_to_css, line_height_css
+from .numbering import Numbering
+from .render import Converter
+from .fontmetrics import embed_css_for_families
+
+__version__ = "0.1.0"
+__all__ = ["convert", "convert_docx", "convert_file", "DocxPackage", "__version__"]
+
+BASE_CSS = """
+*{box-sizing:border-box}
+html,body{margin:0;padding:0}
+body{background:#e9e9ee;color:#000;-webkit-print-color-adjust:exact;print-color-adjust:exact;
+     text-rendering:geometricPrecision}
+.docx-doc{padding:24px 12px}
+/* isolation:isolate makes each page its own stacking context, so that
+   z-index:-1 layers (header/footer art, behindDoc shapes) paint ABOVE the
+   page's own background but BELOW in-flow content -- exactly Word's
+   page-color / behind-text / text layering. Without it, negative z-index
+   children fall behind the page background and vanish. */
+.docx-page{position:relative;background:#fff;margin:0 auto 24px;
+           box-shadow:0 2px 14px rgba(0,0,0,.28);overflow:hidden;isolation:isolate}
+/* .docx-body is intentionally NOT positioned so absolutely-positioned floats
+   (anchored images/shapes) resolve against the .docx-page box = true page
+   coordinates, matching Word's page-relative anchoring. */
+.docx-page p{margin:0}
+.docx-page table{border-spacing:0;max-width:none;border-collapse:collapse}
+.docx-page td,.docx-page th{vertical-align:top}
+.docx-page img{max-width:none}
+.docx-page a{color:inherit;text-decoration:inherit}
+.leader{flex:1 1 auto;align-self:flex-end;border-bottom:1px dotted currentColor;margin:0 4px 3px}
+.tab{display:inline-block;min-width:2em}
+.docx-header,.docx-footer{pointer-events:none}
+@media print{
+ html,body{background:#fff}
+ .docx-doc{padding:0}
+ .docx-page{box-shadow:none;margin:0;page-break-after:always}
+ @page{margin:0}
+}
+"""
+
+
+def _title(pkg, path):
+    core = pkg.xml("docProps/core.xml")
+    if core is not None:
+        for el in core.iter():
+            if local(el.tag) == "title" and el.text:
+                return el.text.strip()
+    return pathlib.Path(str(path)).stem
+
+
+def _body_rule(styles, theme):
+    """Default inherited run/paragraph look, applied to .docx-body."""
+    rpr = styles.effective_rpr(None, None, {})
+    ppr = styles.effective_ppr(None, {})
+    d = rpr_to_css(rpr, theme)
+    out = {}
+    for k in ("font-family", "font-size", "color"):
+        if k in d:
+            out[k] = d[k]
+    # Word single spacing is font-metric based (see fontmetrics.py); the
+    # numeric factor keeps the geometry even under font substitution.
+    out["line-height"] = line_height_css(ppr.get("spacing"),
+                                         rpr.get("font"), rpr.get("sz") or 11.0)
+    out.setdefault("font-family", "'Calibri', 'Segoe UI', sans-serif")
+    out.setdefault("font-size", "11pt")
+    out["word-wrap"] = "break-word"
+    return ".docx-body{%s}" % ";".join("%s:%s" % (k, v) for k, v in out.items())
+
+
+def convert_docx(path, include_headers=True, embed_fonts=False):
+    """
+    Convert a .docx file to a single self-contained HTML string.
+
+    embed_fonts: additionally inline every referenced font family found on
+    THIS machine as base64 @font-face. This makes the HTML render with the
+    exact intended glyph metrics on any viewer, at the cost of several MB
+    per file -- off by default for batch conversions.
+    """
+    pkg = DocxPackage(path)
+    try:
+        theme = Theme(pkg)
+        styles = Styles(pkg, theme)
+        numbering = Numbering(pkg, theme)
+        conv = Converter(pkg, theme, styles, numbering, include_headers=include_headers)
+        body = conv.render_document()
+        font_css, doc_families = pkg.font_face_css_and_families()
+        if embed_fonts:
+            local_css = embed_css_for_families(conv.used_fonts, already_embedded=doc_families)
+            if local_css:
+                font_css = font_css + "\n" + local_css if font_css else local_css
+        body_rule = _body_rule(styles, theme)
+        title = _title(pkg, path)
+    finally:
+        pkg.close()
+
+    return (
+        "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n"
+        "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n"
+        "<title>%s</title>\n<style>\n%s\n%s\n%s\n</style>\n</head>\n<body>\n"
+        "<div class=\"docx-doc\">%s</div>\n</body>\n</html>\n"
+        % (_html.escape(title), BASE_CSS, body_rule, font_css, body)
+    )
+
+
+def convert_file(in_path, out_path, include_headers=True, embed_fonts=False):
+    """Convert one .docx to one .html on disk. Returns the output path."""
+    result = convert_docx(in_path, include_headers=include_headers,
+                          embed_fonts=embed_fonts)
+    out = pathlib.Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(result, encoding="utf-8")
+    return str(out)
+
+
+def convert(source, output=None, *, embed_fonts=False, include_headers=True):
+    """
+    One-line entry point.
+
+        import fancydocx
+        fancydocx.convert("resume.docx", "resume.html")   # write the file, returns path
+        html = fancydocx.convert("resume.docx")            # no output -> returns HTML str
+
+    Parameters
+    ----------
+    source : str | os.PathLike
+        Path to the input .docx file.
+    output : str | os.PathLike | None
+        Where to write the HTML. If None, the HTML is returned as a string.
+    embed_fonts : bool
+        Inline locally-installed referenced fonts as base64 @font-face
+        (exact metrics on any viewer, at the cost of file size).
+    include_headers : bool
+        Render document headers/footers (default True).
+    """
+    if output is None:
+        return convert_docx(source, include_headers=include_headers, embed_fonts=embed_fonts)
+    return convert_file(source, output, include_headers=include_headers, embed_fonts=embed_fonts)

fancydocx/__main__.py

@@ -0,0 +1,5 @@
+"""Enable ``python -m fancydocx`` to run the command-line interface."""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fancydocx/cli.py

@@ -0,0 +1,117 @@
+"""
+Command-line interface for fancydocx, exposed as the ``fancydocx`` command
+(and ``python -m fancydocx``).
+
+  Single file:
+      fancydocx resume.docx                 -> resume.html (next to input)
+      fancydocx resume.docx -o out.html
+
+  Whole folder (recursive), mirroring the tree into an output dir:
+      fancydocx ./docs -o ./html
+      fancydocx ./docs -o ./html --workers 8
+"""
+from __future__ import annotations
+import argparse
+import concurrent.futures as cf
+import sys
+import time
+import traceback
+from pathlib import Path
+
+from . import __version__, convert_file
+
+
+def _iter_docx(root, pattern):
+    for p in sorted(Path(root).rglob(pattern)):
+        # Skip Word lock/temp files like ~$name.docx
+        if p.name.startswith("~$"):
+            continue
+        if p.is_file():
+            yield p
+
+
+def _one(in_path, out_path, include_headers, embed_fonts=False):
+    t0 = time.perf_counter()
+    try:
+        convert_file(in_path, out_path, include_headers=include_headers,
+                     embed_fonts=embed_fonts)
+        return (in_path, out_path, None, time.perf_counter() - t0)
+    except Exception as e:
+        return (in_path, out_path,
+                "".join(traceback.format_exception_only(type(e), e)).strip(),
+                time.perf_counter() - t0)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="fancydocx",
+        description="Convert fancy .docx files to a single self-contained HTML file.")
+    ap.add_argument("input", help="A .docx file or a folder containing .docx files")
+    ap.add_argument("-o", "--output", help="Output .html file (single) or output folder (batch)")
+    ap.add_argument("--glob", default="*.docx", help="Glob for batch mode (default: *.docx)")
+    ap.add_argument("--workers", type=int, default=1,
+                    help="Parallel worker processes for batch mode (default: 1)")
+    ap.add_argument("--no-headers", action="store_true", help="Skip header/footer rendering")
+    ap.add_argument("--embed-fonts", action="store_true",
+                    help="Inline locally-installed referenced fonts as @font-face "
+                         "(exact metrics everywhere, but several MB per file)")
+    ap.add_argument("--quiet", action="store_true", help="Only print a final summary")
+    ap.add_argument("--version", action="version", version="fancydocx %s" % __version__)
+    args = ap.parse_args(argv)
+
+    include_headers = not args.no_headers
+    inp = Path(args.input)
+    if not inp.exists():
+        ap.error("input not found: %s" % inp)
+
+    # ---- single file -------------------------------------------------
+    if inp.is_file():
+        out = Path(args.output) if args.output else inp.with_suffix(".html")
+        in_p, out_p, err, dt = _one(inp, out, include_headers, args.embed_fonts)
+        if err:
+            print("FAILED %s\n  %s" % (in_p, err), file=sys.stderr)
+            return 1
+        print("OK  %s -> %s  (%.2fs)" % (in_p, out_p, dt))
+        return 0
+
+    # ---- batch folder ------------------------------------------------
+    out_dir = Path(args.output) if args.output else inp / "_html"
+    files = list(_iter_docx(inp, args.glob))
+    if not files:
+        print("No files matching %r under %s" % (args.glob, inp))
+        return 0
+
+    jobs = [(f, out_dir / f.relative_to(inp).with_suffix(".html")) for f in files]
+    ok = fail = 0
+    total = len(jobs)
+    started = time.perf_counter()
+    print("Converting %d file(s) -> %s  (workers=%d)" % (total, out_dir, args.workers))
+
+    def report(res, i):
+        nonlocal ok, fail
+        in_p, out_p, err, dt = res
+        if err:
+            fail += 1
+            print("[%d/%d] FAILED %s\n    %s" % (i, total, in_p, err), file=sys.stderr)
+        else:
+            ok += 1
+            if not args.quiet:
+                print("[%d/%d] %s -> %s  (%.2fs)" % (i, total, in_p.name, out_p, dt))
+
+    if args.workers > 1:
+        with cf.ProcessPoolExecutor(max_workers=args.workers) as ex:
+            futs = {ex.submit(_one, f, o, include_headers, args.embed_fonts): idx
+                    for idx, (f, o) in enumerate(jobs, 1)}
+            for fut in cf.as_completed(futs):
+                report(fut.result(), futs[fut])
+    else:
+        for idx, (f, o) in enumerate(jobs, 1):
+            report(_one(f, o, include_headers, args.embed_fonts), idx)
+
+    print("\nDone: %d ok, %d failed, %d total in %.1fs"
+          % (ok, fail, total, time.perf_counter() - started))
+    return 1 if fail else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fancydocx/color.py

@@ -0,0 +1,128 @@
+"""
+Color resolution: hex parsing, theme-color lookup, and the tint/shade
+math Office applies to themed colors.
+
+Word colors come in three flavors:
+    * explicit sRGB      <w:color w:val="1F4E79"/>
+    * "auto"             <w:color w:val="auto"/>  (context default)
+    * theme reference    <w:color w:themeColor="accent1" w:themeShade="BF"/>
+
+For theme references, `themeTint`/`themeShade` are a hex fraction of 255
+applied to the *luminance* of the resolved theme color (HSL space) -- this
+is what Office actually does, not a naive per-channel scale, so the
+accent-bar shades come out matching.
+"""
+from __future__ import annotations
+import colorsys
+
+# Named highlight colors (<w:highlight w:val="yellow"/>).
+HIGHLIGHT = {
+    "black": "000000", "blue": "0000FF", "cyan": "00FFFF", "darkBlue": "00008B",
+    "darkCyan": "008B8B", "darkGray": "A9A9A9", "darkGreen": "006400",
+    "darkMagenta": "8B008B", "darkRed": "8B0000", "darkYellow": "808000",
+    "green": "00FF00", "lightGray": "D3D3D3", "magenta": "FF00FF", "red": "FF0000",
+    "white": "FFFFFF", "yellow": "FFFF00",
+}
+
+# themeColor attribute value -> clrScheme key.  The <w:clrSchemeMapping> in
+# settings.xml can remap tx1/bg1/tx2/bg2, handled in theme.py; this is the
+# default identity mapping.
+THEME_ALIAS = {
+    "dark1": "dk1", "light1": "lt1", "dark2": "dk2", "light2": "lt2",
+    "text1": "dk1", "background1": "lt1", "text2": "dk2", "background2": "lt2",
+    "accent1": "accent1", "accent2": "accent2", "accent3": "accent3",
+    "accent4": "accent4", "accent5": "accent5", "accent6": "accent6",
+    "hyperlink": "hlink", "followedHyperlink": "folHlink",
+}
+
+
+def normalize_hex(val):
+    """Return a 6-digit uppercase hex string, or None for auto/blank/invalid."""
+    if not val:
+        return None
+    v = val.strip().lstrip("#")
+    if v.lower() == "auto":
+        return None
+    if len(v) == 3:  # rare shorthand
+        v = "".join(c * 2 for c in v)
+    if len(v) != 6:
+        return None
+    try:
+        int(v, 16)
+    except ValueError:
+        return None
+    return v.upper()
+
+
+def hex_to_rgb(h):
+    return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
+
+
+def rgb_to_hex(rgb):
+    return "".join("%02X" % max(0, min(255, int(round(c)))) for c in rgb)
+
+
+def apply_tint_shade(hex6, tint=None, shade=None):
+    """
+    Apply themeTint / themeShade (hex byte, fraction of 255) to a base color,
+    operating on HSL luminance the way Office does.
+    """
+    if not hex6:
+        return hex6
+    r, g, b = (c / 255.0 for c in hex_to_rgb(hex6))
+    h, l, s = colorsys.rgb_to_hls(r, g, b)
+    if shade is not None:
+        try:
+            f = int(shade, 16) / 255.0
+            l = l * f
+        except ValueError:
+            pass
+    if tint is not None:
+        try:
+            f = int(tint, 16) / 255.0
+            l = l * f + (1.0 - f)
+        except ValueError:
+            pass
+    l = max(0.0, min(1.0, l))
+    r, g, b = colorsys.hls_to_rgb(h, l, s)
+    return rgb_to_hex((r * 255, g * 255, b * 255))
+
+
+def color_descriptor(el):
+    """
+    Build a color descriptor from any element carrying w:val / w:themeColor
+    (+ themeTint/themeShade).  Returns None if the element is absent.
+    """
+    if el is None:
+        return None
+    from .core import qn
+    return {
+        "val": el.get(qn("w:val")),
+        "theme": el.get(qn("w:themeColor")),
+        "tint": el.get(qn("w:themeTint")),
+        "shade": el.get(qn("w:themeShade")),
+    }
+
+
+def resolve(desc, theme, default=None):
+    """
+    Descriptor -> '#RRGGBB' (or `default` when it resolves to auto/none).
+
+    Precedence: when Word saves a theme-referenced color it ALSO bakes the
+    resolved sRGB into w:val (e.g. w:color w:val="9A92BF"
+    w:themeColor="accent5" w:themeTint="99"). That cached value is Word's own
+    integer-HSL math -- bit-exact by definition -- so prefer it and only
+    recompute from the theme when no explicit value exists (or it is 'auto').
+    """
+    if desc is None:
+        return default
+    hexv = normalize_hex(desc.get("val"))
+    if hexv:
+        return "#" + hexv
+    tname = desc.get("theme")
+    if tname and theme is not None:
+        base = theme.color(tname) or theme.color(THEME_ALIAS.get(tname, tname))
+        if base:
+            base = apply_tint_shade(base, desc.get("tint"), desc.get("shade"))
+            return "#" + base
+    return default

fancydocx/core.py

@@ -0,0 +1,201 @@
+"""
+Core helpers: OOXML namespaces, element utilities, and unit conversions.
+
+Word stores geometry in several units. Getting these conversions exactly
+right is the whole ballgame for 1:1 layout parity:
+
+    * twips      = 1/20 point = 1/1440 inch   (margins, indents, table widths)
+    * EMU        = 1/914400 inch              (DrawingML: image/shape geometry)
+    * half-point = 1/2 point                  (font sizes: <w:sz w:val="24"/> = 12pt)
+    * eighth-pt  = 1/8 point                  (border widths)
+    * pct50      = 1/50 percent               (some width/shade values)
+
+CSS reference DPI is 96, so 1in = 96px and 1pt = 96/72 px = 4/3 px.
+We emit lengths in px (predictable box math) and font metrics in pt
+(matches Word's typographic intent). Both resolve to the same physical
+scale, so mixing them is safe.
+"""
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Namespaces
+# ---------------------------------------------------------------------------
+NS = {
+    "w":    "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
+    "r":    "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+    "a":    "http://schemas.openxmlformats.org/drawingml/2006/main",
+    "wp":   "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+    "pic":  "http://schemas.openxmlformats.org/drawingml/2006/picture",
+    "wps":  "http://schemas.microsoft.com/office/word/2010/wordprocessingShape",
+    "wpg":  "http://schemas.microsoft.com/office/word/2010/wordprocessingGroup",
+    "wpc":  "http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas",
+    "mc":   "http://schemas.openxmlformats.org/markup-compatibility/2006",
+    "v":    "urn:schemas-microsoft-com:vml",
+    "o":    "urn:schemas-microsoft-com:office:office",
+    "w10":  "urn:schemas-microsoft-com:office:word",
+    "w14":  "http://schemas.microsoft.com/office/word/2010/wordml",
+    "wp14": "http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing",
+    "rel":  "http://schemas.openxmlformats.org/package/2006/relationships",
+    "ct":   "http://schemas.openxmlformats.org/package/2006/content-types",
+}
+
+
+def qn(name: str) -> str:
+    """'w:val' -> '{http://.../main}val'  (Clark notation for ElementTree)."""
+    prefix, local_name = name.split(":", 1)
+    return "{%s}%s" % (NS[prefix], local_name)
+
+
+def local(tag) -> str:
+    """Strip the namespace from a Clark-notation tag: '{ns}p' -> 'p'."""
+    if tag is None or not isinstance(tag, str):
+        return ""
+    return tag.rsplit("}", 1)[-1]
+
+
+# ---------------------------------------------------------------------------
+# Element access helpers (all namespace-aware, all None-safe)
+# ---------------------------------------------------------------------------
+def get(el, name: str, default=None):
+    """Attribute lookup by prefixed name, e.g. get(el, 'w:val')."""
+    if el is None:
+        return default
+    v = el.get(qn(name))
+    return default if v is None else v
+
+
+def find(el, path: str):
+    """First descendant matching an ElementTree path using our NS map."""
+    if el is None:
+        return None
+    return el.find(path, NS)
+
+
+def findall(el, path: str):
+    if el is None:
+        return []
+    return el.findall(path, NS)
+
+
+def child(el, name: str):
+    """First *direct* child with the given prefixed tag."""
+    if el is None:
+        return None
+    want = qn(name)
+    for c in el:
+        if c.tag == want:
+            return c
+    return None
+
+
+def children(el, name: str | None = None):
+    """Direct children, optionally filtered by prefixed tag."""
+    if el is None:
+        return []
+    if name is None:
+        return list(el)
+    want = qn(name)
+    return [c for c in el if c.tag == want]
+
+
+def bool_attr(val, default=False):
+    """Interpret an OOXML on/off value ('1','0','true','false','on','off')."""
+    if val is None:
+        return default
+    return str(val).lower() not in ("0", "false", "off", "no")
+
+
+def toggle(el, name: str):
+    """
+    Toggle property such as <w:b/> or <w:b w:val="0"/>.
+    Returns True (on), False (explicitly off), or None (absent).
+    """
+    if el is None:
+        return None
+    sub = child(el, name)
+    if sub is None:
+        return None
+    return bool_attr(sub.get(qn("w:val")), default=True)
+
+
+def int_val(el, name: str, attr: str = "w:val", default=None):
+    sub = child(el, name)
+    if sub is None:
+        return default
+    raw = sub.get(qn(attr))
+    if raw is None:
+        return default
+    try:
+        return int(round(float(raw)))
+    except (TypeError, ValueError):
+        return default
+
+
+def str_val(el, name: str, attr: str = "w:val", default=None):
+    sub = child(el, name)
+    if sub is None:
+        return default
+    v = sub.get(qn(attr))
+    return default if v is None else v
+
+
+# ---------------------------------------------------------------------------
+# Unit conversions -> CSS
+# ---------------------------------------------------------------------------
+PX_PER_INCH = 96.0
+PT_PER_INCH = 72.0
+EMU_PER_INCH = 914400.0
+TWIPS_PER_INCH = 1440.0
+PT_TO_PX = PX_PER_INCH / PT_PER_INCH  # 4/3
+
+
+def _num(x):
+    try:
+        return float(x)
+    except (TypeError, ValueError):
+        return None
+
+
+def twips_to_px(v):
+    v = _num(v)
+    return None if v is None else v / TWIPS_PER_INCH * PX_PER_INCH  # v/15
+
+
+def emu_to_px(v):
+    v = _num(v)
+    return None if v is None else v / EMU_PER_INCH * PX_PER_INCH  # v/9525
+
+
+def halfpt_to_pt(v):
+    v = _num(v)
+    return None if v is None else v / 2.0
+
+
+def eighthpt_to_px(v):
+    """Border widths are in 1/8 pt."""
+    v = _num(v)
+    return None if v is None else (v / 8.0) * PT_TO_PX
+
+
+def pt_to_px(v):
+    v = _num(v)
+    return None if v is None else v * PT_TO_PX
+
+
+def px(v, nd: int = 2):
+    """Format a px number compactly ('12.0' -> '12', '12.500' -> '12.5')."""
+    if v is None:
+        return None
+    v = round(float(v), nd)
+    if v == int(v):
+        return "%dpx" % int(v)
+    return ("%.*f" % (nd, v)).rstrip("0").rstrip(".") + "px"
+
+
+def pt(v, nd: int = 2):
+    if v is None:
+        return None
+    v = round(float(v), nd)
+    if v == int(v):
+        return "%dpt" % int(v)
+    return ("%.*f" % (nd, v)).rstrip("0").rstrip(".") + "pt"